# Hippocampus（海马体）

**Agent 记忆的巩固、修订与选择性遗忘引擎。**

现有记忆产品（Mem0/Letta/Zep 等）只做"存取"，Hippocampus 做记忆的**演变**：
去重合并、知识修订（版本链 + 时间旅行查询）、选择性遗忘（含跨合并记录的传播清扫）、
来源血缘与空闲期巩固。零依赖（纯标准库）、单机单文件 SQLite、可离线运行。

> 详细开发计划见 [docs/dev-plan.md](docs/dev-plan.md)，架构设计见
> [docs/architecture.md](docs/architecture.md)，实施日志见 [docs/journal.md](docs/journal.md)。

## 为什么需要它（立项依据，均为可复现事实）

| 问题 | 证据 |
|---|---|
| 遗忘与知识修订是缺失能力 | MemoryAgentBench 显示主流系统在多跳遗忘任务上 <5% |
| 记忆无限追加、不做巩固 | 语义重复膨胀；各产品无去重/合并生命周期 |
| sleep-time compute 无开源实现 | Letta 论文只有 137 星材料库，一年未维护 |
| 榜单分数不可审计 | judge 配置敏感（同一答案换 judge 分数大幅波动） |

## 快速开始

```bash
pip install -e .            # 或 pip install hippocampus-memory
python -m hippo.cli demo    # 30 天模拟用户端到端演示（离线，零成本）
```

SDK：

```python
from hippocampus import Hippocampus

hippo = Hippocampus("memory.db")
hippo.write("我的饮食是素食。", session_id="day-2")
hippo.write("我最近开始吃鸡胸肉了，不再只吃素。", session_id="day-20")

hippo.consolidate()                                  # 巩固：晋升/去重/修订/衰减
hippo.answer("用户现在的饮食是什么？")                 # -> 鸡胸肉（修订后的当前值）
hippo.answer("用户当时的饮食是什么？", as_of=ts)      # -> 素食（时间旅行）
hippo.forget(query="信用卡密码")                       # 遗忘 + 全库传播清扫
hippo.lineage(record_id)                              # 血缘树（回溯到原始会话）
```

CLI：

```bash
hippo write "我的名字是李明。" --db m.db
hippo search "名字" --db m.db
hippo consolidate --db m.db            # 加 --dry-run 预览，--heavy 附带反思
hippo asof "用户当时的饮食" --time 1760000000 --db m.db
hippo forget --query "信用卡密码" --db m.db
hippo purge --record-id <id> --db m.db  # GDPR 级物理清除（需先 forget）
hippo lineage --record-id <id> --db m.db
hippo daemon --db m.db                 # 常驻：定时轻巩固 + 空闲重巩固
hippo eval --out eval/reports/report.md
```

MCP（任意 MCP 客户端即插即用，暴露 6 个工具：memory_write / memory_search /
memory_forget / memory_provenance / consolidate_now / memory_stats）：

```json
{ "mcpServers": { "hippocampus": {
    "command": "python", "args": ["-m", "hippocampus.mcp_server", "--db", "memory.db"] } } }
```

## 核心设计

```
接口层   MCP Server │ Python SDK │ CLI
调度层   触发器（阈值/定时/空闲/手动）+ 预算熔断（run/daily 双上限，超支降级）
巩固引擎  晋升(PROMOTE) → 反思(REFLECT) → 去重合并(DEDUPE/MERGE)
         → 修订(REVISE, 版本链) → 衰减归档(ARCHIVE) → 遗忘(FORGET/PURGE)
存储内核  SQLite + 向量索引（矩阵缓存） + 不可变操作日志
```

三个关键不变量：

1. **双层数据模型**：情景层只追加（原始记忆真相源，永不改写）；语义层是巩固产物，
   带版本链（`supersedes`）与血缘（`derived_from`）。任何误操作可从情景层重建。
2. **操作日志是唯一状态源**：每次写入（INGEST）与巩固动作都记录为自包含的不可变
   op（含输出快照与嵌入向量），因此 ①`replay(ops)` 逐字节重建当前状态（有属性测试
   保证）②as-of 查询 = 截断重放 ③遗忘传播 = 沿 op 日志回溯依赖。
3. **遗忘是值锚定的**：除了按 op 日志传播，遗忘还以目标的 SPO 三元组与原文为锚，
   清扫所有引用该值的记录（含已归档的情景证据，防止日后反思"复活"被遗忘内容）；
   结构性依赖从剩余干净输入**重新生成**，无法安全重建才级联。

## 合成评测结果（`hippo eval`）

30 天模拟用户（25 条写入、12 个问题、1 次遗忘请求），naive = 同存储同检索但**无巩固
管线**，唯一变量是巩固：

