Mnemon: LLM-supervised persistent memory for AI agents

The problem Mnemon targets: agents that forget between sessions

Context compaction is the failure mode Mnemon is built around. Long conversations push early information out of the context window, and when a session ends, whatever the agent learned about your project goes with it. The README states the problem in one line: LLM agents forget everything between sessions, context compaction drops critical decisions, and cross-session knowledge vanishes.

The project is aimed at people running coding agents and other long-lived LLM runtimes who want that knowledge to accumulate instead of resetting. The README frames memory as a private asset that grows with the user, in contrast to model engines that iterate constantly and skill files that cost nearly nothing to write. That framing explains the design priority: the store belongs to you, lives locally, and is worth investing in.

It is not a general-purpose vector database and it is not a chat history archive. It is a memory layer with three verbs, remember, link and recall, that an agent calls during a session.

How the LLM-supervised model splits work between the agent and the binary

Mnemon's distinguishing choice is where the model sits. Most memory tools embed an LLM inside the pipeline as an executor. Mnemon puts the host LLM outside the binary as a supervisor. The binary handles deterministic computation: storage, graph indexing, search and decay. The LLM makes the judgment calls about what to remember, how to link entries, and when to forget. The README's comparison table names Mem0 and Letta as LLM-embedded examples, Claude Code Memory as file injection with no LLM role, and claude-mem as an MCP tool provider.

The store itself is a four-graph knowledge store with intent-aware recall, importance decay and automatic deduplication. A diagram in the repository shows a graph of 87 insights connected by 2,150 edges across temporal, entity, semantic and causal edge types. Those four edge categories are the interesting part: recall is not a flat similarity search across rows, it is a traversal over typed relationships.

The README also argues that a protocol layer is missing between LLMs and databases with memory semantics, and positions remember, link and recall as an intent-native protocol. Command names map to cognitive vocabulary rather than SQL verbs, and output is structured JSON with signal transparency rather than raw rows. Whether that counts as a protocol or as a well-named CLI is a matter of taste, but the naming choice does shape how an agent's prompt describes its own memory operations.

One consequence of supervision is worth stating plainly: the quality of what gets stored depends on the host model's judgment, not on the binary. Mnemon gives you a place to put memories and a way to retrieve them. It does not decide for you.

Installing Mnemon and getting a first memory into the store

The recommended install is the npm package, which the README lists for macOS, Linux and Windows with Node.js 22 or later. The npm package installs the matching native Go executable for the host OS and CPU; Node.js is only used by the launcher and package manager, and the engine stays a single native binary.

npm install --global @mnemon-dev/mnemon

After that, confirm the binary resolves and check the version:

mnemon --version
mnemon agency --version

There are alternative installers. Homebrew uses a cask from the mnemon-dev tap, and Go users can install directly:

brew install --cask mnemon-dev/tap/mnemon
go install github.com/mnemon-dev/mnemon@latest

The README is explicit that Homebrew, go install, source builds and other Node package managers must keep using their original installation method. To migrate one of those to npm management, run the npm install once and make sure the npm global bin directory comes before the old executable on PATH. After that, mnemon update is npm-managed.

For Claude Code, setup is one command. The README says it auto-detects Claude Code, then interactively deploys a skill, hooks and a behavioral guide:

mnemon setup

Start a new session afterwards. Other runtimes have explicit targets. Codex deploys a skill, prompt files and lifecycle hooks into .codex/hooks.json; Cursor deploys into .cursor/; ZCode takes a global flag:

mnemon setup --target codex --yes
mnemon setup --target cursor --yes
mnemon setup --target zcode --global --yes

The README does not walk through a first remember and recall from the command line, so the concrete first use is the setup command followed by a session in your agent runtime. What you should see is the deployed hook files in the target directory and, in a new session, Mnemon guidance and memory status priming the agent.

Docker, data directories and the environment variables that matter

The repository ships a Dockerfile and a docker-compose.yml, which is useful if you want the store isolated from the host. The runtime image is Alpine, runs as a non-root mnemon user, and sets two environment variables:

ENV MNEMON_DATA_DIR=/mnemon \
    MNEMON_STORE=default
VOLUME ["/mnemon"]
ENTRYPOINT ["mnemon"]
CMD ["status"]

MNEMON_DATA_DIR is the data root and MNEMON_STORE selects the store name. The compose file declares a mnemon service built to the runtime target, mounts a named volume at /mnemon, points MNEMON_DATA_DIR at it, and defaults the command to status:

environment:
  MNEMON_DATA_DIR: /mnemon
volumes:
  - mnemon-data:/mnemon
command: ["status"]

