Mnemosyne: SQLite-backed memory for agents that cannot use the cloud

The problem Mnemosyne targets: agent memory without a backend

Most agent memory layers assume a server. You run a vector database, or you call a hosted memory API, and the agent's context lives somewhere you have to operate. Mnemosyne takes the opposite position. The README describes it as a "universal, Hermes-first memory layer that works with any agent framework", and the storage is one SQLite database with no external services required. The pyproject.toml declares exactly one runtime dependency, PyYAML>=6.0, and requires Python 3.10 or newer.

The audience is narrow but real. It is for people building agents on a laptop, in an air-gapped environment, or under a policy that forbids sending conversation history to a third party. The README's integration table lists Cursor, Claude Code, OpenAI Codex CLI, Windsurf, OpenWebUI, Pi, OpenClaw and Hermes Agent, plus any MCP client and any Python agent. That breadth is the point: the same SQLite file backs all of them, so memory written from one client is visible to another.

How recall works: SQLite, episodic compression and an abstention path

The architecture is visible in the benchmark tables rather than in a diagram. Mnemosyne stores messages in a SQLite file and reports retrieval latency and storage that grow sub-linearly with corpus size. At 100K scale the retrieval table shows 372ms, 1.8 MB and 200 messages. At 10M scale it shows 35ms, 7.2 MB and 20,000 messages. The README attributes the storage behaviour to episodic compression, which it says delivers 9.4x savings. That is a strong claim for a hundredfold increase in messages producing a fourfold increase in bytes, and it is the mechanism worth reading docs/beam-benchmark.md for before you trust it.

The second mechanism is abstention. The README states abstention accuracy is 100%, meaning the system declines rather than inventing an answer when the corpus does not contain one. For an agent memory layer this matters more than raw recall. A memory system that returns a confident wrong answer poisons the next turn. A system that returns nothing lets the agent say it does not know.

The recall level itself is the weak point. Recall@10 is 20% at every scale shown, from 100K to 10M. The README is explicit that "the flatness rather than the level is the result worth citing". That is an honest framing, and it also tells you the retrieval quality is not competitive with systems that score higher. Flat 20% means four out of five relevant items are missed at k=10, regardless of corpus size.

Installing Mnemosyne and adding it to an MCP client

The package name on PyPI is mnemosyne-memory, not mnemosyne. The README gives the plain install and an extras install that adds vector search and the MCP server. The project metadata defines extras named llm, embeddings, mcp, openclaw, sync, test and all.

pip install mnemosyne-memory

# With all features (vector search + MCP server)
pip install "mnemosyne-memory[all]"

For an MCP-based client such as Cursor, Claude Code, Codex or Windsurf, the README shows a JSON block to place in the client's MCP config file. The command is mnemosyne with the single argument mcp, and the env object is empty in the example.

{
  "mcpServers": {
    "mnemosyne": {
      "command": "mnemosyne",
      "args": ["mcp"],
      "env": {}
    }
  }
}

If you are writing a Python agent directly, the SDK example is two functions. remember stores a string, recall searches for one. The README's example stores a preference and queries for preferences in the plural, which is a useful hint that recall is not an exact string match.

from mnemosyne import remember, recall

remember("User prefers dark mode interfaces")
results = recall("user preferences")

For a server deployment, the CLI starts the MCP server over stdio by default, or over SSE and streamable HTTP with explicit transport and port flags. The README notes that a non-loopback streamable-http bind also requires MNEMOSYNE_MCP_ALLOWED_HOSTS, and browser clients additionally need MNEMOSYNE_MCP_ALLOWED_ORIGINS.

mnemosyne mcp
mnemosyne mcp --transport sse --port 8080
mnemosyne mcp --transport streamable-http --port 8080

The repository also ships a Dockerfile and a docker-compose.yml. The compose file runs the image ghcr.io/axdsan/mnemosyne-mcp:latest on port 8080, mounts a named volume at /data, sets MNEMOSYNE_DATA_DIR=/data and passes MNEMOSYNE_MCP_TOKEN through from the environment. The README warns that if Mnemosyne is installed in an isolated venv, you must activate that venv or invoke its bin/mnemosyne executable before running the CLI commands.

Where Mnemosyne is the wrong tool

The benchmark section is the clearest limitation, and the project says so itself. The BEAM numbers were measured on v3.0.0 in May 2026 and, per the README, predate polyphonic recall, enhanced recall, SHMR and the persona tier. They have not been re-run since. A re-run on the current tree is tracked as an open task. So the headline 65.2% at 100K describes software that is several features behind what you would install today, in either direction. You cannot read it as a floor or a ceiling.

