WanYi Memory Core 万忆中枢

永不遗忘的全量记忆系统 — Event-sourced long-term memory for AI agents: process memory, mistake books, experience crystallization, confidence-based decision blocking, counterfactual branches, cross-domain analogy, trajectory replay, proactive partner, semantic vector retrieval, reranker, memory graph, time decay and metacognitive knowledge-gaps. Ships as a local-first MCP server with 23 tools. Your data never leaves your machine.

🎬 Live Demo: 交互式演示页 · 源码 docs/demo.html

---

Why this is different

Most memory systems store your data in the cloud, need a heavy dependency stack, or only do keyword search. wanyimem is local-first, single-file SQLite, and installs with one dependency (numpy).

	wanyimem	typical memory server
Data	never leaves your machine (zero telemetry)	cloud / SaaS
Infra	SQLite single file, no separate vector DB	Qdrant / Neo4j / Postgres
Defaults	shadows the agent, blocks high-risk actions, opens counterfactual branches	stores & retrieves
Resources	runs on 2-core / 2GB	heavier
Evolves	zero-participation (learns from your mistakes automatically)	manual "remember this"

23 MCP tools, open source (MIT), Python 3.10+, pip install wanyimem.

---

Why

LLM agents forget. Every chat window is amnesia: preferences, lessons, and hard-won experience evaporate when the session ends.

WanYi Memory Core is a local-first, full-quantity, self-evolving memory system:

• Event sourcing — an append-only WAL is the single source of truth. Nothing is ever deleted; decay only affects retrieval ranking.
• Semantic recall — hybrid retrieval: BM25 keywords + local Chinese embedding (BAAI/bge-small-zh-v1.5) + reranker (BAAI/bge-reranker-base) + knowledge-graph expansion + explicit time decay. Vector search is hybrid itself: exact cosine below ANN_MIN_COUNT, and a sqlite-vec ANN pre-filter + exact re-rank above it — so it stays fast at scale without sacrificing recall quality.
• Metacognition — when recall is weak, the system admits it and records a knowledge-gap instead of hallucinating an answer.
• Decision guardrails — high-risk actions (all-in, revenge-trading, force-push, rm -rf) trigger confidence-based blocking with counterfactual branches: you see what would have happened if you had listened.
• Zero-participation evolution — no need to say "remember this"; the system decides what to store, consolidates overnight, and surfaces weekly trajectory reviews.

Install

pip install wanyimem            # core
pip install "wanyimem[all]"     # + vector/reranker models + sqlite-vec ANN (use [ann] for ANN only)

Requires Python 3.10+. Models (embedding ~95MB, reranker ~1.1GB) are downloaded on first use from HuggingFace; set HF_ENDPOINT=https://hf-mirror.com if you are in mainland China.

Before the PyPI release lands, you can also install directly from GitHub (identical code):

pip install "git+https://github.com/17861102832/wanyimem.git"

CLI & Automation

Beyond the MCP server, wanyimem ships two console commands after pip install wanyimem:

wanyi-export --db memory.db --out memory.md   # readable, diff-able Markdown mirror of all memory (read-only)
wanyi-auto --db memory.db                     # one AutoMoat pass: honest counterfactual auto-settlement + consolidation + analog patrol
wanyi-auto --db memory.db --loop 3600         # periodic scheduler (daemon background; off by default)

wanyi-export renders the event-sourced store into a human-readable, version-controllable Markdown mirror (grouped by 道/法/术, plus mistakes / experiences / knowledge-gaps / counterfactual branches / cross-domain patterns). wanyi-auto automates the guardrails: it honestly settles overdue counterfactual branches (marking them expired rather than fabricating a winner), runs sleep + deep consolidation, and surfaces the cross-domain analog patterns most worth recalling.

Quick Start (MCP)

Add to your mcp.json (Claude Desktop, Cursor, Trae, etc.):

{
  "mcpServers": {
    "wanyi": {
      "command": "python",
      "args": ["-m", "wanyi.memory_core"],
      "env": {
        "WANYI_STORE_DIR": "C:/path/to/your/memory"
      }
    }
  }
}

