Memora: an MCP memory layer for AI agents that absorbs, supersedes and retrieves

The session boundary problem Memora targets

An agent that writes code has no memory past the context window. Every new session re-derives the same conventions, re-asks which migration was already applied, and re-opens issues that were closed last week. Memora is aimed at that gap. It is an MCP server, so the client spawns it or connects to it over HTTP, and the agent gets tools for storing facts, retrieving them semantically, and following how a fact changed over time.

The intended user is someone running agentic coding tools such as Claude Code or Codex on a codebase over weeks, not someone prototyping a single prompt. The README frames the workflow as absorb then digest: agent work is absorbed into a graph, and memory_digest(topic) returns relevant memories, open TODOs and issues, related edges and source IDs in one call. That bundling is the interesting part. A plain vector store returns text; this returns text plus the open work items attached to it.

Absorb, supersession lineage and the digest call

Storage is SQLite, with optional sync to S3, R2 or D1. On top of that sit three mechanisms that distinguish Memora from a flat RAG index.

Absorb is the write path. Facts are fed in and an LLM classifies each against the existing store: duplicate, update, contradiction, related or new. Duplicates are skipped, relations are linked, related facts are consolidated. The README documents a dry_run preview, which matters because classification errors are otherwise silent.

Supersession lineage is the second mechanism. An update does not delete the old memory; it supersedes it. Retrieval follows the chain to the current version by default, and the follow mode controls how far back it walks: active, latest or full_history. This is a real design commitment. You pay storage and query complexity to keep the history, and you get the ability to ask what a fact replaced.

The third is the digest. memory_digest(topic) is a single retrieval that bundles memories, open TODOs and issues, related edges and source IDs. Source IDs are the traceability hook: a returned memory can be traced to the work that produced it.

Around these sit the supporting tools. Semantic search runs on TF-IDF, sentence-transformers or OpenAI embeddings. Memory linking adds typed edges, importance boosting and cluster detection. Structured documents are stored as fragment trees (claims, plan items, references, risks) with guards against accidental delete, merge or absorb of a fragment. A knowledge graph renders through Mermaid with cluster overlays, and there is a live graph HTTP server with a cloud-hosted D1/Pages option.

Installing memora-mcp from PyPI and wiring it to an MCP client

The local path is a stdio child process the client spawns. Install the package first. Note the name: the PyPI package is memora-mcp, and the README warns that bare memora on PyPI is an unrelated project.

pip install memora-mcp

Local embeddings are optional and pull PyTorch, which the README puts at roughly 2GB. Install them only if you want offline embedding.

pip install "memora-mcp[local]"

To track the development branch instead of the release, the README gives the git form.

pip install "git+https://github.com/agentic-box/memora.git"

The console script exposed by pyproject.toml is memora-server, and the README says to spawn it from .mcp.json with "command": "memora-server". After that, the first real use is an absorb with the preview flag on, so you can see how the classifier treats your facts before anything is written. The README documents dry_run as the preview mechanism but does not show a full example call, so check the tool schema your client lists before running it.

Running Memora as a container service on Apple silicon

The container path is not a convenience wrapper around the pip install. The README states it plainly: if you are running Memora as a service, the container path is the install. It is an HTTP service you start with up, and with MEMORA_DATABASES set it serves multiple stores from one process.

The default runtime is Apple's container CLI, and every container operation in scripts/memora-instance.sh (build, up, status, logs, down) goes through $MEMORA_CONTAINER_BIN, which defaults to container. One caveat is spelled out in the README: the generated proxy process does not honour that variable and hardcodes container list.

The platform requirement is the constraint that will stop most people. Apple's container CLI needs a Mac with Apple silicon running macOS 26, and Apple does not support older macOS versions for it. Before the first build you start the runtime, which also installs a kernel if none is configured.

container system start

Then clone the repository and copy the instance template. It ships with INSTANCE=myinstance so the later build, up and proxy lines match without renaming.

cp instances/example.env instances/myinstance.env

Edit PORT and one backend in that file: STORAGE_URI, VOLUME or MEMORA_DATABASES. The README then says to create the credential file and install the proxy the LaunchAgent will run. Read the LaunchAgent section carefully, because the README flags a supervision gap: the LaunchAgent supervises the proxy, not the container, so after a host restart the listener can come back while its upstream is still stopped.

The mcp dependency pin and what it costs you

pyproject.toml pins mcp>=1.27,<1.28, and the comment above it explains why: mcp 2.0.0 removed mcp.server.fastmcp, which memora/server.py depends on, and 1.27.0 is the only release the MEMORA_TOOL_PROFILE attestation path was verified against. The maintainers state that claiming compatibility with 27 untested minor lines would be worse than a tight range.

That is an honest position and a real operational cost. If another MCP server in the same environment requires a newer mcp, you have a dependency conflict with no upgrade path until the attestation is re-run. The comment names the test to re-run, tests/test_tool_profile.py, which is at least a documented escape hatch.

The broader limitation is that the intelligence in absorb is an LLM call. Classification into duplicate, update, contradiction, related or new is a judgement, and a wrong judgement writes a wrong graph. Supersession lineage limits the damage because the old memory is still there, but a misclassified contradiction can leave retrieval following the wrong branch. The dry_run preview exists for this reason. Use it on a representative batch before letting an agent absorb unsupervised.

Where Memora is the wrong tool

Memora is not a document search engine. If your corpus is static PDFs or a wiki and you never write back, a plain RAG pipeline over a vector database does the job with fewer moving parts and no LLM in the write path.

It is also the wrong choice for a single-session task. The absorb and digest cycle assumes facts accumulate across sessions; on a one-off run you pay the setup, the embedding model and the classification latency for nothing.

There is a platform boundary too. The container service requires Apple silicon and macOS 26, so a Linux server deployment is not the documented path. The Dockerfile exists and installs the package with MEMORA_TRANSPORT=streamable-http, MEMORA_HOST=0.0.0.0, MEMORA_PORT=8000 and MEMORA_DB_PATH=/data/memora.db, but the README's service instructions are written around Apple's container CLI. Treat the Dockerfile as a starting point you validate yourself, not as a supported deployment.

Finally, the README does not document rollback for an absorb that wrote bad data. Supersession keeps the old version, but reverting a batch is not described.

How this differs from a plain vector store or a notes MCP

Compare Memora to the common alternative: an MCP server that exposes a vector index over a folder of notes. The difference is the write path. A notes-plus-embeddings server stores whatever you give it and retrieves by similarity. It has no notion of a fact replacing another fact, so over months you accumulate near-duplicates and contradictory statements with equal weight in retrieval.

Memora puts an LLM between the write and the store to classify the incoming fact against what is already there. That is the actual architectural difference, and it is also where the risk sits: a classifier that is wrong writes a graph that is wrong, and the graph is what later retrieval follows.

The second difference is lineage. A vector store can return the old and new text; it cannot tell you which one is current. The follow modes (active, latest, full_history) are a retrieval-time answer to that question, and they only exist because supersession is a first-class record rather than an overwrite. If your facts never change, this machinery is overhead. If they change weekly, it is the part that keeps retrieval honest.

Editorial conclusion

Adopt Memora if you run Claude Code, Codex or another MCP client across many sessions and want facts to survive the session boundary with a lineage you can inspect. Skip it if you want a hosted memory service with a support contract, or if you are not on Apple silicon and macOS 26 for the container path. Before trusting a store, run absorb with dry_run on a small batch and check the classification, then try memory_digest on a topic you know the answer to.

Frequently asked questions

Official sources

1. agentic-box/memora on GitHub
2. Issues
3. License: MIT
4. README
5. Releases