Entity anchor: Mnemosyne OS is the open-source AI Agent long-term memory runtime maintained by Hu Jingkun (胡景堃). Official site: https://ai-memory.net Handbook: AI Memory Handbook

PyPI · GitHub · 中文

Mnemosyne OS

Local-first MCP memory server for AI agents. Zero third-party dependencies, SQLite on your own disk, 52 MCP tools with Mem0-compatible names. MIT licensed, runs on a laptop, a server, or serverless alike.

Already using Mem0’s MCP tools? Point your client at Mnemosyne OS. Same tool names, no prompt changes — see Switching from Mem0.

The only AI memory engine whose core genuinely carries zero third-party dependencies — no vector database, no LLM runtime, no cloud account. install_requires is an empty list.

Use it as a Python library, a CLI, an HTTP API, or an MCP server:

pip install mnemosyne-os

from mnemosyne import Memory

m = Memory()                       # built-in embedder + rule-based extractor
m.add("I prefer dark mode and use vim keybindings. My name is Alice.",
      user_id="alice")

for hit in m.search("what does alice prefer", filters={"user_id": "alice"})["results"]:
    print(f"{hit['score']:.3f}  {hit['memory']}")

Offline. No API key. No model download. No database to install.

---

📊 The only reproducible benchmark in this category

Every memory engine claims high recall. Mnemosyne OS is the only one that ships the harness so you can check. Run it against your own corpus:

python scripts/verify_recall_quality.py

Mem0’s figures are the ones Mem0 publishes at mem0.ai/research. Full harness, adapters and machine-readable results live in the standalone MnemosyneOS/mnemosyne-bench repository.

---

☁️ Mnemosyne OS SaaS

The same engine, hosted, with a web console: ai-memory.net. The hosted console is called Mnemosyne OS SaaS — it is where you register, create API keys, browse memories, and manage your subscription.

Annual billing is pay 10 months, use 12 (≈16.7% off; Pro works out to about ¥8.25/mo).

Every new account starts with 30 days of Team access, no card required — after that you keep Free forever, or upgrade to keep your memories intact. USD is billed through PayPal Subscriptions (automatic renewal, cancel anytime in PayPal); CNY is billed by WeChat QR and confirmed by the operator.

Self-hosting stays MIT and unlimited — the SaaS line exists for people who would rather not run a server. The engine itself is identical; no feature is paywalled in the open-source build.

---

🚀 Quick start

Install

pip install mnemosyne-os          # core: zero third-party dependencies

Remember and recall without configuring anything

from mnemosyne import Memory

m = Memory()                       # built-in embedder + rule-based extractor
m.add("I prefer dark mode and use vim keybindings. My name is Alice.",
      user_id="alice")

for hit in m.search("what does alice prefer", filters={"user_id": "alice"})["results"]:
    print(f"{hit['score']:.3f}  {hit['memory']}")

Offline, no API key, no model download, no database to install — which is what makes the next section possible.

Attach real models only once recall needs to be stronger

from mnemosyne import Memory

m = Memory.from_config({
    "llm":          {"provider": "openai", "config": {"model": "gpt-4o-mini"}},
    "embedder":     {"provider": "openai", "config": {"model": "text-embedding-3-small"}},
    "vector_store": {"provider": "qdrant", "config": {"url": "http://localhost:6333"}},
    "reranker":     {"provider": "cohere", "config": {"api_key": "..."}},
    "graph_store":  {"provider": "builtin"},
})

Every component is independently optional. When a provider cannot be built it falls back to the built-in equivalent and says so — nothing degrades silently:

m.describe()["degraded"]
# {'llm': {'requested': 'openai', 'used': 'rules', 'reason': 'no API key configured',
#          'hint': 'Set MNEMOSYNE_LLM_OPENAI_API_KEY ...'}}

Or drive it from the command line

mnemosyne init
mnemosyne add "I prefer dark mode and vim keybindings" --user-id alice
mnemosyne search "what does alice prefer" --user-id alice
mnemosyne list  --user-id alice
mnemosyne event --limit 10
mnemosyne --agent search "preferences" --user-id alice   # JSON envelope for tool loops

