Mnemosis

把 AI 的记忆，从“无限存储 + 搜索”改造成“会记住、会遗忘、会整理、会自我怀疑”的系统。

Mnemosis is a human-inspired memory layer for AI agents. Most "AI memory" systems are just storage with semantic search bolted on: they save everything and recall by similarity. Mnemosis instead treats memory as a lifecycle — remembering, reinforcing, consolidating, forgetting, and reconciling — the way human memory actually works.

🍼 New here? Start with the 奶龙级入门教程——基本功能介绍版 — a teacher-style, zero-background tour of every feature (Chinese).

🗄️ Want the storage layer explained? See 存储功能介绍（技术人员版） (Chinese).

中文说明：README.zh-CN.md · English: README.md

Install

pip install git+https://github.com/liyexiaoyi/Mnemosis.git

Zero runtime dependencies (pure Python stdlib + SQLite). No server, no cloud embeddings required — optional embedder hooks only.

PyPI 版（pip install mnemosis）发布后会在这里同步更新。

SQLite 存储适合单进程/低并发场景；多个 Agent 并发写入时建议串行访问或接入 外部数据库适配层。

Related MCP server: aimemory

Quick start

from mnemosis import MemoryEngine
from mnemosis.types import MemoryKind, SourceRecord, SourceType

engine = MemoryEngine("memory.db")  # pass a path for persistence

engine.remember(
    "The user prefers Chinese for technical discussions.",
    kind=MemoryKind.SEMANTIC,
    source=SourceRecord(origin=SourceType.USER),
    cues=["user", "language", "preference"],
    importance=0.9,
)

for r in engine.recall("what language does the user prefer?", top_k=3):
    print(f"[{r.item.kind.value}] {r.score:.2f}  {r.item.content}")

check = engine.check("what is the user's favorite movie?")
print("knowledge gaps:", check.gaps or "none")

engine.sleep()  # offline consolidation: dedupe, promote, detect contradictions

中文快速开始

pip install git+https://github.com/liyexiaoyi/Mnemosis.git

from mnemosis import MemoryEngine
from mnemosis.types import MemoryKind, SourceRecord, SourceType

engine = MemoryEngine("memory.db")
user = SourceRecord(origin=SourceType.USER)

engine.remember(
    "用户喜欢用中文讨论技术问题。",
    kind=MemoryKind.SEMANTIC,
    source=user,
    cues=["语言", "偏好"],
    importance=0.9,
)
engine.remember(
    "昨天一起修了 SQLite 锁死的问题。",
    kind=MemoryKind.EPISODIC,
    source=user,
    cues=["SQLite", "锁死"],
)

for r in engine.recall("用户用什么语言聊天？", top_k=3):
    print(f"[{r.item.kind.value}] 相关度 {r.score:.2f}  {r.item.content}")

一分钟完整演示（记住 → 检索 → 新旧矛盾 → 睡眠整合 → 元认知 → 遗忘回收）：

pip install git+https://github.com/liyexiaoyi/Mnemosis.git
python examples/demo.py          # 仓库内

不想安装？可以在线体验：

• Google Colab 打开演示笔记本 （部分地区访问不了 Colab，可改用下面的方式）

• GitHub Codespaces 一键打开：云端环境， 打开终端执行 python examples/demo.py 即可

• 下载 examples/Mnemosis_demo.ipynb 后，用本地 Jupyter 或百度 AI Studio 打开

How it works

Mnemosis is a memory layer, not a recorder: your agent decides what to save (via remember / remember_turn) and what to ask (via recall / check). Inside, memories are stored, decay, consolidate and self-check the way human memory does.

flowchart LR
    A[Agent / MCP client] -->|remember / remember_turn| M[MCP server]
    A -->|recall / check| M
    M --> E[MemoryEngine]
    E -->|store| DB[(SQLite)]
    E -->|keyword + n-gram + optional embeddings| R[Retrieval]
    E -->|forgetting curve| F[Forgetting & spaced review]
    E -->|sleep consolidation| S[Consolidation: dedupe / link / resolve]
    E -->|metacognition| C[Check: gaps / contradictions]
    R --> DB
    F --> DB
    S --> DB

原理：Mnemosis 照着人脑记忆机制给 agent 做长期记忆——remember 写入、recall 联想检索、遗忘曲线自动衰减、sleep 睡眠式整理（去重/建联/消矛盾）、 check 知道自己不知道（这里的意思是，比如你问了他一个他没有记住的事情，他就会回答不知道，而不是乱编一个答案）。它不是录音机，谁调用、存什么由你和 agent 决定。

Use with your AI client (MCP)

One-line MCP integration for Claude Desktop, Cursor, Codex and any MCP client:

{
  "mcpServers": {
    "mnemosis": {
      "command": "mnemosis-mcp",
      "args": ["--db", "/path/to/memory.db"]
    }
  }
}