| 类别 | naive | hippocampus |
|---|---|---|
| 稳定事实（名字/城市） | 3/3 | 3/3 |
| **知识更新·当前值** | **1/2**（答出旧值"素食"） | **2/2** |
| 知识更新·as-of 时间旅行 | 2/2 | 2/2 |
| 多跳推理（哥哥→生日→礼物） | 1/1 | 1/1 |
| 遗忘前可答 / 遗忘后弃答 / 改写探测 | 4/4 | 4/4 |
| **总计** | **11/12** | **12/12** |
| 活跃记录数（压缩） | 24 | **15**（重复闲聊合并、旧值归档） |

多 judge 协议（rule_v1 + rule_norm_v1）逐题一致率 100%，判分配置全部随报告开源。

性能（笔记本，numpy 开启）：1 万条记录建索引 0.7s；向量检索
**p50=3.8ms / p95=5.5ms**（矩阵缓存命中时；首查含缓存构建约 28ms）。

## 真实 benchmark：LongMemEval-S（ICLR 2025）

内置官方数据集适配器（`hippo eval-lme`，数据自动下载）。LongMemEval-S 分层抽样
每题型 10 题（共 60 题，每题约 53 会话 / 500 轮 haystack），确定性离线模式
（mock LLM），金标包含判定（近似，非官方 LLM-judge F1），naive = 同引擎关闭巩固：

| 题型 | BGE 嵌入 | 哈希词面嵌入 | naive（BGE） |
|---|---|---|---|
| knowledge-update | **7/10** | 5/10 | 6/10 |
| multi-session | **4/10** | 2/10 | 2/10 |
| single-session-assistant | 6/10 | 4/10 | 6/10 |
| single-session-user | 5/10 | 6/10 | 7/10 |
| single-session-preference | 0/10 | 0/10 | 0/10 |
| temporal-reasoning | 2/10 | 0/10 | 2/10 |
| **总计** | **24/60** | 17/60 | 23/60 |
| **问答时活跃记录数** | **163.4**（↓67%） | 360.2（↓27%） | 490.9 |

诚实解读：分数衡量**记忆管理与检索**在真实长程数据上的相对表现（离线 mock LLM
不做生成推理）；绝对值低于官方 LLM-judge 评分属预期。知识更新（7/10 vs 基线 5-6）
与多跳（4/10 vs 1-2）是巩固收益最大的题型；preference 类需要阅读理解，检索层
不单独解决。完整报告：
[longmemeval_bge_report.md](eval/reports/longmemeval_bge_report.md) ·
[longmemeval_report.md](eval/reports/longmemeval_report.md)。

## 接真实 LLM## 接真实 LLM

默认运行在确定性离线模式（mock LLM，零成本、可复现，评测即基于它）。生产接入：

```python
from hippocampus import Hippocampus, HippoConfig
from hippocampus.llm.providers import OllamaClient   # 或 LiteLLMClient

hippo = Hippocampus("memory.db",
                    llm=OllamaClient("qwen3:8b"),
                    config=HippoConfig(llm_provider="ollama", llm_model="qwen3:8b"))
```

巩固判定的 prompt 全部版本化于 `src/hippocampus/prompts/`（op 日志记录产生它的
prompt 版本）。嵌入默认为确定性哈希嵌入（词面重叠）；安装
`hippocampus-memory[local]` 可切换 BGE 语义嵌入。预算熔断：`run_cap_tokens` /
`daily_cap_tokens` 超限时巩固自动降级并记入 degrade 日志，LLM 响应按 prompt 哈希
持久缓存，重复实验零成本。

## 已实现 / 边界（诚实声明）

**已实现并有测试**：存储内核与操作日志（重放一致性属性测试）、晋升/去重/合并/
衰减、修订版本链与 as-of 查询、值锚定遗忘与传播、purge 物理清除（含 op 日志脱敏
后重放一致性）、反思（sleep-time）、预算熔断、CLI、MCP server（子进程握手测试）、
合成评测 harness 与多 judge 协议。32 个测试全绿（`python -m pytest tests/`，
无 pytest 时 `python tests/run_tests.py`）。

**已知边界**：
- 修订后的"陈旧依赖"（如旧值仍被反思摘要引用）目前**只报告不自动重写**
  （巩固报告的 `stale_report` 阶段），多跳级联重写是明确的后续工作。
- 向量检索是缓存化的暴力扫（O(n)），10 万级以上需换 sqlite-vec（接口已收窄为
  `vector_search`，见计划 R7）。
- 查询级遗忘按记录粒度生效；含密钥的混合记录整条隐藏（重新生成仅按 id 遗忘时
  触发）。
- LongMemEval 已接入（BGE 嵌入 + 包含判定）；LoCoMo/MemoryAgentBench 适配器
  待做；preference / temporal 类问题需要生成级推理，检索层不单独解决。
- 中文与英文 SPO 抽取均为规则模板子集；接真实 LLM（extract 任务）可扩展覆盖面。

## License

MIT