The judge caveat compounds this. Mnemosyne's run used Llama 3.3 70B with a DeepSeek V4 Flash judge, while Hindsight's published 73.4% used Llama-4-Maverick. The README states plainly that scores produced under different judges are not directly comparable and that Hindsight leads on this benchmark as published. That is unusually candid, and it also means the comparison table should not be used to pick between the two.

The withdrawn LongMemEval figure is a third warning. A 98.9% Recall@All@5 number from April 2026 sat in the README until September 2026. The project removed it because no methodology or run log exists in any of its repositories. A memory system is exactly the kind of component where an unverifiable number is worse than no number, because it shapes architecture decisions before anyone checks.

On fit: if your agent needs high recall over a large corpus, flat 20% Recall@10 is not enough, and no amount of storage efficiency compensates. If you need a multi-writer database with concurrent writes from several processes, a single SQLite file is a known constraint, and the README does not document a server mode for that. If you need managed backups, failover or an audit trail, the README is silent on those.

Mnemosyne against Honcho, Hindsight and plain RAG

The BEAM table names three alternatives: Honcho at 63.0%, Hindsight at 73.4% and LIGHT at 35.8%, with a RAG baseline at 32.3% at 100K scale. The difference in approach is the deployment model. Mnemosyne is a library and an MCP server over a local SQLite file. Hindsight and Honcho are memory systems whose published results come from their own runs, and the README's judge caveat means the 65.2% and 73.4% figures are not apples to apples.

Against a plain RAG pipeline, the contrast is sharper and more useful. RAG at 32.3% is a retrieve-and-stuff baseline: chunk, embed, fetch top-k, paste into the prompt. Mnemosyne adds episodic compression, an abstention path and a persistent store that multiple agent clients share. The 65.2% versus 32.3% gap is the argument for using a memory layer at all rather than wiring retrieval yourself. But the same table shows LIGHT at 35.8%, barely above RAG, which is a reminder that not every system labelled as agent memory beats a naive pipeline by much.

If your priority is the highest published end-to-end score and you are willing to run a service, the material points at Hindsight. If your priority is zero external services and one file you can copy, Mnemosyne is the one in this set that makes that claim.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-09-14. The recent release list shows v4.0.0b2 on 2026-09-10, v0.7.0 on 2026-09-09 and v4.0.0b1 on 2026-08-24. Two of those three are beta releases on a v4 line, while v0.7.0 sits on a separate version sequence. If you pin a version, check which line you are pinning, because the numbering does not read as a single progression.

Upgrade cost is mostly the dependency surface. The core install pulls PyYAML only. The extras pull more: embeddings brings fastembed, onnxruntime and sqlite-vec, llm brings ctransformers, llama-cpp-python and huggingface-hub, and sync brings cryptography. The mcp extra pins mcp>=2.0.0 with an exclusion for 2.1.0, which suggests a known bad release rather than a stable range. The Dockerfile installs mnemosyne-memory[mcp] into a python:3.11-slim base, so container users get the MCP extra and not the others unless they rebuild.

Licence is MIT, declared in both pyproject.toml and the Dockerfile's org.opencontainers.image.licenses label. MIT permits commercial use and modification with the copyright notice retained. It also means there is no patent grant, unlike Apache-2.0. The repository carries a CLA.md and a SECURITY.md, which are worth reading before contributing. None of this is legal advice; if the distinction between MIT and a patent-granting licence matters to your organisation, that is a question for your counsel.

What to check before you install Mnemosyne

The repository layout gives you a cheap way to audit the claims. docs/beam-benchmark.md is the methodology for the BEAM numbers, and the README points there for the full report. run_beam_all_scales.sh, run_beam_bench.sh and run_beam_clean.sh are the scripts behind those runs, so you can inspect what was measured rather than trusting the table. open_issues_summary.md and CHANGELOG.md are the fastest way to see what changed between v3.0.0 and the current tree, which is exactly the gap the benchmark caveat describes.

The README also states that a LongMemEval run is pending and that re-running both benchmarks on the current tree is tracked as issue #584. If your decision depends on retrieval quality, that issue is the thing to watch, not the withdrawn 98.9% figure. UPDATING.md exists in the top-level entries and is the place to look before you move between the v0.7.0 and v4.0.0b lines.

Editorial conclusion

Adopt Mnemosyne if you want agent memory that stays inside one SQLite file, you already run an MCP-capable client, and you can accept the published retrieval figures as they stand. Do not adopt it if you need a re-run benchmark on the current tree before committing, or if your agent memory must live behind a managed service with its own operations team. Before you commit, verify which version the BEAM numbers describe, whether the LongMemEval re-run tracked as issue #584 has landed, and whether the optional extras you need (embeddings, mcp, sync) install cleanly on your Python version.

Frequently asked questions

Official sources

1. License: MIT
2. mnemosyne-oss/mnemosyne on GitHub
3. Project website
4. README
5. Releases