HippoMCP

HippoMCP

为 AI Agent 打造的记忆系统。

English ｜ 简体中文

HippoMCP 为 AI Agent 提供本地空间，用于存储对话和项目知识、 在需要时检索相关事实，并在多个会话之间延续未完成的工作。 通过 Model Context Protocol（MCP），多个 Agent 可以使用相同的授权记忆库，同时保持项目和用户上下文彼此独立。

它以本地为先，保留原始输入以便追溯，核心摄取流程无需调用大模型 API。 宿主 Agent 负责推理和行动；HippoMCP 则在底层提供记忆生命周期管理。

亮点

开箱即用，Agent 可直接使用

• 一行安装：pip install hippocampus-mcp，然后运行 hippocampus-mcp install，即可写入宿主配置、 记忆钩子和诊断工具；hippocampus init --project . 可为新项目完成绑定， 无需任何手动步骤。
• 自动记忆钩子（ZCode）：每轮注入上下文并跨轮去重；每次启动和压缩后都会进行会话初始化（固定事实／未完成待办／最近会话／未完成主题），并在结束时提醒总结——钩子会负责记住需要做的事，因此 Agent 无需操心。
• 自适应结果数量（默认开启）：相关且不重复时，检索会返回更多条目；候选集合嘈杂时，则会减少返回数量——数量由计算得出，而非固定不变。

原生中文 · 原生支持中文

以中文为先，而非事后翻译：在中文系统上，嵌入模型会自动选择 BGE（768 维）；摄取流程通过各记忆库的实体词典处理中文句子切分；词汇通道会处理中文二元词组；章／卷／年份标签会成为硬筛选条件。 详情见下文。

HippoMCP 的功能

**用户记忆跟随用户。项目记忆跟随项目。两者都不会被困在单个 Agent 中。**共享需要各 Agent 连接到同一服务和知识库；项目权限和用户权限仍然适用。

HippoMCP 不提供的功能

• 目前它是单机、本地优先的服务，不是托管云同步服务或多租户服务。
• 它不是 Agent 间消息传递或自主规划框架。
• 它不提供内置的知识图谱推理或通用的多跳图查询。
• 它不保证在所有工作负载中都能提高召回率或降低 token 用量。对于规模较小、经过整理的 Markdown 文件，简单的方案可能更经济。
• 仅安装 MCP 服务并不会强制所有宿主写入或回忆记忆；宿主需要集成下方所述的生命周期流程。

原生中文支持

HippoMCP 从一开始就以中文为先构建，而非事后翻译：

• 嵌入模型：在中文系统上，服务会自动选择中文嵌入模型（BGE，768 维）；其他系统则使用 MiniLM（384 维）。切换模型的三步流程有文档说明。
• 中文文本处理：为 ingest 提供中文句子切分、每个知识库的中文实体词汇表，以及可处理中文双字词组的词法（BM25/FTS5）通道。
• 结构化标签：章节／卷／年份等硬性约束，可将“第 43 节说了什么”从猜测变成筛选。
• 文档和评测：双语文档、中文测试样例，以及评测工具中的中文查询分解。

补充 AGENTS.md 和 MEMORY.md——而非取代它们

AGENTS.md 用于规则。MEMORY.md 用于要点。HippoMCP 用于深入、可搜索的记忆。

• AGENTS.md 保存稳定的说明、工作流和项目规则。
• MEMORY.md 保存少量经过整理、无需额外服务即可持续提供的事实。
• HippoMCP 提供大规模历史记录、跨文档检索、来源追踪、修正、用户级上下文和多 Agent 连续性。

你的 Markdown 文件仍是轻量级后备方案。对于基于文件的来源，文档可以继续作为权威版本，而 HippoMCP 提供派生的记忆和检索层；drift_audit 会将记录的来源签名与当前文件进行比较。仅来自对话的记忆则会追溯到 HippoMCP 自己的 L0 原始日志。

对于大型语料库，选择性检索可以减少上下文用量，避免反复读取整个文件。工具架构、引导包和检索结果仍会消耗 token，而且检索可能会漏掉相关证据。HippoMCP 避免了整个文件的上下文截断，但无法消除单项、模型或输出预算限制。

