Memoria: Git-style version control for AI agent memory

The problem Memoria targets: memory that cannot be rolled back

Most agent memory today is append-only. A retrieval layer writes a fact, a preference or a decision into a vector store, and the next session reads it back. When that fact is wrong, stale, or contradicted by a later statement, the usual remedy is to delete rows by hand or to widen the retrieval window and hope the model sorts it out. There is no diff, no branch, and no point to return to.

Memoria's README frames the project around exactly that gap. It calls itself a persistent memory layer with Git-level version control, and the tagline is "Snapshot, Branch, Merge, Rollback, for memory, not code." The audience is not a single developer keeping a scratchpad; it is anyone running an agent that accumulates state across conversations, where a corrupted memory persists silently and affects every later answer.

The project is written in Rust and licensed Apache-2.0. It is not archived, and the last push to the default branch was on 2026-09-10. The most recent release listed is v0.5.1 from 2026-08-26, preceded by v0.4.0 and v0.3.3, so the version cadence over 2026 has been roughly quarterly with a patch in between.

How the Git-for-Data layer works on MatrixOne

The mechanism is not reimplemented in Memoria itself. The README states that snapshots, branches, merges and time-travel rollback are "powered by MatrixOne's native Copy-on-Write engine," and the project cites an arXiv paper, Version Control System for Data with MatrixOne, describing how immutable storage and MVCC make clone, branch/tag, diff, merge and revert practical at terabyte scale without loading whole datasets into memory.

That division of labour matters when you evaluate the project. The versioning semantics are a database feature exposed through an agent-facing API, not a bespoke snapshot format layered over a vector index. Zero-copy branching is claimed on the strength of the storage engine underneath.

On top of that storage, Memoria adds retrieval and governance. The README describes vector plus full-text hybrid search, so memories are found by meaning and by keyword rather than by vector similarity alone. It also describes self-governance: automatic contradiction detection, quarantine of low-confidence memories, and an audit trail that attaches a snapshot and provenance chain to every mutation.

The repository layout reflects the split: a memoria/ directory holding the Rust service and its Dockerfile, a config/matrixone directory mounted read-only into the database container, sdk/ and plugins/ for client integrations, plus skills/ and benchmarks/ at the top level. The docker-compose.yml starts MatrixOne, an init container that fixes ownership of the data and log volumes, and the API container on port 8100 by default.

Installing Memoria and getting a first memory write

There are two documented paths. The cloud path needs no Docker and no local database: sign up at thememoria.ai for a token, run the install script, then initialise the project and choose Remote mode when prompted.

curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash
cd your-project
memoria init -i   # Select "Remote" mode, paste your token

After that, the README says to restart your AI tool and ask it "Do you have memory tools available?" If the MCP server registered, the agent should report memory tools.

The self-hosted path brings up MatrixOne and the API with Docker Compose, then installs the same CLI and initialises in Embedded mode.

git clone https://github.com/matrixorigin/Memoria.git
cd Memoria
docker compose up -d
curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash
cd your-project
memoria init -i   # Select "Embedded" mode

Before running Compose, copy .env.example to .env and fill it in. The template requires MEMORIA_MASTER_KEY, which it says to generate with openssl rand -hex 32, and DOCKER_UID and DOCKER_GID, which you get from id -u and id -g. The .env.example notes that the default Docker image does not include local-embedding support, so a Docker deployment should point at an HTTP embedding provider or rebuild Memoria with that feature enabled. The template's worked example uses an OpenAI-compatible endpoint.

MEMORIA_EMBEDDING_PROVIDER=openai
MEMORIA_EMBEDDING_MODEL=BAAI/bge-m3
MEMORIA_EMBEDDING_DIM=1024
MEMORIA_EMBEDDING_API_KEY=your-embedding-api-key-here
MEMORIA_EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1

The Makefile wraps the common operations: make up starts MatrixOne and the API, make status shows service state, make health checks the API /health endpoint, and make reset stops everything, deletes the data and restarts. If you prefer the OpenClaw plugin route, the README shows installing @matrixorigin/memory-memoria through openclaw plugins install, enabling it, then running openclaw memoria setup with --mode cloud and openclaw memoria health to confirm.

Where Memoria is the wrong tool

The first limitation is environmental. Self-hosting means running MatrixOne, an init container and the API, with the database exposed on port 6001 by default. That is a real service to operate. If you wanted a library you import and forget, this is not it.

The second is the embedding dependency. The .env.example is explicit that the default Docker image does not include local-embedding support, so the "no data leaves your machine" property advertised in the README's feature grid depends on either building Memoria with that feature or accepting an HTTP embedding provider. The template does document a local option with all-MiniLM-L6-v2 at 384 dimensions, but it also warns that the model is roughly a 900MB download on first use and that HF_HUB_OFFLINE and TRANSFORMERS_OFFLINE should only be set to 1 after the model is cached. The privacy claim and the default deployment therefore do not line up without extra work.

