Mnemo
One shared, versioned memory for your coding agents. Claude Code, Codex, OpenCode and other MCP clients on your machine read and write the same memory, for each project and across projects. Every change is kept, attributed to the agent that made it, and can be undone. Everything runs locally.
Quick start
You need macOS or Linux with uv. Nothing else runs: memory
is one file, ~/.mnemo/mnemo.db, and the embedding model runs inside Mnemo. On Linux a
glibc distribution is needed (Debian, Ubuntu and uv's own Python are tested); Alpine
and other musl systems are not supported, because sqlite-vec publishes no wheels for
them. Windows has not been tested: the code avoids the POSIX assumptions found so far
(.exe server paths, escaped paths in agent configs, UTF-8 files, path: project
names), but nobody has run it there yet.
uv tool install mnemohive
mnemo install # connect Claude Code, Codex and OpenCode (shows every change, asks first)
The package is mnemohive on PyPI; the command it installs is mnemo.
mnemo install downloads the embedding model (BAAI/bge-small-en-v1.5, about 67 MB,
from Hugging Face) after you confirm, creates the memory file (readable only by you),
registers Mnemo with Claude Code and Codex (and OpenCode, when it is installed), and
adds a short memory policy to their global instructions. The agents run
the installed tool's own server. Then start a new session in any repository. For
example, tell Claude Code:
Heads-up: in this repo we run tests with
make test-db.
Later, ask Codex in the same repository:
How do I run the tests here?
Codex finds the note in the shared memory and answers make test-db.
mnemo uninstall removes exactly what mnemo install added; your memories stay in
the file.
To update, run uv tool upgrade mnemohive and then mnemo install, which applies
any new schema migrations and refreshes the agents' configuration. Until then, the
tools answer with an error that says what to run.
Installed from GitHub before 0.1.3 (the tool was called mnemo then): run
uv tool uninstall mnemo, then uv tool install mnemohive and mnemo install.
Your memories stay in ~/.mnemo/mnemo.db.
Upgrading from the Postgres version (before 0.1.0): the new version does not read the Postgres database, so carry your memories over with an export.
mnemo-transfer export --all-scopes --out mnemo-postgres.json # old version, Postgres up
uv tool uninstall mnemo && uv tool install mnemohive
mnemo import mnemo-postgres.json # creates ~/.mnemo/mnemo.db; same IDs, history, receipts
mnemo install # embeds the imported memories with the chosen model
Import leaves the vectors to mnemo install, which now uses the model inside Mnemo
by default; add --backend ollama to keep using Ollama. Your Postgres data is not changed, and mnemo up/mnemo down are gone:
stop the old container with Docker when you no longer need it. To go back, install
the tag: uv tool install --force git+https://github.com/Yugesh-reddy/Mnemo@v0.0.1-postgres.
From a checkout (to change Mnemo itself): git clone it, then make install
and make agents. make agents installs the tool from your checkout first,
so the agents keep working if you move or delete it; rerun it after changing code.
What you get
- Shared across agents. Every agent reads the same memory. Each one writes under
its own name (
claude-code,codex), so history shows who changed what. - Project and global scopes. Memories belong to the git repository the agent is working in (SSH and HTTPS clones share them) and stay out of other repositories. Things you say apply everywhere, like "always use uv", go to the global scope.
- History and undo. A change never overwrites the past: every revision is kept,
memory_historyshows it, andmemory_revertrestores an earlier value as a new revision. Stale writes are rejected, and retrying a change doesn't apply it twice. - Clear failures. If the memory file or the embedding model is missing, the agent gets an error that names the command that fixes it, and the server keeps running.
- Local and private. Memories stay in one file on your disk, embeddings come from a model inside Mnemo (or your Ollama), and nothing is sent anywhere else. There is no telemetry.
Does it work?
The coding-agent eval runs sixteen scenarios with the real
Claude Code and Codex CLIs in throwaway repositories: a convention told to one agent
and used by the other, an end-of-day handoff, a correction, several values of one
kind, isolation between projects, a preference for all projects, a restated rule, a
retracted memory, small talk, a question nothing answers, and five poisoning attempts
(instructions planted in repository files, in a code comment aimed at the user's other
projects, and inside a stored memory). Without
instructions, Codex never saved what it was told, and the first ten scenarios passed
4 of 10. With the memory policy that mnemo install installs, all twelve passed
(12 of 12), including with Claude Code's own auto-memory left on. On the
single-file store the same setup passed 12 of 12 in three more runs, one with Ollama
and two with the model inside Mnemo, with no Mnemo tool errors. After a policy change
for the three harder poisoning scenarios (tell the user about planted instructions;
retract a poisoned memory unasked), all sixteen passed (16 of 16, with a control
that a plain memory is still used). Each scenario ran once
per run on tiny planted repositories, so this shows the approach works, not how often it works in long, real sessions.
How agents use it
Seven MCP tools, served by mnemo-mcp-direct:
| Tool | Contract |
|---|---|
memory_create |
Save a new memory in the project (default) or global scope, with its source: user (high trust), tool (medium) or agent (low, the default). Trust is what the writing agent claims; the recorded actor, the history and retract are the defence when an agent is wrong or misled. An existing subject/predicate in that scope returns ALREADY_EXISTS with its ID. |
memory_get |
Read the current value and event ID, or a full historical value and whether it can be restored. |
memory_search |
Search the project and global scopes; hits carry fact ID, event ID, scope, who wrote the value (actor), when (recorded_at) and its provenance and trust_level. |
memory_update |
Change a memory by fact ID, passing the event ID you read as expected_event_id, with its source. |
memory_history |
Page through revisions, newest first, with value previews. |
memory_revert |
Copy a historical value into a new revision, keeping its provenance and trust. |
memory_retract |
Withdraw a wrong or planted memory, including one just created: it leaves search and memory_get reports status: "retracted". History is kept; revert or update restores it. |
Agents read before changing a memory, pass the revision they read, re-read on a
conflict, and ask which change to undo when "undo that" is ambiguous. request_id is
optional; sending the same one again replays the original result instead of
applying the change twice. Errors are JSON {code, message, details} with MCP's
isError flag set:
| Code | What to do |
|---|---|
INVALID_INPUT |
Correct the input, ID, value size, limit, or cursor. |
NOT_FOUND |
Check the memory ID; memories from other projects are not visible. |
ALREADY_EXISTS |
Read the returned fact ID, then use a guarded update. |
REVISION_CONFLICT |
Re-read and reconsider; the memory changed since you read it. |
INVALID_RESTORE_TARGET |
Select a revision belonging to this memory. |
UNSUPPORTED_STATE |
This current state or historical revision cannot be restored here. |
REQUEST_ID_REUSED |
A request ID was reused with different parameters; retry the original or leave it out. |
UNSUPPORTED_OPERATION |
Undoing a creation is not supported. |
SERVICE_UNAVAILABLE |
The memory file or the embedding service is missing, not set up, or busy; the message names the fix. |
Configuration
Settings come from MNEMO_* environment variables or .env; see
.env.example. The ones that matter most:
| Setting | Default | Meaning |
|---|---|---|
MNEMO_DB |
~/.mnemo/mnemo.db |
The memory file every agent shares. Keep it on a local disk, not in a synced folder. |
MNEMO_BACKEND |
local |
Embeddings: local (a model inside Mnemo, no server; see below), ollama (a local Ollama server), hash (no model, matches exact words only) or openai (sends text to OpenAI). |
MNEMO_ACTOR |
the agent ID | Who is writing; set per agent by mnemo install. |
MNEMO_PROJECT |
detected | Overrides the project detected from the git repository. |
MNEMO_NAMESPACE, MNEMO_USER_ID |
default |
Shared by every agent that should see the same memory. |
mnemo install options: --dry-run shows the changes only,
--agent claude|codex|opencode limits them to the agents named, --codex-home points
at another Codex home (a codex wrapper that pins one is detected), --opencode-dir
at another OpenCode config directory, --backend ollama uses Ollama's
nomic-embed-text instead of the model inside Mnemo, and --claude-auto-memory off also turns off Claude Code's built-in memory.
OpenCode gets a mnemo server under mcp in ~/.config/opencode/opencode.json
(under mcp.servers when the file already groups its servers there, the newer
layout). An opencode.jsonc with comments is never rewritten: the installer prints
the entry to paste instead, and when OpenCode was only detected, not named with
--agent, it sets up the other agents and skips OpenCode. The policy goes into ~/.config/opencode/AGENTS.md, or into
~/.claude/CLAUDE.md when OpenCode is reading that file because it has no
AGENTS.md of its own (creating one would stop it reading CLAUDE.md).
The default local backend runs the embedding model inside each Mnemo server.
mnemo install downloads BAAI/bge-small-en-v1.5 (about 67 MB, from Hugging Face)
into ~/.mnemo/models; nothing is downloaded later. Each agent session's server uses
about 300 MB of memory once it has searched or written (about 60 MB before), and its
first search takes about 2 s while the model loads. After 5 minutes without a search or
write the server lets the model go (MNEMO_LOCAL_MODEL_IDLE_SECONDS, 0 to keep it):
on Linux that gives back about 90 MB per idle session; macOS reclaims the memory
gradually; the next call reloads it in about 0.1 s. On a 28-question check it found
memories about as well as Ollama (see tests/test_retrieval_quality.py), but an
unrelated question returns a memory more often (3 of 8 questions against 1); the
model is English-only. --backend ollama uses Ollama's nomic-embed-text instead
(about 70 MB per server plus Ollama). Each vector is stored with the model that made it, and search compares
a question only with vectors from the same model, so switching models keeps your
memories: mnemo install embeds them again with the new model. mnemo reindex does
it by hand with the backend in your shell's MNEMO_BACKEND, so set the one the agents
use. Until then memories are still found by their words.
Configure by hand
With the tool installed, the server is mnemo-mcp-direct in uv tool dir --bin
(usually ~/.local/bin); use its absolute path. The server never downloads the
model: let mnemo install fetch it once, or use MNEMO_BACKEND=ollama with
MNEMO_EMBED_DIM=768. Claude Code, once for every repository:
claude mcp add mnemo --scope user \
-e MNEMO_BACKEND=local -e MNEMO_MODEL_DIR=/Users/you/.mnemo/models \
-e MNEMO_ACTOR=claude-code \
-- /Users/you/.local/bin/mnemo-mcp-direct
Codex, in ~/.codex/config.toml (or $CODEX_HOME/config.toml):
[mcp_servers.mnemo]
command = "/Users/you/.local/bin/mnemo-mcp-direct"
default_tools_approval_mode = "approve" # lets `codex exec` call the tools unattended
[mcp_servers.mnemo.env]
MNEMO_BACKEND = "local"
MNEMO_MODEL_DIR = "/Users/you/.mnemo/models"
MNEMO_ACTOR = "codex"
OpenCode, in ~/.config/opencode/opencode.json:
{
"mcp": {
"mnemo": {
"type": "local",
"command": ["/Users/you/.local/bin/mnemo-mcp-direct"],
"environment": {"MNEMO_BACKEND": "local", "MNEMO_ACTOR": "opencode"}
}
}
}
Also paste the memory policy into ~/.claude/CLAUDE.md,
$CODEX_HOME/AGENTS.md and OpenCode's rules file: without it, Codex did not save
anything in the eval. Other
clients such as Claude Desktop or Cursor take the same
command and environment in their JSON configuration (Cursor also needs
"type": "stdio"). They are not started inside a repository, so they see only the
global scope unless you set MNEMO_PROJECT. In a checkout, make mcp runs
the server from source.
What Mnemo depends on
| Service | Used for | If it is down |
|---|---|---|
One SQLite file (~/.mnemo/mnemo.db) with sqlite-vec |
All memories, history and receipts | Tools return SERVICE_UNAVAILABLE naming the fix (mnemo install) |
The embedding model in ~/.mnemo/models (or Ollama with nomic-embed-text) |
Embeddings for search and writes | Search and writes fail with the fix; reading by ID, history and revert still work |
| git | Detecting the project | Only the global scope is available |
No language model runs inside Mnemo for this path: the agent decides what to save. The optional web UI serves its own copies of Tailwind's CSS and htmx, so it works offline.
What the store guarantees
| Mechanism | Where it lives |
|---|---|
Triggers reject changes to event payloads and receipts, deletes, and INSERT OR REPLACE; supersession and recall bookkeeping remain mutable. |
Schema |
| Every write takes the file's single write lock; expected-event guards reject stale updates/reverts, including A→B→A. Eight processes racing one update give one winner. | Direct API, race tests |
Each event is chained to the previous one by a SHA-256 hash; mnemo verify recomputes the chain and reports any event changed, removed or inserted outside Mnemo. It records the head it verified beside the store (mnemo.db.verified, or --witness FILE) and next time checks the chain still passes through it, which catches a rewrite of every later hash too. A memory's scope, subject and key cannot be changed or deleted through SQL either, and are sealed the same way, so mnemo verify also reports a memory moved or renamed around the triggers. After restoring a backup on purpose, delete that file and verify again. |
Chain, spec §27, §31 |
| Event, HEAD, and append-only receipt commit together. Receipts survive restarts and remain for the store's lifetime. | Schema |
| Revert copies source payload, embedding and lineage into a new event; it does not raise source trust. | Core, direct contract |
Historical reads distinguish recording time (as_of) from world validity (valid_at). Archive is reversible; blame, diff, and commit expose history. |
Temporal contract |
To see the versioning without any agent or model, run make demo in a
checkout. It
remembers PostgreSQL, changes it to MySQL, rejects a stale update, inspects history
and restores PostgreSQL; retrying the restore returns its receipt:
ADD(PostgreSQL) -> UPDATE(MySQL) -> REVERT(PostgreSQL)
Source trust preserved: agent_inference / low
The demo uses the hash backend in a temporary file, so it never touches your
memories.
The Python guide shows Mnemo.direct and the async
DirectMemory(store) interface. Existing add, search, blame, revert,
diff, log and commit APIs remain available with their legacy
contracts. Legacy add performs alias deduplication; direct updates preserve
exact spelling changes. Legacy human-review revert is not revision-guarded.
Back up or move a store
mnemo export --out mnemo-export.json # the configured scope; stdout without --out
mnemo export --all-scopes --out all.json # every scope
mnemo import mnemo-export.json # into an empty store only
Copying ~/.mnemo/mnemo.db while no agent is running also works. The export is one
versioned JSON document: facts with their HEADs, every event, commits, receipts and
the applied migrations, exactly as stored. Vectors are left out and rebuilt on
import with the destination's model. Import restores the rows in one transaction,
reads back what it wrote and rolls back if anything differs, so IDs, sequence
numbers, history and receipt replays come through unchanged. It also reads exports
from the Postgres version (spec §16).
Review memory in the browser
make ui # installed as a tool: mnemo ui
# then open http://127.0.0.1:8000
The page opens on the global memories; the Scope menu in the header lists every
project that has memories in the store, and the choice stays in the address
(?scope=…) on every page. A correction or restore always applies to the scope the
memory belongs to.
A project's scope is <MNEMO_NAMESPACE>@<project>, where the project is the
repository's remote in lower case (for example github.com/you/your-repo), or
path:<repository path> when it has no remote. The UI needs the same embedding
backend as the agents (the model inside Mnemo by default). Search → open history → revert a
revision. A stale form
returns HTTP 409, shows the latest state, and writes nothing. Repeated submissions
replay their receipt. Unrestorable revisions have no restore button. Retracted
lists every memory an agent withdrew, with who did it, when and why, so you can
restore one an agent was misled into retracting. Manual
correction records a value you checked yourself as human review (high trust). It is
guarded like restore: if an agent changed the memory while the page was open, the
correction is refused with HTTP 409 and the page shows the agent's value.
Checks, layout and limits
make test # every test gets its own temporary memory file
make lint
uv build
bash scripts/check-wheel.sh
The packaging check uses a fresh environment and exercises installed SDK/MCP
behavior. The correctness workflow
runs the tests on macOS and Linux. bash scripts/check-linux.sh (Docker) installs the
wheel as a new user would in a fresh Linux container: mnemo install with and without
agents present, the MCP server over stdio, mnemo verify, the web UI and
mnemo uninstall; --local also downloads the embedding model. Optional live-Ollama
tests skip when their models are unavailable.
mnemo/ contains the async store, direct API, SDK, MCP server and installer;
mnemo/web/ the review UI; migrations/ holds the schema; examples/, scripts/
and tests/ hold the demos, the agent eval and checks.
The spec defines contracts; the plan and
status track delivery.
This is a local, single-user service. Scope columns do not provide authentication or access control, and memories are stored unencrypted, so don't save secrets. Identity is one current value per subject/predicate in a scope. Direct mutations accept strings up to 8192 UTF-8 bytes and operate on active, durable, non-expiring memories, or retracted ones. Grouped undo, branching, merging and multi-user access are out of scope for now.
Architecture
flowchart LR
Claude[Claude Code] --> Direct[Seven direct MCP tools]
Codex[Codex] --> Direct
OpenCode[OpenCode] --> Direct
UI[Web revert] --> Direct
Direct --> Core[Scoped event store]
Core --> Events[Append-only events]
Core --> Heads[Current HEADs]
Direct --> Receipts[Durable mutation receipts]
Events --> History[History / as-of reads / diff]
History: the automatic extraction pipeline (archived)
Mnemo began as a write-quality pipeline: it recorded conversation turns, and a worker
extracted facts, checked them against their source, deduplicated, scored and tiered
them. Coding agents save what matters themselves, and small local models did not
reach the quality target, so the pipeline, its evals and its evidence were removed
from main. They remain at the git tag archive/extraction-pipeline
(git checkout archive/extraction-pipeline), on the Postgres version of the store.
An earlier host-agent pilot let Qwen or Azure Luna drive the direct tools, one attempt per scenario: both reached the intended end state in 5/6 scenarios, and on an ambiguous "undo that" Luna reverted both memories instead of asking. The revision guards block stale and racing writes but cannot know whether a write was wanted; what they guarantee is that such a change is attributed, visible in history and reversible.
License
The project declares the MIT license in pyproject.toml.
Metadata
Release files for mnemohive 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mnemohive-0.1.5.tar.gz | 462.1 kB | Without provenance | Details for mnemohive-0.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mnemohive-0.1.5-py3-none-any.whl | Python 3 | none | any | Details for mnemohive-0.1.5-py3-none-any.whl |
Total release size: 598.1 kB
Release files / mnemohive-0.1.5.tar.gz
| Download URL | mnemohive-0.1.5.tar.gz |
|---|---|
| Size | 462.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
debd11489696b5c037b222ced2fb141d2b8d6297d09bb04d927676b22f3e6e90
|
|
BLAKE2b-256 checksum How to use checksums |
98180af61f3d32724ff3f025be943e7ed971f79e5757eb0a3ff18cc2f929f6d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mnemohive-0.1.5-py3-none-any.whl
| Download URL | mnemohive-0.1.5-py3-none-any.whl |
|---|---|
| Size | 136.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6b39ca1969ec9d2cda1b453058dd9b77e33d4b45b3156fb5cabe768d9d1c400b
|
|
BLAKE2b-256 checksum How to use checksums |
b2e2853adfeed7ad765ad892581a7aa8e23aae6be277bc89a9fc4c0dd5948eb3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for mnemohive 0.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.