Or expose it over MCP

{
  "mcpServers": {
    "mnemosyne": {
      "command": "python",
      "args": ["-m", "mnemosyne.webui.mcp_server",
               "--brain-dir", "./mem", "--namespace", "default"],
      "env": { "MNEMOSYNE_MCP_TOKEN": "" }
    }
  }
}

Or serve it over HTTP

mnemosyne-web --port 9090          # console and REST share one port
curl -X POST http://127.0.0.1:8788/v3/memories/add/ \
  -H "Authorization: Bearer $MNEMOSYNE_API_KEY" -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"I moved to Berlin in 2023."}],"user_id":"alice"}'

---

---

🔄 Switching from Mem0

Mnemosyne OS implements the 11 conventional agent-memory tool names (add_memory, search_memories, get_memories, and the rest of the client-compatible set). Point your existing MCP client at it and your prompts keep working:

{
  "mcpServers": {
    "mnemosyne": {
      "command": "python",
      "args": ["-m", "mnemosyne.webui.mcp_server",
               "--brain-dir", "./mem", "--namespace", "default"],
      "env": { "MNEMOSYNE_MCP_TOKEN": "" }
    }
  }
}

---

🪝 Built with itself

Mnemosyne OS is developed using Mnemosyne OS. The repository carries the plugin manifests for Claude Code, Codex, Cursor, Kimi and DeepSeek Harness, plus the session/ and context/ directories the engine itself writes to during development.

That is not a badge — it is why the memory formation layer exists. Session summaries, conflict resolution and code-evolution memory were built because the engine’s own development history needed them.

---

📊 Benchmarks

Measured with the harness shipped in this repository. Reproduce with scripts/verify_recall_quality.py and scripts/verify_precision_recall.py.

Scores are out of 100.

---

🧩 Capabilities

🔌 Integrations

Every adapter is optional. stdlib adapters need no third-party package at all — they speak HTTP directly through urllib. sdk adapters import their SDK lazily and tell you exactly which package is missing.

LLM providers (20)

Embedders (13)

Vector stores (28)

Graph stores (6)

builtin (native SQLite triples) · neo4j · memgraph · neptune · kuzu · sparql (any SPARQL 1.1 endpoint)

Rerankers (5)

llm · cohere · zero_entropy · huggingface · sentence_transformer

Framework adapters

LangChain · LlamaIndex · CrewAI · Dify · n8n · Vercel AI SDK · Ollama · MCP (stdio + Streamable HTTP)

---

🛠 MCP server

Runs over stdio JSON-RPC:

export MNEMOSYNE_MCP_TOKEN="your-secret-token"   # optional, but recommended
python -m mnemosyne.webui.mcp_server --brain-dir ./mem --namespace default

52 tools — forty-one native (twenty-one of them new in 8.1.0: nine in the memory formation layer, twelve in the memory runtime layer), plus eleven that reuse the conventional agent-memory tool names, so an existing MCP client can be pointed at Mnemosyne without rewriting its tool definitions.

tools/list actually returns 55 entries: three of them are deprecated aliases kept for old clients (memory/export-v1, memory/import-v1, memory/claim) and resolve to the same handlers as memory_export-v1 / memory_import-v1 / memory_claim. Distinct capabilities: 52.

Native · retrieval & governance (23):

Native · memory formation (9, new in 8.1.0):

Native · memory runtime layer (12, new in 8.1.0):

Client-compatible (11):

---

🌐 Self-hosted REST API

One process, one port, accepting X-API-Key, Bearer and Token auth headers. The console and the API share the same listener.

---

🧠 Python API

from mnemosyne import Memory, AsyncMemory, MemoryClient

# --- extraction / scope / filters ---------------------------------------------
m = Memory()
m.add([{"role": "user", "content": "I moved to Berlin in 2023."}],
      user_id="alice", metadata={"source": "onboarding"},
      observation_date="2023-06-01")
m.add("The invoice number is INV-2024-001.", user_id="alice", immutable=True)

