You want to try an architecture with a different persistence layer. In an ordinary memory system the experimental conclusions land in the same store and stay there forever. In Memoir a separate branch is created for them:

Did not like the experiment - delete the branch. Turned out useful - merge it into the main line. The point is that the main memory was never contaminated with temporary conclusions. This is exactly where the usual "long-term memory" metaphor stops working: Memoir holds several possible lines of memory and lets you choose explicitly which one becomes shared.

Addresses instead of random identifiers

An ordinary vector database stores records roughly like this:

Memoir gives memory a structure:

The benefit is not cosmetic. If the path is known, the record is fetched directly - no semantic search, no model call:

This is one of the project's main ideas: retrieval need not start with vectors. If the agent understands the structure of memory, an exact tree lookup is faster, cheaper and more predictable.

Where do the paths come from? The system has a taxonomy, and it works two ways: a ready-made scheme of known paths plus dynamic expansion through a model. The bundled set ships in the repository and holds 275 paths across seventeen categories, and it is composed with an explicit tilt towards coding agents - context, workflow, preferences.coding, knowledge and debugging are the densest, while general-purpose sections such as profile and relationships are retained but deliberately thinned.

When you write a memory without naming a path, the classifier picks one. When the path is known in advance, you name it by hand and no model is called at all.

What Memoir is assembled from

The components are separated and wired through dependency injection, so the classifier or the search engine can be replaced without touching storage.

Underneath the storage lies the ProllyTree library. What matters to a user is not the tree itself but the properties Memoir gains on top of it: sorted hierarchical keys, fast prefix lookups, content addressing through hashes, versions and snapshots, branching and merging, cryptographic verifiability. The documentation claims SHA-256 integrity for operations and a Git-like change history over the store. Altogether memory becomes less like a table of notes and more like a small versioned database with a HEAD and a history.

Installation

The project is published on PyPI as memoir-ai:

The authors recommend uv as the faster route:

The current release is 0.2.4, it needs Python 3.10 or newer, and the licence is Apache 2.0.

Your first store in a few minutes

Three things are worth noticing. memoir new creates a versioned store. The -p flag sets the semantic path by hand, so classification needs no model. And get is a direct lookup by a known key, with no semantic search involved.

When the classifier picks the path

If the path is unknown, the classifier chooses it - and here a model is needed:

By default claude-haiku-4-5 is used, but the model can be swapped:

The order of precedence is: the --model flag, then the MEMOIR_LLM_MODEL variable, then the default.

Three different ways to read memory

The first is when the path is already known:

The cheapest option: no model, no search. The documentation cites a typical latency under 10 ms.

The second is looking at the structure:

This is not a model summarising text but a view of the taxonomy itself: which branches exist and how many keys are in them.

The third is an ordinary human question:

There are single and tiered modes here, both involving a model. But for agent integrations the project promotes a different order: first summarize, then the calling model picks the paths it needs, and then it does a get. That way no second model is needed inside the memory system at all.

Branches: an experiment that does not spoil the main line

The experimental branch's memory stays separate. If the decision holds up - merge it:

Since version 0.2.1 there is another convenience - choosing the branch per call, without moving HEAD all the time. That is especially useful when several agents work on one project:

Reading from one branch does not see the working memory of another until you merge it explicitly. A reviewer can write down suspicions and hypotheses in its own branch without turning them into truth for whoever writes the code.

A handy detail: if the named branch does not exist yet, it is created automatically - no separate command is needed to set it up in advance.

Commits, a fact's origin, and time travel

By default operations are committed automatically, but through the Python API several related changes can be gathered into one logical transaction:

That makes the memory's history meaningful: one commit is one decision or one finished operation, not a random set of lines.

Next comes what ordinary memory lacks the most:

The idea of blame is the same as in Git: found strange knowledge - trace which change introduced it. For an agent in production that is fundamental: a memory error becomes debuggable. Not "the model recalled something", but "this fact appeared in this commit".

Debugging across time grows from the same root. The documentation describes a scenario where an agent started making bad decisions after its memory state was corrupted:

You can compare the state before and after the error appeared, find the point of contamination and restore a clean version. It resembles debugging configuration: instead of deleting suspicious records by hand, you first work out when exactly the behaviour changed.

Conflicts and memory types

What happens if two facts land on the same path? In early versions such a conflict turned into either an overwrite or endless text appending. Now a second-generation schema with dated facets is used: one semantic key can hold several dated entries.

The interesting part is that you usually do not pick a strategy by hand - the memory type sets it. From the top level of the taxonomy the system determines the record's cognitive type.

The logic is clear: "the deploy happened at 14:00" is an event and belongs in the history. But "the current task is fixing auth" is working memory, and the old value can safely be replaced.

The automation can be overridden: the MEMOIR_MERGE_POLICY variable forces a strategy for every write, regardless of which cognitive type a path falls under.

Documents: watch, search and the role of vectors

Since 0.2.1 there is a separate system for ingesting existing files:

Files are parsed through MarkItDown. The pipeline hashes them, skips unchanged documents, builds a summary and chunks, files them into the taxonomy and indexes them for search. In the current version the pipeline targets relatively short documents: the default guard is 100,000 bytes per file and no more than 10 chunks per document.

Does that mean Memoir is against vector databases? No, and the nuance matters. The project's idea is not to make vectors the single source of truth. For short memory, semantic paths, the classifier, exact key lookups and taxonomy navigation do the work - a vector index is not required for a plain remember. For documents, though, watch creates chunks and a separate versioned text-and-vector index, which is what memoir search uses. So vector search here is a useful tool, not the whole model of memory.

The MCP server and connecting agents