Windows users: if the client reports that mnemosis-mcp is not found, add Python's Scripts directory to PATH, or use an absolute path, e.g. "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\mnemosis-mcp.exe".

Full guide (including Cursor and Codex configs): docs/mcp-quickstart.md.

Remote deployment (HTTP)

The MCP server also speaks Streamable HTTP (POST), so it can run on a VPS or NAS and be reached from other machines by URL:

mnemosis-mcp --transport http --host 0.0.0.0 --port 8000 --db /data/memory.db

Point an MCP client at http://your-server:8000/ (Claude Desktop, Cursor and Cherry Studio accept remote MCP URLs). Put it behind a reverse proxy (Caddy/nginx) with TLS and basic auth before exposing it to the internet.

Or run it in Docker:

docker build -t mnemosis .
docker run -d -p 8000:8000 -v mnemosis-data:/data mnemosis

Memory is a single SQLite file in /data, so backups are just one file.

Command line

mnemosis --db memory.db remember "用户喜欢用中文讨论技术问题。" --kind semantic
mnemosis --db memory.db recall "用户喜欢什么语言？"
mnemosis --db memory.db sleep
mnemosis --db memory.db check "用户最喜欢的电影是什么？"
mnemosis mcp --db memory.db   # or: mnemosis-mcp --db memory.db

By default the MCP server hides experimental tools from tools/list (they stay callable). --expose core shows only the 16 everyday tools (remember/recall/check/review/stats/...), --expose advanced (default) adds the rest except experimental, and --expose experimental shows all 100+ tools.

Semantic embeddings (optional)

Without an embedder, recall uses zero-dependency keyword + n-gram matching. For real semantic recall, point the MCP server at an embedding API:

# local Ollama (e.g. nomic-embed-text)
mnemosis-mcp --db memory.db --embedder ollama

# any OpenAI-compatible endpoint (DashScope, OpenAI, ...)
export MNEMOSIS_EMBEDDING_API_KEY=sk-...
mnemosis-mcp --db memory.db --embedder openai --embedding-model text-embedding-v3

Vectors are cached next to the DB (memory.db.cache) and indexed in memory.db.vec, so repeated recalls skip embedding calls.

The in-memory embedding cache is bounded by an estimated memory budget (default 512 MB, configurable via embed_cache_memory_limit_mb): Python lists of floats count ~32 bytes per element and compact arrays (numpy.ndarray/array.array) count by their real nbytes, so the cap reflects actual process memory. An entry-count floor (100k) remains as a guard for extreme vector dimensions.

For the strongest retrieval quality, enable a dense embedder (Ollama or any OpenAI-compatible endpoint): on the independent LongMemEval benchmark this mode reaches parity with mem0 on turn recall while keeping ingestion ~13x faster. Lexical-only mode stays available and is several times faster per query (dense re-ranking only embeds the top-64 lexical candidates).

After enough usage, call the calibrate_decay MCP tool to fit the forgetting curve to your real retrieval history (median survival span -> per-user decay rate). The fitted rate is persisted in the SQLite database and automatically reloaded the next time you open it.

To see what the memory actually holds, call memory_map (topics with counts/retrievability plus a weak/ok/strong histogram), or render a Chinese chart locally:

python benchmarks/render_memory_map.py --db memory.db --out memory_map.svg

Automatic memory saving

Mnemosis never eavesdrops: whoever owns the agent decides what is worth remembering. The easiest automatic pattern is one tool call per turn:

mnemosis-mcp --db memory.db

Then tell your agent in its system prompt:

After every user/assistant exchange, call remember_turn with the raw text of the turn. It splits sentences, extracts cues and stores them. Call recall (or check) before answering when the user references earlier topics.

remember_turn is a single call that stores the whole turn as segmented memories with automatic cues, so agents do not need to hand-write remember calls for each fact.

For temporal and multi-session questions ("how much did I spend in total", "what changed since last month"), LongMemEval bad-case analysis shows the biggest accuracy gains come from prompting, not retrieval: ask the agent to build a chronological timeline of the recalled memories, sum amounts when the question asks for a total, and treat the most recently dated fact as authoritative when facts conflict (knowledge updates). Mnemosis returns recalled items with dates and confidence, so the agent can apply exactly those rules.

Batch ingestion (importing large histories)

remember_many imports a batch of memories with the same per-item semantics as remember (semantic dedupe, cues, term index, association graph), but commits storage, term rows and links in bulk:

engine.remember_many([
    {"content": "用户喜欢喝咖啡。", "kind": MemoryKind.SEMANTIC, "cues": ["用户"]},
    {"content": "上周修了空调。", "kind": MemoryKind.EPISODIC},
    {"content": "阿丽在2026年3月1日买了笔记本。", "kind": MemoryKind.EPISODIC},
])

