Documentation

Overview

NMAFC is an open-source memory layer for LLM agents. It is the engine behind OpenLoft Memory, and you can run it yourself — the whole thing is Apache-2.0.

It exists to solve one problem: assistants that forget. Rather than stuffing raw transcripts into a vector database and paying for repeated summarisation passes, NMAFC compacts each turn into atomic facts with resolved absolute dates at write time, lets unused facts fade on a decay curve, and retrieves through a fusion of five ranked channels.

What you get

Install

Python 3.11 or newer. Two supported routes — a local library, or the HTTP server.

As a library

git clone https://github.com/blok-hamster/nmafc.git
cd nmafc

# a virtualenv is worth it; the engine pins LanceDB tightly
uv venv && source .venv/bin/activate     # or: python -m venv .venv && source .venv/bin/activate

# pick the extras you need
uv sync --extra all                      # or: pip install -e ".[llm]"
uv run pytest -q                         # 833 tests, about 30s, no network

As a server

# the engine ships its own server: an explorer UI plus a REST API
uv run nmafc-web --host 127.0.0.1 --port 8000

# then read the interactive API surface
open http://127.0.0.1:8000/docs

Bind to localhost unless you have put authentication in front of it. The bundled server ships with its explorer endpoints open — see the security note below before exposing it.

Quick start

The shortest useful path. Construct a memory, give it a turn, recall what it kept.

import asyncio
from nmafc.wrapper import NeuromorphicMemory
from nmafc.integration.factory import create_llm_provider, create_embedding_provider

async def main():
    memory = NeuromorphicMemory(
        llm_provider=create_llm_provider("openai/gpt-4o-mini"),
        embedding_provider=create_embedding_provider("openai/text-embedding-3-small"),
    )

    # one turn: recall, generate with the facts injected, then write what it learned
    reply = await memory.process_turn("I run a bike shop in Lisbon.")
    reply = await memory.process_turn("Which city am I in?")

    # read-only retrieval — performs no writes and no reinforcement
    result = await memory.recall("where is the shop?")
    print(result.context)

    memory.close()

asyncio.run(main())

Synchronous code

from nmafc.wrapper import SyncNeuromorphicMemory

memory = SyncNeuromorphicMemory.from_config()
memory.process_turn_sync("I prefer Postgres over Mongo.")
context = memory.recall("what database do I prefer?")
memory.close()

Talking to it over HTTP

# /v1/memories is Mem0-shaped, so migrating from Mem0 is a base URL and a key
curl -X POST http://127.0.0.1:8000/v1/memories \
  -H "Authorization: Bearer $NMAFC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"I moved to Porto in March."}]}'

curl -X POST http://127.0.0.1:8000/v1/memories/search \
  -H "Authorization: Bearer $NMAFC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"where did I move?"}'

Choosing an integration

Four ways in. They reduce to one decision: how much of your request loop do you want to hand over.

MCP — coding agents

The zero-code-change path. The MCP server exposes six tools over stdio, so any MCP host can use NMAFC without your writing integration code.

Claude Code / Claude Desktop

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/nmafc", "nmafc-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "NMAFC_HOT_URI": "/path/to/nmafc/data/lancedb",
        "NMAFC_COLD_URI": "/path/to/nmafc/data/cold.db"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/nmafc", "nmafc-mcp"]
    }
  }
}

Codex uses the same JSON shape in .codex-mcp.json. Any other MCP host takes the same command and environment.

OpenAI drop-in

If your stack is already OpenAI-shaped, MemoryOpenAI wraps an existing client and interposes memory on chat completion. It remembers on the way out and recalls on the way in.

import openai
from nmafc.proxy import MemoryOpenAI
from nmafc.wrapper import SyncNeuromorphicMemory

client = MemoryOpenAI(
    openai.OpenAI(api_key="sk-..."),
    memory=SyncNeuromorphicMemory.from_config(),
)

