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 .
Local-first MCP memory server for AI agents. Zero dependencies, SQLite on your own disk, 52 MCP tools with Mem0-compatible names. MIT.
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:
Benchmark
Mnemosyne OS
Mem0 (published)
LongMemEval
96.2
94.4
LoCoMo
94.8
92.5
BEAM 1M
68.5
64.1
BEAM 10M
53.9
48.6
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.
Permanent cold memory · cross-namespace recall · unlimited audit history · full export
Team
$19.9/seat/mo · $199/seat/yr
¥29.9/seat/mo · ¥299/seat/yr
Everything in Pro · multi-user namespaces · team policies · audit report export
Compliance Add-on
$9.9/mo
¥19.9/mo
Monthly only. Optional add-on on top of Pro or Team (not a standalone tier): scheduled verify_integrity reports, deletion-proof export, data-residency configuration
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
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:
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
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:
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.
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
🔌 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.
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):
Tool
Purpose
retain
Store one memory
recall
Retrieve memories
retain_batch
Bulk write, roughly 15× 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
User profile card: three tiers (stable identity / preferences & constraints / current situation) + open items, ready to splice into a system prompt. max_tokens is a hard cap — over-budget content is dropped by tier (situation → open → preferences), never mid-sentence.
memory_inject
Context injection pipeline: query construction → four-path recall → RRF fusion → rerank → in-budget injection. Returns ready-to-inject text plus four quota ledgers. Prefer this over recall when you are preparing a prompt.
recall_catalog
Progressive disclosure, catalog level: returns title + one line + expansion cost only, never the body. Decide which are relevant, then expand 1–2 with expand_memory — injection cost drops from O(everything) to O(catalog + a few).
expand_memory
Progressive disclosure, expansion: one memory's body + unified envelope + graph neighbours + evidence chain. Pairs with recall_catalog; neighbours come from the knowledge graph, so "which modules did this decision affect" is answerable.
memory_envelope
Unified memory envelope: eight-class typing + four-dimensional scope + evidence chain + dual time axis + TTL + SPO structure. Omit memory_id for a whole-library eight-class distribution.
memory_consolidate
Three consolidation paths: episodic→semantic, episodic→procedural, failure→negative memory. Idempotent — the same source batch never generates twice.
memory_metrics
Metrics: Chat (5) + Working (4) + Coding (4). Honest by design — insufficient data returns {value:null, status:"insufficient_data"} rather than 0, because 0 and "no data" are different things.
memory_cascade_delete
Cascade delete: soft-delete the source → invalidate derived conclusions → clear the retrieval cache → mark dependent summaries stale. hard=true for physical delete; run dry_run=true first to see dependents.
memory_mask
Mask: replace the body with a placeholder but keep the record skeleton, preserving context length and prefix so KV-Cache reuse is not broken. Prefer this over delete when the user says "don't keep this". action=unmask reverses it.
topic_summarize
L3 topic summary: merge several L2 session summaries in one project into "where this project stands now". Merging is deterministic (goal newest, decisions accumulate, pending newest only). persist=true stores it and records pointer.children.
memory_trace
Pointer-chain backtracking: walk L3→L2→L1, returning each layer's content, the turn ranges it covers and its message_ids. Answers "which sentence did this conclusion come from".
memory_hot_path
Hot-path buffer: action=enable turns on async writes (the hot path only enqueues); action=status inspects the queue; action=flush waits for the queue to land — the read-consistency barrier you must pass before reading right after writing.
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
上次檢查時間:2026-10-28。 Local-first MCP memory server for AI agents. Zero dependencies, SQLite on your own disk, 52 MCP tools with Mem0-compatible names. MIT.