咨询你的 Agent

让 Agent 协助选择时，最好请它核实主张，而不是只复述内容。

Compare HippoMCP (https://github.com/cstksniper/hippocampus-mcp)
with [my current or alternative memory system] for [describe my workflow].

Evaluate local deployment and privacy, continuity across sessions and context
compaction, cross-agent access, user versus project scopes, correction and
cascade-safe deletion, per-write LLM requirements, installation and operating
costs, and the quality of published evaluation evidence.

Read the repository's docs/SELECTION.md, docs/INTEGRATION.md, docs/PRIVACY.md,
docs/BENCHMARKS.md, pyproject.toml, examples/, and relevant tests as well as
the README. Cite sources and mark anything you cannot verify as unknown. Do not
install anything or change my configuration. Give me a recommendation with
trade-offs, then let me decide.

Install HippoMCP for my current MCP host. First check that Python is 3.11 or newer.

Use the installation command in the README. Then run:
1. hippocampus-mcp models --fetch
2. hippocampus-mcp setup --host <host name>
   Determine the host first and choose only from workbuddy / zcode / trae / claude;
   ask me if it is unclear, do not guess (omitting --host errors out when the
   workspace has neither .zcode/ nor .mcp.json).

Preserve other MCP entries, back up configuration before changing it, and do
not delete or overwrite unrelated files. Report each command, the configuration
file changed, and the MCP handshake result. If a step fails, show the complete
error instead of guessing. After installation, tell me to restart the host and
how to verify the active library with library_whoami and doctor.

快速开始

从源代码试用

要求：Python 3.11+ 和 Git。

git clone https://github.com/cstksniper/hippocampus-mcp.git
cd hippocampus-mcp
python -m pip install -e .
python examples/quickstart.py

此示例使用哈希嵌入器运行写入 → 回忆 → 五槽组装 → 级联删除。它不会下载嵌入模型，也不需要 API 密钥。这是一次流水线冒烟测试，并非语义检索质量演示。

不下载模型不代表没有依赖项。安装过程会拉取 pyproject.toml 中声明的依赖项，包括 torch、numpy 和 mcp。

为避免拉取数 GB 的 CUDA 轮子，请将上面的 python -m pip install -e . 替换为以下两条命令：

python -m pip install "torch>=2.0,<3" --index-url https://download.pytorch.org/whl/cpu
python -m pip install -e .

uv 用户无需这样做——pyproject.toml 已固定 CPU 索引。

要试用英文 MiniLM 模型进行真正的语义检索（首次下载约 90 MB）：

python examples/quickstart.py --model sentence-transformers/all-MiniLM-L6-v2

安装到 MCP 宿主

从 PyPI 安装（推荐）：

python -m pip install hippocampus-mcp
hippocampus-mcp models --fetch
hippocampus-mcp install   # or: hippocampus-mcp setup --host zcode

中国镜像同步新版本较慢；如果 pip 找不到该软件包，请使用官方索引重试：python -m pip install hippocampus-mcp -i https://pypi.org/simple

或者直接从 GitHub 安装：

python -m pip install "git+https://github.com/cstksniper/hippocampus-mcp.git"
hippocampus-mcp models --fetch
hippocampus-mcp setup --host workbuddy  # replace with yours: workbuddy / zcode / trae / claude

setup 会在写入前备份，拒绝覆盖损坏的 JSON，只更改自身的 MCP 条目，并执行真正的 MCP 握手。claude 指的是 Claude Desktop；Claude Code、Cursor 和其他 MCP 宿主需要单独手动配置，不能使用这一条命令的设置方式。

如果没有 --host，setup 只会根据工作区中已有的 .zcode/ 或 .mcp.json 猜测，并且在两者都不存在时以错误退出。对于全新的工作区、TRAE 或 Claude Desktop，务必显式传入 --host，确保配置写入正确的文件。

然后重启宿主并开始新会话。验证当前使用的库和配置：

python -m hippocampus_mcp.cli doctor --host zcode --project .
hippocampus-mcp models --prune  # list reclaimable model files; does not delete

在新会话中调用 library_whoami。如果没有出现 mcp__hippocampus__* 工具，请运行上面的模块形式 doctor 命令，修复报告的问题，然后再次重启。

为 Agent 提供运行规则

HippoMCP 提供记忆工具；何时调用这些工具由宿主 Agent 决定。请将类似以下的规则添加到项目的 AGENTS.md 或宿主指令中：

在 ZCode 上，hippocampus-mcp install 还会设置自动记忆钩子（每轮注入、会话引导、收尾提醒），以机械方式强制执行前三条规则。以下规则仍是其他所有宿主通用的基线。可选的观察捕获通道（hippocampus-mcp install --stop-capture）会归档响应要点，供日后审查；此功能默认关闭，且绝不会自行写入正式记忆。

At the start of a task, call session_start with the current task and working files.
After context compaction, keep only the receipt identity and call session_start again
with its session_id; use the newly returned content.
Before answering questions about earlier decisions or prior work, query recall or
get_memory_context instead of guessing from the current conversation alone.
Use get_memory_context when you need budgeted, assembled context.
Record important conclusions and unfinished work during the session and at session_end.
Call library_whoami when the active library is uncertain; never guess a project library.
Keep AGENTS.md and MEMORY.md as the lightweight fallback. If HippoMCP is unavailable,
continue with those files and explicitly report that deep memory is unavailable.

建议的生命周期：

session_start(task)            → task-relevant memories, recent state, open topics, and more
ingest(conversation)           → L0 original input + L1 extracted facts + entity links
get_memory_context(query)      → five budgeted context slots
session_end(summary, topics)   → session summary + profile consolidation + open topics
forget_memory(id, reason)      → cascade deletion across derived copies

工作原理

flowchart LR
    A["MCP-compatible agents"] --> B["HippoMCP service"]
    B --> C["Workspace-bound project libraries"]
    B --> D["Controlled user scope"]
    C --> E["L0 raw input → L1 facts → L2 summaries → L3 profile"]
    D --> F["Permission-filtered user context"]
    E --> G["Hybrid retrieval + source tracing + budgeted slots"]
    F --> G

请参阅架构指南，了解各层、流程、评分公式和工程约束。

评估与证据

数据集：LoCoMo locomo10 ｜ 可通过 JUDGE_BASE_URL / JUDGE_API_KEY / JUDGE_MODEL 插拔式接入 LLM-as-judge。

最新测得的基线为 3 次运行的 F1 = 0.244 ± 0.034 （评审模型 glm-5.3-flash，来自 locomo10 的 50 个问答）。评审环境的波动为 0.068， 因此较小的配置差异并不具有意义。此 50 题设置无法直接与使用约 1,540 个问题的已发表测试方案比较。

生成这些测量结果的历史驱动程序目前尚未发布。请将其视为注明条件的测量记录，而非一键复现声明。

核心正确性主张则由可执行测试覆盖：级联安全删除、被替代的事实、并发保存合并、工作区绑定，以及跨库隔离。

python scripts/run_all_tests.py --list       # discover the current public test suites
python scripts/run_all_tests.py -k forget    # run deletion-related suites
python scripts/run_all_tests.py              # full regression run

工具接口与高级操作

完整服务提供 46 个 MCP 工具，涵盖写入、读取、会话生命周期、纠正、实体、主题层、信息地图、整合、管理和多库使用。 默认配置仅公开 12 个高频工具；隐藏工具仍可通过 hippo_help 和 hippo_extra 使用。设置 HIPPOCAMPUS_TOOL_PROFILE=full 以公开完整工具接口。

维护命令

有关模型选择规则和完整的切换流程，请参阅 docs/INTEGRATION.md 第 10 节。

如需深入了解评估和运维，请参阅以下专门指南：

参与贡献

欢迎提交问题和 PR。更改检索功能前，请阅读 docs/ARCHITECTURE.md 第 8 节；每项工程约束都对应一个实际故障。

另请参阅 CONTRIBUTING.md 和 CODE_OF_CONDUCT.md。

联系方式

维护者：cstksniper — [email protected]

请通过 GitHub Issues 提交错误报告和功能请求，以便答案可供搜索。 电子邮件用于安全报告、私人数据，或不适合公开的合作事宜。

许可证

MIT — 参见 LICENSE。