# extra keyword arguments are consumed by the wrapper, not sent upstream
reply = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Remind me what I said about the lease."}],
    memory_conversation_id="lease-thread",
).choices[0].message.content

Agent hosting

OpenLoft deploys and operates agent harnesses for you. Every one of them reads the same memory — which is the point, not a side effect.

What you get

• A provisioned container with its own subdomain and TLS.
• Secrets pulled at runtime from a per-tenant vault, never as plain environment variables.
• Health checks and automatic restart if the process dies.
• An agent-to-agent gateway so agents in the same tenant can pair and collaborate.
• WireGuard or overlay networking onto the shared memory service.

Hosted memory

The same engine, operated by us. Multi-tenant on our infrastructure, or deployed inside yours.

Enterprise controls — current state

Data residency

Content reaches whichever LLM and embedding providers you configure, even in a sovereign deployment. For a genuinely air-gapped setup, use a local model and a local embedder so nothing crosses the boundary. This is worth raising with a data protection officer early rather than at audit.

Metered LLM access

Use our model keys with per-request metering, or bring your own. Either way the same proxy fronts the provider.

• Platform credits: one balance, metered per request, floored at zero rather than allowed to go negative.
• Bring your own key: your provider credentials are stored per agent and used directly.
• Per-agent switching: change an agent between platform and your own key without redeploying.
• One proxy in front of every supported provider, so changing provider is a configuration change.

API endpoints

Scope

Every record is scoped by agent_id and conversation_id, passed as the X-Agent-Id and X-Conversation-Id headers or in the request body. One engine instance is bound to one pair, so a memory object cannot be used to read a different scope — it raises rather than widening.

CLI

nmafc start        # serve the API and the explorer UI
nmafc init         # interactive setup wizard
nmafc chat         # terminal chat against your memory
nmafc eval locomo summarise   # regenerate the benchmark table from committed data

Configuration

A TOML file, or environment variables. Environment variables win.

[storage]
hot_uri = "./data/lancedb"      # working set
cold_uri = "./data/cold.db"     # append-only archive
embedding_dim = 1536
agent_id = "default"
conversation_id = "default"

[llm]
provider_model = "openai/gpt-4o-mini"

[embedding]
provider_model = "openai/text-embedding-3-small"

[decay]
# how long a working fact stays active. 0.005 gives roughly a 139-turn half-life.
lambda_active_context = 0.005
rerank_top_k = 20      # facts injected into context
hydrate_top_k = 5      # source turns attached behind them

Providers

fastembed is worth knowing about if conversation content must not leave your boundary: it runs a small embedding model locally with no network call.

How it works

A turn goes through the write path; a question goes through the read path.

Write

• The turn is sent to your model with a tool-calling schema, which returns an assistant reply and a set of atomic facts in the same response.
• Relative dates are resolved to absolute calendar timestamps at this point, so "last week" stops being ambiguous the moment it is stored.
• Each fact is given a memory type and a validity interval. A fact that contradicts an existing one supersedes it rather than accumulating.
• Facts are written to the archive, then the working set. The archive is never mutated — superseded and invalidated rows are marked, not removed.

Read

• The question is turned into an embedding and retrieved from the working set, the archive, and along entity links — up to two hops.
• Results from each channel are fused by reciprocal rank fusion, which combines ranked lists without needing their scores to be comparable.
• The top facts and the turns behind them are assembled into the context, verbatim and compacted, and handed to the model.
• Retrieving strengthens what was retrieved, and the turn counter advances so everything fades slightly.

Benchmarks

On the LoCoMo benchmark of 1,985 conversational questions, both arms answering each question in the same execution window. You can regenerate the table yourself with one command and no API credentials.

python scripts/benchmarks/results/paired_2026_09_10/summarise.py

LoCoMo is licensed CC BY-NC 4.0. Its licence is non-commercial, so the aggregate numbers are reported here for reference and the dataset is not redistributed as a commercial evaluation harness.

Limitations

If you are evaluating this, read this section before you build on it. Every item is a measured or documented limitation, not a hedge.