mnemosyne OS

September 22, 2026 · View on GitHub

mnemosyne OS

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.

Benchmark	Score	What it measures
LongMemEval	96.2	long-horizon conversational recall
LoCoMo	94.8	multi-session dialogue memory
BEAM (1M)	68.5	recall under a 1M-token context budget
BEAM (10M)	53.9	recall under a 10M-token context budget

Scores are out of 100.

🧩 Capabilities

Memory API	`Memory` / `AsyncMemory` / `MemoryClient` with a complete method surface: `add` `get` `get_all` `search` `update` `delete` `delete_all` `history` `reset` `close` `from_config`.
Four-dimensional scoping	`user_id` / `agent_id` / `run_id` / `app_id` — enforced by physical isolation: one SQLite file per scope, rather than shared rows with a filter applied.
Filter language	`eq` `ne` `gt` `gte` `lt` `lte` `in` `nin` `contains` `icontains` `wildcard`, with arbitrarily nested `AND`/`OR`/`NOT`.
Single-pass ADD-only extraction	One model call per write; memories accumulate and are never overwritten. Because nothing is rewritten, a bad extraction only introduces noise — it can never destroy a real fact.
Graph memory, always on	Entity linking and multi-hop traversal live in the same SQLite file. No external graph database required.
Multimodal ingestion	Accepts the OpenAI, Anthropic and Gemini image content shapes (plus audio). With a vision model configured it stores a description; without one it stores the reference — nothing is dropped.
Multi-signal retrieval	Semantic + BM25 keyword + entity graph + temporal + tag, fused with calibrated relevance floors and a lexical fallback.
Temporal reasoning	Observation dates, relative-time resolution, expiry semantics, and per-entity version chains.
Tiered memory	Hot / warm / cold tiers with forgetfulness economics: low-value memories are demoted and compressed, never silently deleted.
Lossless compression (AIC)	Compresses a memory into pointer + structured facts + content atoms. Numbers, dates, amounts and model numbers survive at every tier; `expand()` recovers the original text byte-for-byte and verifies its hash.
Hash-chained audit ledger	A SHA-256 chain; `verify_integrity()` detects tampering and names the exact entry that changed.
Async API and events	`AsyncMemory` for high-throughput writes, plus a persisted operation log so an accepted write stays visible across processes.
Chinese-optimised	Bigram tokenisation + FTS5 + a built-in synonym dictionary, with full Latin-script support.
Safety notary	Detects credentials, invisible Unicode and HTML injection before a write lands, and redacts at field level.

🔌 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)

Transport	Providers
stdlib HTTP	`openai` `openai_structured` `azure_openai` `azure_openai_structured` `ollama` `anthropic` `gemini` `groq` `together` `deepseek` `minimax` `xai` `sarvam` `openrouter` `litellm` `lmstudio` `vllm`
sdk	`langchain` `aws_bedrock`
built-in	`rules` — a deterministic offline extractor, which is why `add()` works with no model configured at all

Embedders (13)

Transport	Providers
stdlib HTTP	`openai` `azure_openai` `ollama` `gemini` `vertexai` `together` `lmstudio` `huggingface`
sdk	`fastembed` `langchain` `aws_bedrock`
built-in	`builtin` (128-dim, zero-dependency, deterministic) · `hashing` (any dimension, offline)

Vector stores (28)

Transport	Stores
embedded	`builtin` (one SQLite file holds both memories and vectors) · `memory` · `generic` (declarative REST)
stdlib HTTP	`qdrant` `pinecone` `elasticsearch` `opensearch` `weaviate` `upstash_vector` `turbopuffer`
sdk	`chroma` `pgvector` `milvus` `mongodb` `redis` `valkey` `azure_ai_search` `azure_mysql` `baidu` `cassandra` `databricks` `faiss` `langchain` `neptune` `oracledb` `s3_vectors` `supabase` `vertex_ai_vector_search`

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):

Tool	Purpose
`retain`	Store one memory
`recall`	Retrieve memories
`retain_batch$	\text{Bulk} \text{write}, \text{roughly} 15 \times \text{faster}
$forget`	Forget a memory — by id, or by locating it with a natural-language query
`capsule`	Compress a memory into pointer + facts + atoms
`expand`	Recover a capsule's original text byte-for-byte
`recall_health`	Read-only recall quality metrics
`consolidate`	Merge near-duplicate memories into one representative
`reflect`	Statistics, frequent entities, conflict detection, cognitive patterns
`dedup`	Detect duplicates and near-duplicates
`graph_query`	Knowledge-graph traversal
`temporal_query`	Version-chain queries
`list_projects`	List isolated projects
`doctor`	Health check — integrity, counts, disk, backend state
`stats`	Runtime statistics
`audit`	Audit-chain queries
`confidence_history`	Confidence trajectories
`memory/export-v1`	Export via the Memory Exchange Protocol
`memory/import-v1`	Import via the Memory Exchange Protocol
`memory/claim`	Take over memories from an external export

Client-compatible (11):

Tool	Purpose
`add_memory`	Save text or conversation history for a user/agent
`search_memories`	Semantic search with filters
`get_memories`	Structured filter + paginated listing
`get_memory`	Fetch one by id
`update_memory`	Overwrite text and/or metadata
`delete_memory`	Delete one
`delete_all_memories`	Clear a scope
`delete_entities`	Delete entities and cascade
`list_entities`	List users/agents/apps/runs
`list_events`	List memory operations
`get_event_status`	Poll an async operation

🌐 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.

Method	Path	Purpose
`GET`	`/v1/status/`	Liveness probe + live configuration report
`GET`	`/v1/providers/`	Every provider and its current availability
`POST`	`/v3/memories/add/`	Extract and store (async, returns an event id)
`POST`	`/v3/memories/search/`	Semantic search
`POST`	`/v3/memories/get-all/`	Filtered listing
`GET` / `PUT` / `DELETE`	`/v3/memories/{id}/`	Fetch / update / delete one
`DELETE`	`/v3/memories/`	Clear a scope
`GET`	`/v3/memories/{id}/history/`	Change history
`GET`	`/v1/event/{id}/` · `/v1/events/`	Poll / list operations
`GET` / `DELETE`	`/v2/entities/`	List / delete scopes
`POST`	`/v3/graph/{add,search,get-all,delete-all}/`	Graph memory
`POST`	`/v1/capsule/` · `/v1/expand/`	Lossless compression
`GET`	`/v1/integrity/`	Ledger verification
`GET` / `POST` / `DELETE`	`/v1/keys/`	API key management

🧠 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.