Third, the versioning model is a poor fit for short-lived state. If your agent only needs a scratchpad for the current conversation, snapshots, branches and provenance chains are overhead with no payoff. The value appears when memory outlives a session and multiple sessions read it.

Finally, the README does not document a rollback procedure in the Quick Start, and it does not describe how merge conflicts between branches are surfaced to a user. The arXiv paper is cited as the foundation for the storage-level operations, so the semantics of merge and revert are best checked there and in the API reference rather than inferred from the marketing copy.

Memoria against Letta, Mem0 and plain RAG

The README's own comparison table puts Memoria next to Letta, Mem0 and traditional RAG on five axes: version control, isolated experimentation, audit trail, semantic retrieval, and self-governance. It scores the alternatives as file-level or no version control, manual data duplication for experiments, limited logging, vector-only retrieval, and manual cleanup.

The real difference is where state lives. A conventional RAG memory is a collection of embeddings plus whatever metadata you attach; changing it means rewriting rows. Letta and Mem0, as characterised in that table, give you memory management but not a branching history of it. Memoria's claim is that the history is the product: you branch, validate, then merge, and every mutation carries a snapshot and provenance.

That framing is worth taking seriously but also worth testing. The comparison is the project's own, and the table gives no thresholds or workloads behind the labels. If you are choosing between these tools, the deciding question is whether you have ever needed to answer "what did the agent believe last Tuesday, and why." If yes, a versioned store is the right shape. If your memory is small enough to inspect by hand, the extra machinery is not earning its place.

Licence, maintenance and what an upgrade costs

Memoria is Apache-2.0, which permits commercial use and modification, and the repository ships the LICENSE file at the top level. The project also depends on MatrixOne, which is a separate component with its own licence; running the Docker Compose stack means you are operating both, so review the database's terms alongside Memoria's. Nothing here is legal advice.

On maintenance, the observable facts are a last push on 2026-09-10 and releases v0.3.3 in April 2026, v0.4.0 in May 2026, and v0.5.1 in August 2026. There is a CHANGELOG.md and a cliff.toml, which suggests release notes are generated rather than written by hand, so the changelog is the place to look before upgrading. The .mergify.yml file indicates automated merge handling on pull requests.

The upgrade cost you should plan for is schema and storage compatibility. Because versioning is delegated to MatrixOne, a Memoria upgrade may pull a different MatrixOne image: the Compose file defaults MATRIXONE_IMAGE to matrixorigin/matrixone:latest, and the data directory is bind-mounted from ${MATRIXONE_DATA_DIR:-./data/matrixone}. Pinning that image to a known tag rather than latest is the difference between a controlled upgrade and a surprise against your existing data. The Makefile's make reset and make clean both delete data, so neither belongs in an upgrade path.

What to check before you adopt it

Start with the embedding path, because it determines both your privacy posture and your network dependencies. Decide whether you will rebuild the image with local-embedding support or point MEMORIA_EMBEDDING_BASE_URL at an HTTP provider, and check whether your provider's model dimension matches the MEMORIA_EMBEDDING_DIM you set. The template also documents a multi-endpoint round-robin mode where MEMORIA_EMBEDDING_ENDPOINTS supersedes the base URL and API key, and it requires every endpoint to serve the same model; if you plan to use it, confirm your providers meet that constraint.

Second, verify the agent integration end to end. The README's test is a single question to the agent after a restart, which tells you the MCP server is visible but not that writes and reads behave as expected. Since the Quick Start does not document a rollback command, exercise the snapshot and branch operations yourself against a throwaway database before trusting them with production memory.

Third, check the deployment defaults. The API listens on 8100 and MatrixOne on 6001 unless you override API_PORT and MATRIXONE_PORT, and the Compose file sets TZ to Asia/Shanghai in the database container, which you may want to change for log correlation. Set MEMORIA_MASTER_KEY to a real value from openssl rand -hex 32 rather than leaving the placeholder.

Editorial conclusion

Adopt Memoria if your agent's memory is long-lived, shared across sessions, and you need to reverse a bad write or test a change in isolation before it reaches production. Skip it if you only need a scratchpad inside one conversation, or if you cannot run MatrixOne alongside it. Before committing, verify which embedding provider your deployment will accept, since the default Docker image does not ship local-embedding support, and confirm that the MCP server registers correctly in your agent after memoria init -i.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. matrixorigin/memoria on GitHub
3. Project website
4. README
5. Releases