mnemosyne OS

mnemosyne OS

PyPI · GitHub · 中文

Mnemosyne OS 8.0.0 — a zero-dependency, local-first AI memory system. Graph memory, multimodal ingestion, reranking, temporal reasoning, a hash-chained audit ledger, lossless compression, and 31 MCP tools.

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. It runs on a laptop, a server, or serverless infrastructure alike.

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

---

🚀 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": "<random 32+ chars>" }
    }
  }
}

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"}'

---

📊 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

31 tools — twenty native, 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.

Native (20):

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("<memory_id>", 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    # 20 native MCP tools
    └── 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/ACCEPTANCE_GUIDE.md — acceptance criteria and the script for each
• docs/RECALL_STRATEGY.md — how retrieval is assembled and budgeted
• docs/KNOWN_DEFECTS.md — confirmed defects, with measurements and fixes
• docs/DEPLOY_DEEPSEEK_HARNESS.md — MCP deployment walkthrough
• CHANGELOG.md — version history

---

📄 License

MIT License — see LICENSE.

Built by the Mnemosyne OS contributors.