Env keys are "Chinese-first, ASCII-fallback": the new WANYI_STORE_DIR (recommended, more portable) and the legacy 万忆中枢_STORE_DIR both work. Bare python depends on PATH and may fail; prefer an absolute interpreter path, or pip install wanyimem then use "command": "wanyi".

Then any agent can call the 23 tools, e.g.:

万忆记录见闻 → "2026年5月基金大跌时我死扛不止损，亏了18%才割肉。"
万忆召回记忆 → query "认赔离场到底对不对"   # semantic match even with zero shared keywords
万忆置信度决策检查 → "我要全仓梭哈"          # BLOCK if confidence is low, with historical mistakes

Quick Start (Library)

from wanyi import WanYiCore

engine = WanYiCore()
engine.tool_record_memory(
    content="止损纪律：亏损超过8%必须无条件卖出",
    layer="法", mem_type="principle",
)
resp = engine.tool_recall_memory("认赔离场到底对不对", limit=5)
for m in resp["memories"]:
    print(m["content"], m.get("_rerank_score"))

Features

Area	Capability
Storage	SQLite + append-only event WAL; 道/法/术 three-layer half-lives
Retrieval	Keyword BM25 + vector (bge-small-zh) + reranker (bge-reranker-base) + graph expansion + time-decay fields
Metacognition	knowledge-gap auto-record, stats self-check, honest "I don't know"
Guardrails	confidence-based decision blocking, counterfactual branches with auto-settlement, cross-domain analogy bridging
Proactivity	daily brief on LOAD, due-branch reminders, weekly trajectory replay, risk-keyword alert
Growth	mistake book, experience crystallization, overnight consolidation, evolution queries
Privacy	fully local, zero telemetry, no cloud dependency

Public benchmark (LongMemEval) — session-level retrieval, full results in benchmark/RESULTS.md. Core (BM25 + graph, no models) reaches Recall@5 = 0.960 / MRR = 0.907 on s_cleaned (with ~40 distractor sessions). Reproduce via python benchmark/longmemeval_run.py.

Benchmark — reproducible mini LongMemEval (14 keyword-mismatched cross-session fact queries, run via python benchmark/recall_benchmark.py):

Version	Recall@5	MRR
Core (keyword BM25 + knowledge-graph, no models)	1.000 (14/14)	0.857
Full (bge-small-zh vector + bge-reranker-base rerank)	1.000 (14/14)	0.857

Every query is intentionally phrased with different keywords than its answer (e.g. 本地数据库怎么提高并发写 → WAL模式, 记忆系统最怕什么 → 事件溯源), so 14/14 reflects genuine semantic recall, not string matching. The knowledge-graph channel (active in the core, model-free) already lifts BM25 to parity here; the vector + reranker path shows its edge on larger-scale semantic expansion ("pip install wanyimem[all]" downloads the models).

Architecture (1.1.0)

wanyi/
├── core_base.py    # constants · four-factor scoring · MemoryDB (SQLite engine)
├── engine.py       # WanYiCore · 23 MCP tools · MCP_TOOLS registry · JSON-RPC dispatch
├── transport.py    # MCP stdio: newline-delimited JSON (+ legacy Content-Length frame compat)
├── memory_core.py  # compat facade — every legacy import path keeps working
├── version.py      # single source of truth for the version
└── hooks / gardener / confidence / vector_memory / reranker / mirror / auto_moat ...

• Standards-compliant stdio: speaks MCP newline-delimited JSON and still parses legacy LSP Content-Length frames.
• Compat facade: wanyi.memory_core, python -m wanyi.memory_core, python -m wanyi and the wanyi console script all keep working after the 1.1.0 module split.
• 33 tests (pytest, py3.10–3.12 CI matrix + ruff): stdio protocol compliance, module-split integrity (symtable-based missing-global guard) and a full 23-tool smoke pass.

Docs

• 中文安装与使用指南
• README 中文版
• 示例 MCP 配置

Contributing

See CONTRIBUTING.md. Report vulnerabilities privately via SECURITY.md.

License

MIT © 2026 Zhao Xikun