# mnemon, a memory binary where the host model supervises and the engine just computes

> mnemon 0.2.9 stores agent memory in a four-graph store on disk, and deliberately keeps no model of its own. Here is how that choice shapes the install, the hosts, and the build.

**mnemon-dev/mnemon** — LLM-supervised persistent memory for AI agents — graph-based recall, cross-session knowledge, single binary. Works with DeepSeek Harness, Claude Code, OpenClaw, and any agent runtime.

- Repository: https://github.com/mnemon-dev/mnemon
- Website: https://github.com/mnemon-dev/mnemon#readme
- Stars: 605 · Forks: 74
- Language: Go
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/mnemon-dev-mnemon

## The host model supervises, and the binary only computes

The central design choice is that mnemon ships no model of its own, and the README puts that in a table of four patterns. A tool that embeds its own model acts as an executor inside the pipeline, with two named examples. A tool that injects a file has no model at all and simply reads it at session start. A tool that speaks a tool protocol provides tools and lets the caller decide. Mnemon is the fourth: an external supervisor of a standalone binary. The split is explicit. The binary handles deterministic work, which is storage, graph indexing, search, and decay, and the host model handles judgment, which is what to remember, how to link it, and when to forget. The stated benefit is no middleman and no extra inference cost, and for a subscriber on an existing model plan it means there is nothing else to buy.

## Three primitives, named after what the model is trying to do

The protocol argument is the more interesting half of the design. MCP standardises how a model discovers and invokes tools; the database wire protocols standardise how applications talk to databases. What the project identifies as missing is a layer in between: how a model talks to a database using memory semantics. So mnemon exposes three primitives, and the argument is about their names. The model says it wants to remember something rather than to insert a row, and it says it wants to recall rather than to select. The names map to the vocabulary the model already reasons in, and the return value is structured JSON carrying signal transparency rather than raw database rows. If you are building anything that consumes memory programmatically, that naming is the contract, and it is a small deliberate decision with a large effect on how well a model uses the tool.

## npm is the recommended installer, and it is only a launcher

Installation is one command on all three desktop platforms, requiring Node 22 or newer:

```bash
npm install --global @mnemon-dev/mnemon
```

What that command does is worth being clear about, because it is not a JavaScript tool. The npm package downloads the matching native Go executable for the host operating system and CPU architecture. The engine remains a single native binary and Node is used only by the launcher and the package manager, which is why upgrading is also npm-shaped:

```bash
mnemon update
```

There is a small inconsistency worth knowing if you script this. The manifest at the repository root declares a Node engine floor of 20, while the install instructions say 22 or newer. If you are pinning a Node version in CI, the stricter number is the one in the documentation, and the discrepancy is worth raising rather than working around silently.

## Migrating off Homebrew or Go means fixing your path once

There are two alternative installers, and the project is unusually explicit about the consequence of using them:

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

The rule is that Homebrew, a Go install, a source build, and other Node package managers must each keep using their original installation method. If you want to move to npm, you run the npm install command once and then make sure the npm global bin directory comes before the old executable on your path. After that, update calls are npm-managed. The reason this is spelled out is that two copies of the same binary on one machine is a genuinely confusing failure: whichever one resolves first wins, and the upgrade path of the one that is not being used is the one that will surprise you. Building from source is a Makefile target after a clone, and there are two version commands to verify an install, one for memory and one for the Agency surface.

## Windows gets Memory, and Agency is blocked on a security boundary

Platform support is split along a specific line rather than a general one. Windows supports the core Memory commands. Agency does not, and the reason is not that it was not finished: the documentation says Agency remains unavailable on Windows until its local authority boundary has native Windows security. That phrase points at something real, because Agency is the surface that admits an agent's responsibilities and effects in a project, and that is exactly the kind of capability that needs operating-system-level enforcement rather than a convention. The practical upshot is that a Windows user gets a working memory store and not the second half of the product, and that the two halves are explicitly independent: enabling one does not enable the other.

## Each host gets a different subset of hooks, skills, and scope