The same file defines a dev service under the dev profile with the source tree mounted at /workspace plus Go build and module caches, and an ollama service under the embeddings profile exposing port 11434. That last one is the only place in the repository where an external model server appears, and the README does not describe how embeddings are wired into recall, so treat the embeddings profile as an optional component rather than a documented requirement.

The practical point for operators: the named volume is the memory. If you rebuild the container without that volume, the store is gone. The README does not document an export or backup command.

Where Mnemon is the wrong tool

Windows is the clearest boundary. The README states that Windows supports the core Memory commands, and that Agency remains unavailable on Windows until its local authority boundary has native Windows security. If Agency is what you came for, Windows is not a supported platform yet.

Agency itself is labeled Preview and Pi-first. The setup command is mnemon agency setup --runtime pi --project-root ., and the README points to docs/AGENCY.md for the operating model and the Preview compatibility boundary. Preview means the surface can change between releases, and the release cadence supports that reading: v0.2.6, v0.2.7 and v0.2.8 all landed within a week of each other in late August and early September 2026.

If you want a memory system that runs its own model and produces memories without your agent's involvement, Mnemon's supervision model is the opposite of what you want. The README is direct that the LLM makes the judgment calls. An agent that never calls remember will never store anything.

If your need is simply carrying a few notes across sessions, file injection is cheaper. The README lists Claude Code Memory as the file-injection pattern, where the runtime reads a file at session start and no LLM is involved. That has no graph, no decay and no deduplication, but it also has no setup, no hooks and no binary to keep updated.

Finally, the README does not document rollback for mnemon setup. If the hooks it deploys interfere with your runtime, the documentation does not say how to undo the deployment.

Mnemon compared with an LLM-embedded memory library

The closest alternative in the README's own table is the LLM-embedded pattern, with Mem0 and Letta named as representatives. The difference is architectural, not cosmetic. In an LLM-embedded library, the memory pipeline calls a model itself: extraction, summarization and linking happen inside the library, and you pay for that inference separately from your agent's own calls.

Mnemon inverts that. The binary is deterministic and the host LLM supervises it, which means there is no second inference bill and no separate API key. The README makes this concrete for Claude Max and Pro subscribers: Mnemon works through the existing subscription, and the README calls the subscription the intelligence layer.

The trade-off runs the other way too. With an embedded model, memory writes happen automatically as part of the pipeline. With Mnemon, the host agent has to decide to write, which depends on the hooks and skill files that mnemon setup deployed actually steering it. That is a real dependency on integration quality rather than on the store itself.

A second difference is packaging. Mnemon is a single Go binary with SQLite underneath, per the go.mod dependency on modernc.org/sqlite, plus cobra for the CLI. That makes it easy to run locally or in a small container. An embedded-LLM library typically brings a Python or Node service and its model dependencies along with it.

Maintenance, upgrades and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-09-06, two weeks before this writing, so the project is being worked on. Releases have been frequent: v0.2.8 on 2026-09-05, v0.2.7 on 2026-08-31, v0.2.6 on 2026-08-30. Frequent patch releases at this stage usually mean fixes and small surface changes rather than a frozen API.

Upgrade cost depends on how you installed it. npm-managed installs upgrade with one command:

mnemon update

The README warns that Homebrew, go install, source builds and other Node package managers must continue to use their original installation method, so those users upgrade through brew, go install or a rebuild rather than through mnemon update. Mixing the two paths is the failure mode the README calls out: if the npm global bin directory does not precede the old executable on PATH, you can end up running a stale binary.

There is also a separate npm package in the repository root, @mnemon-dev/dsh-mnemon, version 0.1.0, described as installing the full dsh-mnemon integration and depending on dsh-mnemon latest. It declares a dsh bundle patch at ./cordis.patch.yml. That is the DeepSeek Harness path, and it is versioned independently of the main CLI, so an upgrade of one does not imply an upgrade of the other.

The licence is Apache-2.0, which permits commercial use and modification with the usual attribution and notice requirements. The README does not discuss trademark or contribution terms beyond the presence of CONTRIBUTING.md and SECURITY.md in the repository. If you plan to redistribute a modified binary, read the licence text and the NOTICE handling yourself rather than relying on a summary.

Editorial conclusion

Adopt Mnemon if you already pay for a Claude Max or Pro subscription and want cross-session memory without a second inference bill, or if you want the memory store to be one local binary you can inspect. Do not adopt it if you need Windows support for the Agency surface, if you want the memory engine to embed its own model, or if you are unwilling to let the host LLM make the write decisions. Before committing, verify three things on your own machine: that mnemon --version and mnemon agency --version both resolve after install, that a fresh session actually triggers the hooks your target runtime deployed, and that your data directory survives whatever backup or container lifecycle you run.

Frequently asked questions

Official sources

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