10,000 memories take about 13 seconds via remember_many vs ~70 seconds in a single-remember loop. When a vector index + Ollama/OpenAI embedder is enabled, embedding is also batched (100 texts per call, chunked by size, with automatic retry on 429/5xx).

If a batch embedding still fails halfway (the memories are stored but some have no vector), lexical recall keeps working and the gap can be repaired in one pass:

rebuilt = engine.rebuild_missing_vectors()   # or the MCP tool rebuild_vectors

Threading

MemoryEngine is designed for one agent loop per instance: SQLite access and the shared intent / suppression state are internally locked, so light concurrent read/write calls are safe. If you fan one engine out across many threads, serialize the high-level calls yourself.

Testing

python -m unittest discover -s tests -q   # 395 unit tests
python benchmarks/locomo_bench.py --mode keyword   # LoCoMo-style long dialogue

Performance (10,000 memories, local machine)

On the independent LongMemEval benchmark (20 questions, cloud Qwen judging), the dense mode matches mem0 on every retrieval metric (@1 0.5 / @5 0.8 / @10 0.8), scores slightly higher on answer accuracy (0.45 vs 0.40) and ingests 1.4x faster (44s vs 62s per question).

A larger retrieval-only run (50 questions) confirms exact parity on every metric (@1 0.42 / @5 0.78 / @10 0.86 / gold-answer-token hit@5 0.38) with 1.37x faster ingestion (44.6s vs 61.2s per question).

The end-to-end run with cloud Qwen judging (30 questions, mem0 vs dense) again shows identical retrieval (@1 0.433 / @5 0.767 / @10 0.867) and equal answer accuracy (0.433 both), with 2.1x faster ingestion (28.0s vs 58.8s per question).

A second cloud-judged sample (different seed, 20 questions, dense mode) scored 0.6 answer accuracy, so the accuracy range across samples is ~0.43-0.60 (50 combined questions ≈ 0.5), consistent with mem0-tier retrieval and answer quality.

A 2026-08-13 retrieval-only rerun (20 questions, seed 42) confirms exact dense-mode parity with mem0 on every retrieval metric (@1 0.5 / @5 0.8 / @10 0.8 / gold-token hit@5 0.35) while ingesting ~5.8x faster (10.8s vs 62.4s per question).

The sentence-segmented ingestion pattern (remember_turn, one call per conversation turn) is even stronger on the same 20-question set: turn recall @1 0.60 / @5 0.85 / @10 0.90, ahead of mem0 on every retrieval metric while ingesting ~4.8x faster. For long multi-session conversations, store turns with remember_turn and recall with recall / recall_fused.

Cloud-judged end-to-end (qwen3.7-plus answers + judging, same 20 questions) confirms the pattern: mnemosis seg answer accuracy 0.65 vs mem0 0.45, with retrieval also ahead and ingestion ~5x faster. (The benchmark initially capped answer generation at 300 tokens, truncating the mandated timeline + ANSWER line for seg contexts; raising it to 1200 removed that artifact.)

At a 50k-input / 25k-active real-Chinese store, recall is 26-85ms and sleep consolidation ~2.3s after the large-store scaling work (batched term df, batched REM links, generic-cue skipping).

At 100k input (50k active, real Chinese): batch ingestion is ~6.8 minutes (was >2h before the bulk upsert + generic-cue skip work), hit recall ~4ms, zero-hit recall ~5ms (dual fallback: recent 150 + strongest 50, so old high-importance core facts still surface), sleep ~1.3s after the trusted row fast path (SQLite reads skip per-row validation/normalization).

Independent public benchmark (LongMemEval)

Mnemosis is also validated against an external, non-self-built benchmark: LongMemEval (Wu et al., ICLR 2025), which uses ~115k tokens of real chat history per question and heavy interference. The comparison with the official mem0 package is in benchmarks/longmemeval_bench.py.

First fetch the official dataset (cached copies are detected and reused):

python benchmarks/fetch_longmemeval.py            # oracle + S set (~290 MB)
python benchmarks/fetch_longmemeval.py --all      # also the 2.7 GB M set

If Hugging Face is unreachable from your network, download the files from huggingface.co/datasets/xiaowu0162/longmemeval-cleaned and point the script at the local folder:

python benchmarks/fetch_longmemeval.py --source-dir /path/to/downloads

Then run a head-to-head against mem0 (requires a Python with mem0 installed, plus Ollama or a cloud embedder/LLM for the dense mode):

python benchmarks/longmemeval_bench.py --data work/longmemeval_s_cleaned.json --questions 20

License

MIT. See LICENSE.

Contributing

PRs, issues and new benchmark scenarios are welcome — see CONTRIBUTING.md. Every change should come with a test or a measured benchmark result.