Hippocampus（海马体）

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

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

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

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

Related MCP server: agent-memory

快速开始

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

SDK：

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：

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）：

{ "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 = 同存储同检索但无巩固 管线，唯一变量是巩固：

多 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 = 同引擎关闭巩固：

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

接真实 LLM## 接真实 LLM

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

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