The per-host integrations are not uniform, and the differences are documented reasons rather than oversights. Codex gets three named lifecycle hooks, at session start, on user prompt submission, and at stop, written into its hooks configuration file. Cursor gets skill, prompt files, and its own hooks, and the integration primes new sessions with memory guidance and status, then nudges for writeback after responses. ZCode is the awkward one: without the global flag you get only the project skill, because that host currently ignores project-level hook configuration, so a project-scoped install gives you the instructions without the automation. MiniMax Code is declared skill-only on purpose, because in one specific release the local agent path does not dispatch the user-prompt lifecycle hook that dependable automatic recall requires. So the honest summary is that full automatic recall is not universal across hosts.

## The runtime image is Alpine, non-root, and built without cgo

The container is three stages and the interesting decisions are all in the last one. The build compiles with cgo disabled and the binary stripped, with the version string injected into the source at link time rather than read from a file. The runtime stage is Alpine with only certificate and timezone data added, and it creates a system group and user, creates the data directory, and hands ownership to them before switching to that user. The entrypoint is the binary itself and the default command asks for status, and the data directory is declared as a volume with the store name in the environment. The Compose file adds a development target behind a profile that bind-mounts the source and persists the Go build and module caches, and an optional profile that brings up a local model server for embeddings on its usual port.

## Seven pinned Go dependencies, one of them a pure-Go SQLite

The module file is short enough to read in one pass and everything in it is pinned to an exact version, with no ranges. Seven direct requirements: a command-line framework, a UUID generator, a terminal detection library, a YAML parser, two operating-system and terminal packages, and the database driver. That last one is the interesting choice. It is a pure-Go SQLite implementation rather than the usual cgo binding, which is what lets the binary be built with cgo disabled and run on Alpine from a scratch-like base with no shared library to ship. A separate manifest at the repository root is not the published package at all; it is a bundle definition for a different agent harness, and it declares a single dependency on a companion package pinned to the floating tag `latest`, which is the one place in the repository where a version is not pinned.

## Conclusion

mnemon fits an agent runtime where the model is already available and you would rather not pay for a second inference path to remember things. The supervisor pattern means the memory quality tracks the quality of the host model, which is a feature when you trust that model and a liability when you do not. It is a poor fit if you need the memory engine to work without a capable model, if you are on Windows and want the Agency surface, or if you want a hosted protocol rather than three command names. Before you adopt it, pick one installer and do not mix, then check which lifecycle hooks your host actually dispatches.

## FAQ

### Does mnemon need its own language model or API key?

No. The design is that your host model is the supervisor: the binary handles storage, graph indexing, search, and decay, while the model decides what to remember, how to link, and when to forget. The README notes that a subscriber on an existing model plan can use it with no separate key at all, because the subscription is the intelligence layer.

### How do I install mnemon?

The recommended route is a global npm install, which requires Node 22 or newer and downloads the matching native Go executable for your platform. Homebrew and go install are also documented. If you migrate from one of those to npm, run the npm install once and make sure the npm global bin directory precedes the old executable on your path.

### What are the three mnemon primitives?

remember, link, and recall. The argument is that these names map to the model's own vocabulary rather than to database operations, so it asks to remember rather than to insert and to recall rather than to select. Output is structured JSON carrying signal transparency rather than raw database rows.

### Does every agent host get automatic memory recall with mnemon?

No. Codex receives three named lifecycle hooks. ZCode ignores project-level hook configuration, so it needs the global flag to get anything but the project skill. MiniMax Code is intentionally skill-only because in one specific release the local agent path does not dispatch the user-prompt lifecycle hook dependable automatic recall requires.

### Is Agency available on Windows?

Not yet. Windows supports the core Memory commands, while Agency remains unavailable there until its local authority boundary has native Windows security. The two surfaces are independent, so enabling Memory on a project does not enable Agency.

## Sources

- [License: Apache-2.0](https://github.com/mnemon-dev/mnemon/blob/master/LICENSE)
- [mnemon-dev/mnemon on GitHub](https://github.com/mnemon-dev/mnemon)
- [Project website](https://github.com/mnemon-dev/mnemon#readme)
- [README](https://github.com/mnemon-dev/mnemon/blob/master/README.md)
- [Releases](https://github.com/mnemon-dev/mnemon/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mnemon-dev-mnemon