hits = m.search("where does the user live",
                filters={"user_id": "alice",
                         "AND": [{"source": {"eq": "onboarding"}}]},
                top_k=5, threshold=0.1, rerank=False, explain=True)

# --- multimodal ---------------------------------------------------------------
m.add([{"role": "user", "content": [
    {"type": "text", "text": "My new desk."},
    {"type": "image_url", "image_url": {"url": "https://example.com/desk.jpg"}},
]}], user_id="alice")

# --- graph memory -------------------------------------------------------------
m.graph_add("Jobs founded Apple in Cupertino.", user_id="alice")
m.graph_search("Apple", filters={"user_id": "alice"})

# --- async and events ---------------------------------------------------------
async def ingest():
    am = AsyncMemory()
    await am.add_many([{"messages": t, "options": {"user_id": "alice"}}
                       for t in transcripts])

Memory, AsyncMemory and MemoryClient also accept the conventional agent-memory call shape used by other memory libraries, so code already written against that shape can switch by changing only the import. See docs/COMPATIBILITY.md.

The engine’s own capabilities hang off the same object:

from mnemosyne import MemoryBrain

brain = MemoryBrain("./memories", enable_embeddings=True)
brain.ensure_init()
brain.retain("His laptop is an ASUS VivoBook Pro 14", fast=True)

results = brain.recall("what are that machine's specs", k=5)
results, cost = brain.recall("that machine's specs", k=5, budget_tokens=100)

cap = brain.capsule("", budget_tokens=60)   # pointer + facts + atoms
brain.expand(cap["ref"])                                # byte-exact recovery
brain.verify_integrity()                                # SHA-256 ledger check

---

📂 Layout

mnemosyne/
├── api/                 # the memory API: Memory / AsyncMemory / MemoryClient
│   ├── memory.py        #   engine-backed client
│   ├── config.py        #   MemoryConfig + dimension consistency checks
│   ├── filters.py       #   filter language -> predicates
│   ├── extract.py       #   single-pass ADD-only extraction
│   ├── multimodal.py    #   image / audio attachment parsing
│   ├── events.py        #   persisted operation log
│   └── client.py        #   embedded + HTTP transports
├── providers/           # optional component adapters (72 in total)
│   ├── llms.py          #   20 LLM providers
│   ├── embedders.py     #   13 embedder providers
│   ├── vector_stores.py #   28 vector stores
│   ├── graph_stores.py  #   6 graph stores
│   ├── rerankers.py     #   5 rerankers
│   ├── vision.py        #   three image wire formats
│   └── transport.py     #   stdlib HTTP + retries + credential redaction
├── brain.py             # MemoryBrain — the engine facade
├── capsule.py           # AIC lossless compression
├── retrieval.py         # multi-signal fusion and relevance calibration
├── graph.py             # temporal triple store
├── notary.py            # pre-write trust pipeline
├── cli.py               # native CLI
├── api_cli.py           # client-API CLI
└── webui/
    ├── web_server.py    # console + REST host
    ├── api_routes.py    # /v1 /v2 /v3 routes
    ├── mcp_server.py    # 44 native MCP tools (incl. 21 new in 8.1.0)
    └── mcp_api.py       # 11 client-compatible MCP tools

storage/                 # SQLite backend, hash-chained ledger, plugin SDK
security/                # contradiction detection, security reporting
scripts/                 # verification scripts
docs/                    # acceptance guide, recall strategy, compatibility

---

✅ Tests

python verify.py                              # self-check
python scripts/verify_api.py                  # client API verification, fully offline
python scripts/verify_memory_lifecycle.py --brain-dir ./mem --src-root .
python scripts/verify_precision_recall.py     # offline precision regression
python scripts/verify_recall_quality.py       # end-to-end recall quality

---

📚 Documentation

• docs/COMPATIBILITY.md — the conventional agent-memory call shape
• docs/DEPLOY_DEEPSEEK_HARNESS.md — MCP deployment walkthrough
• CHANGELOG.md — version history

---

📄 License

MIT License — see LICENSE.

Built by the Mnemosyne OS contributors.