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

![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Version](https://img.shields.io/badge/version-1.1.0-orange)
![MCP](https://img.shields.io/badge/MCP-server-purple)
[![CI](https://github.com/17861102832/wanyimem/actions/workflows/ci.yml/badge.svg)](https://github.com/17861102832/wanyimem/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/wanyimem)](https://pypi.org/project/wanyimem/)
[![Live Demo](https://img.shields.io/badge/Live-Demo-00d4aa)](https://17861102832.github.io/wanyimem/)

> 🎬 **Live Demo**: [交互式演示页](https://17861102832.github.io/wanyimem/) · [源码 `docs/demo.html`](https://github.com/17861102832/wanyimem/blob/main/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

```bash
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):
>
> ```bash
> pip install "git+https://github.com/17861102832/wanyimem.git"
> ```

## CLI & Automation

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

```bash
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.):

```json
{
  "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.:

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

## Quick Start (Library)

```python
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`](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

- [中文安装与使用指南](docs/INSTALL_CN.md)
- [README 中文版](README.zh-CN.md)
- [示例 MCP 配置](examples/mcp.example.json)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately via [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE) © 2026 Zhao Xikun