MCP support installs as a separate extra:

Or with nothing installed permanently:

That config works as a base for Claude Desktop, Cursor, Cline and Windsurf. And the server exposes not only writing and searching but version-control tools too - branches, checkout, commits. There is a remote mode as well:

The endpoint will be available at /mcp. For an internet-facing install the documentation plainly requires TLS and authentication on a reverse proxy.

Claude Code deserves a separate mention - it is the most complete of the integrations. It installs from inside the tool:

The plugin adds slash commands, automatic recall before work, auto-capture of important facts after a turn, project onboarding, branch sync, a status line and a web UI launcher. The commands are these:

It works through session events: at start it injects the memory state, on prompt submission it suggests a suitable recall, and when a turn ends it asynchronously extracts durable facts. Architecturally that is done right - reading happens before the answer, and writing is deferred to the end of the turn so it does not hold the user up.

Codex has its own plugin, not just the shared MCP server:

Then the plugin is installed through /plugins. But Codex has a limitation at the time of checking: marketplace plugins install skills, while lifecycle hooks require separate installation into the user's hooks file and trusting through /hooks. So there is no symmetry with Claude Code yet: there the integration is seamless, here part of the wiring is manual.

Memoir also works as a memory provider for personal assistants. In Hermes the plugin handles auto-capture, remembering, recall, forgetting and sync, and it mirrors conversation forks into Memoir branches. The OpenClaw integration is built the same way: the plugin takes the memory slot, keeps durable facts in a versioned store, and injects what is relevant before the prompt. The scope setting there is interesting - memory can be isolated per chat or profile, so a fact from a private conversation does not surface in another channel.

Seeing it with your own eyes and embedding it in your code

Memory can literally be examined:

On the left is a commit rail: hash, message, author, age and a diff in +N ~N -N form. So versioning is not hidden away in the backend - it is part of the interface.

For deeper embedding, separate storage, classifier and search components are available:

Writing and searching look familiar:

One nuance of the current package: the high-level ProllyTreeMemoryStoreManager depends on the optional langmem extra, so install that dependency if you need it specifically. The low-level ProllyTreeStore is in the main package.

Where a model is needed, what you pay for, and privacy

Memoir works without a model, but not in every operation.

The package itself is free and open. Money appears only where you plug in an external model: OpenAI, Anthropic, Gemini or your own API base URL.

Privacy follows the same logic. The store is local, and if you set paths by hand and use get and summarize, the data need never leave. But auto-classification, model-driven recall, conflict merging and file ingestion do send the corresponding text to the chosen provider. So "Memoir is installed locally" does not automatically mean "all data stays local". For MCP over HTTP the documentation warns separately: a public /mcp must sit behind TLS and authentication.

Limitations, and what to make of the published numbers

The documentation cites its own figures: 0.1-1 ms for structural search by semantic path, 20-30 ms for storage operations, 1-5 ms for pattern classification, and an overall 10-20x advantage over the baselines the authors name. Treat these as the authors' claims rather than a universal guarantee - especially since the project itself puts model-driven recall at 500-800 ms in single mode and 1-2 seconds in tiered mode. The instantaneity applies to structural operations, not to the whole system.

The other limitations are worth knowing up front. The project is still Alpha - stated plainly in pyproject.toml; the current release is 0.2.4 and the API and plugins keep changing. Not all search is genuinely logarithmic: exact and prefix queries use the tree well, while model-driven search, vector search and document ingestion have an entirely different cost profile. Auto-classification depends on the model, and a wrong path creates its own class of problem - the information physically exists but the agent looks in the wrong place, so a good taxonomy and review of critical records are still needed. Conflict detection is deliberately narrow: the system notices a collision when a new write hits an occupied key, but it does not search for semantic duplicates across the whole store on every write - the same thought filed under two different paths can exist in parallel. And finally, branches require discipline: if everything is always written to main, the main architectural advantage disappears.

How Memoir differs from Mem0, Memanto and Memora

All four solve a similar long-term memory problem, but Memoir stands out most through its version-control model.

It fits where an agent works across several code branches; where different agents need isolated working memory; where the origin of every decision matters; where hypotheses must be tested safely; where wrong memory has to be rolled back and debugged; where one memory store must serve Claude Code, Codex, Cursor and other MCP hosts; where both structured facts and document search are needed.

It is redundant in a one-off chat; with a memory of a dozen facts; when the task is classic document retrieval; when change history has no value; when you want the simplest possible hosted memory API with no infrastructure of your own.

Boiled down to one thought: Memoir is interesting not because it can remember facts - dozens of libraries do that. Its idea is more specific: an agent's memory should have the same engineering properties we have long considered mandatory for code. Knowledge has an address, not just a similarity score. Every change is visible in the history. An experiment need not become shared truth. And the origin of a wrong fact can be established. For an ordinary support bot that is excessive, but for agents working with code and research, where decisions change, branch and sometimes turn out wrong, the approach looks logical.

Sources

This article was checked on 9 August 2026 against the GitHub repository, the official Memoir documentation, the release notes and the current plugin guides. Supplemented on 14 August 2026 against a fresh clone: version, licence and requirements re-verified, the size of the bundled taxonomy corrected, the placement of the OpenClaw plugin fixed, and the forced merge-policy variable and automatic branch creation added.

• GitHub: zhangfengcdt/memoir
• Official documentation
• Quickstart
• Architecture
• CLI Reference
• Watch & Search
• Conflict & Merge
• MCP Server
• Claude Code Plugin
• Codex Plugin
• Hermes Plugin
• OpenClaw Plugin
• Web UI
• GitHub Releases
• Apache 2.0 License