Handoff

handoff-mcp

Agent 跨会话记忆。 通过 Model Context Protocol 为 Claude 提供持久化、跨项目的交接功能——它会记住目标、决策、走过的弯路以及下一步要做什么，让下一次会话不必从零开始。

Claude 会忘记会话之间的一切。handoff-mcp 为它提供一种能跨越上下文窗口的记忆：它会跟踪工作的进展——目标、决策及其理由、走过的弯路、未决问题和下一步；在会话结束时生成一份按优先级排序、符合令牌预算的简报，让下一次会话恢复时就知道你上次停在了哪里。

它不是上下文转储。它与基于相似度的记忆存储（mem0 / OpenMemory 风格）有两个不同之处：

1. 时序上的取代关系。 新决策会撤销旧决策；被撤销的决策绝不会出现在后续简报中。记忆反映的是世界的当前状态，而不是一堆互相矛盾的事实。
2. 确定性简报。 简报由可解释的排序器（时效性 + 重要性 + 取代关系）生成，而不是由大模型生成——因此结果可复现，并且会控制在令牌预算内（事件内容的软上限；参见限制）。
3. 你自己的存储，多设备使用。 保险库是你自己的私有 git 仓库，而不是托管服务——因此记忆可以随你在不同设备间同步（启动时拉取、检查点时推送、实体合并无冲突），不受供应商锁定。参见多设备同步。

状态：v0.4，早期版本。 核心功能（保险库、简报、取代关系、关键词搜索、跨项目回忆）已经过测试且稳定；语义、整合、导入和多设备同步层均为可选且较新。它依赖 Agent 在恰当时机调用工具——关于这些方面的实际限制，请参见限制。

它也支持跨项目：一个保险库，每个项目各自命名空间。简报按项目范围生成（我在这里做到哪一步了），但 search_memory 会搜索所有项目——所以当你说*“我们在某个项目里做过 X”*时，Claude 可以找到并调出另一个项目中的相关决策。

目录

• 演示：两个会话
• 基准测试
• 工作原理
• MCP 工具
• 费用和 API 密钥
• 语义回忆（可选）
• 记忆整合（可选）
• 导入现有历史记录
• 快速开始
• 连接你的 MCP 客户端 — Claude、Cursor、Codex、Kilo Code、…
• 记忆存储位置
• 多设备同步（可选）
• Agent 集成
• 限制
• 开发
• 许可证

演示：两个会话

python examples/two_sessions_demo.py — 会话 1 执行并停止；会话 2 是一个仅凭简报恢复的全新进程。

会话 1 记录其进度（并且中途改变了一次主意）：

log_event("goal",     "Ship the finance agent: income/expense tracking…")
d = log_event("decision", "Store transactions in a flat JSON file.")
log_event("decision", "Use SQLite instead of JSON — need queries.", supersedes=[d])  # retracts ↑
note_entity("Architecture", "SQLite-backed; LLM summary calls run in a worker.")     # durable
log_event("deadend",  "Provider streaming API times out on long months; needs chunking.")
log_event("question", "Recurring transactions: templates or materialised rows?")
log_event("next_step","Write the SQLite schema, then the ingest function.")
checkpoint("Chose SQLite; finance schema is next.")

会话 2 调用 get_brief()，得到的只有当前状态——已撤回的 JSON 决策不见了：

# Hand-off brief — agent-hub

## Goal
- Ship the finance agent: income/expense tracking with scheduled summaries.
## Next step
- Write the SQLite schema for transactions and categories, then the ingest function.
## Decisions
- Use SQLite for transactions instead of JSON — need queries for summaries. See [[Architecture]].
## Dead ends (tried & failed)
- Tried the provider's streaming API for the summary job — times out on long months. Don't retry without chunking.
## Open questions
- Should recurring transactions be modelled as templates or materialised rows?
## Related knowledge
- [[Architecture]] — SQLite-backed; LLM summary calls run in a worker.

已撤回的“扁平 JSON 文件”决策从未出现。与图关联的 [[Architecture]] 笔记会自动纳入。简报约为 170 个 token。

跨项目回忆也是如此——search_memory("timeout chunking", scope="all") 会从另一个项目中找出一项决策：

- [hermes]    In the Hermes project we solved long-job timeouts by chunking requests.
- [agent-hub] Tried the provider's streaming API for the summary job — times out on long months…

基准测试

两个离线、确定性的基准测试——无需 LLM，也无需网络——因此可在任何地方生成完全相同的结果，并由 tests/test_benchmark.py 固定。完整数据、方法以及复现方式：benchmarks/RESULTS.md。

1. 单独测试决策取代（benchmarks/supersession_benchmark.py）。一个项目的决策在 4 个主题上经过 8 条陈述不断演变；每个主题都有一项决策被后续决策撤回（JSON→SQLite、cookies→JWT，等等）。按决策检索（因此每条过时事实都可被检索到）时，扁平日志与当前视图的对比：

模式	泄漏的过时信息	保留的当前信息
决策取代关闭（扁平日志）	4 / 4	4 / 4
决策取代开启（当前视图）	0 / 4	4 / 4

决策取代会恰好移除已撤回的决策，同时保留每一项当前决策——同时评估保留的当前信息，也意味着空答案不能冒充胜利。没有事实取代事实这一概念的相似度存储，其表现与关闭决策取代的行相同。

2. 简报与朴素转储（benchmarks/brief_reconstruction.py）。恢复中的会话实际读取的内容——受预算限制且考虑决策取代的简报，与粘贴回整个日志的对比。随着历史增长，转储会急剧膨胀，并持续携带每项撤回信息；简报则保持在上限内（软上限），没有矛盾，同时保留所有关键事项（例如，228 个事件时：3063→217 个 token，缩减 14×，矛盾从 3 个降至0）。

这些测试如实衡量该机制，而不是安排与另一种存储进行正面对比——要公平地跨系统运行，必须在相同检索条件下，并使用我们无法在 CI 中复现的 LLM 端点（参见 ADR-0008）。

本 README 中此处及其他位置的“token”均按 len(text) / 4 估算（与模型无关），并非使用真实分词器统计。

工作原理

Markdown 库是真实数据源——可供人阅读、可在 Obsidian 中打开，数据保存在你的磁盘上。SQLite + FTS5 索引由该库派生，可随时重建；它为排序、token 预算和跨项目全文搜索提供支持。

设计原理请参见 docs/architecture.md 和 ADR。

MCP 工具

工具	Claude 调用时机
get_brief(project?, token_budget?)	会话开始时——加载上次会话的进度。
log_event(type, content, importance?, supersedes?, supersedes_query?, project?)	工作过程中——记录目标、决策、死胡同、文件、问题和后续步骤。supersedes 通过 ID 将先前的事件标记为已失效；如果不知道事件 ID，supersedes_query 会将最匹配的同类型活跃事件标记为已失效（ADR-0007）。
search_memory(query, scope=current|all, limit?)	用户提及过去或其他项目的工作时。limit 限制结果数量（默认值为 10）。每条结果都包含事件 ID，可直接传给 log_event 的 supersedes。
note_entity(name, content, project?)	记录持久的项目知识（架构、约定、组件）。
checkpoint(summary?, project?)	会话结束时——完成会话并生成简报。传入与记录时相同的 project（默认使用会话的项目）。
consolidate(project?, older_than_days?)	将旧会话压缩为持久笔记（可选启用，需要大模型）。
sync(remote_url?)	跨设备同步记忆——拉取、提交并推送知识库的私有 git 远程仓库（可选启用）。首次调用时传入仓库 URL 进行配置；之后直接调用即可同步。请参阅多设备同步。

此外还提供一个 MCP 资源 session://brief 和一个提示词 resume，用于在会话开始时自动加载简报。

log_event 类型：goal、decision、deadend、file、question、next_step。

费用和 API 密钥

无需订阅，无需 API 密钥。核心功能免费且完全在本地运行——你的记忆以普通文件的形式存储在磁盘上，handoff-mcp 绝不会连接外部服务（没有托管服务，也没有遥测）。

功能	需要模型或密钥吗？
记忆、简报、替代、关键词搜索、跨项目、导入器	不需要——本地、离线、免费
语义检索 （可选）	默认不需要（使用 hashing 或本地 sentence-transformers）；只有选择 openai 后端时才需要自备兼容 OpenAI 的密钥
整合 （可选，偶尔使用）	需要大模型——自备密钥（费用几美分，极少运行；不属于高频路径）或使用本地模型

因此，大部分功能无需花费，也无需密钥。可选层要么在本地运行，要么使用你自己的服务商——你永远不会被锁定在我们的服务中。

语义召回（可选）

默认使用关键词搜索（FTS5/bm25），无需额外配置。你可以启用语义层，通过倒数排名融合（Reciprocal Rank Fusion）结合关键词相似度和嵌入相似度：

HANDOFF_SEMANTIC=1 handoff-mcp     # turn the layer on (default: hashing backend)

你选择的后端决定了它是否真正理解改述。 默认的 hashing 后端是词法基线——它会对词元进行哈希，因此可以实现模糊词法匹配（并展示混合流水线），但当措辞不同时，无法根据含义进行召回。若要真正支持改述容忍的召回，请选择使用学习得到的嵌入的 local 或 openai。

可插拔的嵌入后端，通过 HANDOFF_EMBEDDER 选择——单个服务，无需分叉：

后端	安装	支持改述？	备注
hashing（默认）	—	否 — 词法匹配	确定性、离线、零依赖的玩具基线（特征哈希）。适合演示/测试；不具备真正的语义能力。
local（推荐）	pip install -e ".[semantic-local]"	是	离线 sentence-transformers；无需密钥，但会安装 torch。默认模型 Qwen/Qwen3-Embedding-0.6B（多语言，含俄语，1024 维，Apache-2.0）。
openai	pip install -e ".[semantic-openai]"	是	支持任何兼容 OpenAI 的端点（OpenAI、Together、可自托管的代理等）。设置 HANDOFF_EMBED_BASE_URL / OPENAI_BASE_URL 和 HANDOFF_EMBED_API_KEY / OPENAI_API_KEY。

# Example: semantic recall via any OpenAI-compatible endpoint
pip install -e ".[semantic-openai,semantic]"
export HANDOFF_SEMANTIC=1 HANDOFF_EMBEDDER=openai
export HANDOFF_EMBED_BASE_URL=https://your-openai-compatible-endpoint/v1 HANDOFF_EMBED_API_KEY=sk-…
export HANDOFF_EMBED_MODEL=text-embedding-3-small

设计（参见 ADR-0004）：

• 通过 Embedder 协议接入可插拔的嵌入器——默认的 hashing 确定且无需依赖；openai / local 可在不改动其他部分的情况下接入，提供真正的语义能力。
• sqlite-vec 是加速器，而非必需项（.[semantic]）——向量以 BLOB 形式持久化，搜索通过精确余弦扫描实现；若已安装且可加载 sqlite-vec，则 vec0 表会提供快速 KNN 搜索，并返回相同的排名靠前结果。
• 确定性摘要不会查询嵌入——语义只影响 search_memory。
• 重新排序——召回结果（任何模式）都会根据相关性、时效性（时间衰减）和重要性的确定性加权结果重新排序，让新近且优先级高的记忆优先显示。无需 LLM；传入 rerank=False 可获取原始相关性顺序。
• 增量嵌入——事件不可变，因此启动时只会嵌入新事件（复用缓存的向量）；若嵌入模型的维度发生变化，缓存会自动失效。这让较重的本地模型也能实用。

若要改用更轻量、更快速的本地模型，请设置 HANDOFF_EMBED_MODEL（例如 Alibaba-NLP/gte-multilingual-base，305M/768 维——该模型需要设置 HANDOFF_EMBED_TRUST_REMOTE_CODE=1）。

记忆整合（可选）

对于长期运行的项目，情景日志会不断增长——这是容量问题，而不只是索引问题。整合（“休眠”）会将其压缩：

HANDOFF_LLM_MODEL=gpt-4o-mini handoff-mcp   # enables the consolidate tool

consolidate(project?, older_than_days?) 会提炼旧的已完成会话中的活跃决策，写入持久实体笔记（架构、决策、死路等），随后将原始记录归档到 <project>/archive/，并从活跃索引中移除。因此，知识库会缩小，但已有摘要呈现的持久知识仍会保留。

• 这是唯一会调用 LLM 的步骤；除非设置 HANDOFF_LLM_MODEL，否则此功能默认关闭（兼容 OpenAI；复用嵌入器的端点设置）。摘要、搜索和取代操作仍保持确定性。
• 只会提炼活跃事件——撤回的决策绝不会被永久留存。死路会作为警示性事实保留。
• 原始记录会归档而非删除（可审计、可撤销）。

参见 ADR-0006。

导入现有历史记录

从已有数据初始化项目记忆，让它从第一分钟起就能发挥作用，而不是一片空白：

handoff-import git ./my-repo --project my-project        # commit history → memory
handoff-import claude session.jsonl --project my-project # a Claude Code transcript

• git 会将每次提交转换为一项决策（提交主题）和一条涉及文件的备注，并使用提交日期添加时间戳——完全确定，不使用大模型。
• claude 会从 Claude Code 对话记录中提取第一个提示词作为目标，并将文件编辑记录为文件事件（尽力而为）。
• 导入具有幂等性（ID 根据来源生成），因此重新运行时只会添加新内容。数据会写入同一个共享保险库（HANDOFF_VAULT）。

快速入门

uv venv && uv pip install -e ".[dev]"

# Run the two-session demo: session 1 works, session 2 reads the brief.
python examples/two_sessions_demo.py

连接 MCP 客户端

Claude Code——一分钟安装（推荐）：

/plugin marketplace add kirill-sviridov/handoff-mcp
/plugin install handoff-mcp@handoff-mcp

此操作会一并配置服务（通过 uvx 从 PyPI 自动安装——需要将 uv 添加到 PATH）、用于加载记忆协议的会话启动钩子，以及 session-handoff / session-planning 技能。下面的手动配置适用于其他客户端（或喜欢显式配置的用户）。

handoff-mcp 使用 stdio 上的标准 MCP，因此适用于任何 MCP 客户端——Claude、Cursor、Codex、Kilo Code、Windsurf、Cline、VS Code、Zed 等。各处的配置基本相同，只有文件位置（以及 Codex 的格式）不同。

标准配置——Claude、Cursor、Kilo Code、Windsurf、Cline 和大多数其他客户端使用的 mcpServers JSON 代码块：

{
  "mcpServers": {
    "handoff": {
      "command": "handoff-mcp",
      "env": {
        "HANDOFF_VAULT": "/path/to/your/vault",
        "HANDOFF_PROJECT": "my-project"
      }
    }
  }
}

客户端	配置位置
Claude Code	claude mcp add handoff -- handoff-mcp，或项目中的 .mcp.json
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）
Kilo Code	Settings → MCP → Add Server → Local (stdio)，或 .kilocode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline / Roo Code	扩展的 MCP 面板 → cline_mcp_settings.json
VS Code（Copilot）	.vscode/mcp.json——请注意下方的不同架构

Codex CLI 在 ~/.codex/config.toml 中使用 TOML（或运行 codex mcp add）：

[mcp_servers.handoff]
command = "handoff-mcp"
[mcp_servers.handoff.env]
HANDOFF_VAULT = "/path/to/your/vault"
HANDOFF_PROJECT = "my-project"

VS Code 使用 "servers" 和显式类型：

{ "servers": { "handoff": { "type": "stdio", "command": "handoff-mcp",
  "env": { "HANDOFF_VAULT": "/path/to/your/vault", "HANDOFF_PROJECT": "my-project" } } } }

注意：

• handoff-mcp 必须位于 PATH 中——将其安装为工具 （uv tool install handoff-mcp；或从源码安装：uv tool install git+https://github.com/kirill-sviridov/handoff-mcp） 或者，在检出目录中使用 "command": "python", "args": ["-m", "handoff_mcp.server"]。
• 为每个 Agent/仓库设置 HANDOFF_PROJECT；确保所有 Agent/仓库的 HANDOFF_VAULT 都指向同一个共享保险库（见下文）。从 0.4.0 开始，如果未设置 HANDOFF_PROJECT，项目默认使用 git 根目录/当前工作目录的目录名，因此无需任何配置即可按仓库划分命名空间；显式设置时仍以显式值为准。在 Claude Code 下，目录使用 CLAUDE_PROJECT_DIR（会话的项目目录），而不是服务的当前工作目录（从 0.4.1 开始）。
• 使用 uv 从检出目录运行？请使用 uv run --project /path/to/handoff-mcp handoff-mcp，不要使用 --directory：--directory 会将服务的当前工作目录切换到检出目录，因此未设置 CLAUDE_PROJECT_DIR 的客户端会把每个项目都归入 handoff-mcp。

记忆存放位置

一个中央知识库，其中每个项目都有自己的文件夹：

~/.handoff-mcp/vault/            # HANDOFF_VAULT (default; override per machine)
├── .index.db                    # derived SQLite index — rebuildable, gitignore it
├── my-project/
│   ├── sessions/<id>.md         # episodic notes
│   └── entities/<Name>.md       # durable knowledge
└── another-project/…

• **所有项目共用一个知识库，而不是每个代码库各用一个。**跨项目检索（search_memory）只有在所有项目都存放于同一个存储库时才能生效。因此，请将每个 Agent 的 HANDOFF_VAULT 指向同一个目录，只需更改 HANDOFF_PROJECT 即可。
• 知识库位于代码仓库之外，因此不会意外提交到工作项目中——项目代码库可以保持整洁。
• **想要备份或在多台设备间同步？**知识库是纯 Markdown，因此可以单独对其进行版本管理（使用私有 git 仓库、Obsidian Sync、Dropbox 等）。如需跨设备内置 git 同步——启动时拉取、创建检查点时推送、无冲突的实体合并——请参阅多设备同步；handoff-sync --setup 会为你配置远程仓库，并将派生索引添加到 gitignore。
• **更喜欢让记忆跟随单个代码仓库？**将 HANDOFF_VAULT 指向该仓库内的目录（例如 ./.handoff）——但这样搜索只能看到该项目。建议使用共享知识库。

多设备同步（可选）

你的知识库就是一个私有 git 仓库，因此记忆可以随你在不同设备间同步。 同步完全由你选择启用——如果没有配置 git，记忆也能在单台设备上完整运行。

层级	设置	效果
仅本地（默认）	无需设置	完整记忆功能，单台设备，无需账户
手动	运行一次 handoff-sync --setup <private-repo-url>	按需运行 handoff-sync（或 sync 工具）来拉取、提交和推送
自动	完成上述设置并设置 HANDOFF_AUTO_SYNC=1	会话开始时拉取，创建检查点时推送

通过 git 内置的 union 驱动程序，实体笔记可以在不同设备间顺畅合并（在知识库的 .gitattributes 中设置 */entities/*.md merge=union，由设置程序写入）。 在没有 Shell 的客户端中（例如 Cursor），只需让 Agent 同步——sync 工具无需终端。设置需要可用的 git 身份验证（gh auth login 或 SSH 密钥）；如果推送失败，命令会准确告知你需要修复什么。

Agent 集成

*了解何时使用它。*服务器不会主动向模型推送任何内容；由模型决定何时调用工具。以下四层机制从适用范围最广到功能最强，可确保可靠使用：

1. 工具描述（内置）——每个工具都会说明何时调用。适用于任何 MCP 客户端。

2. 服务 instructions（内置）——服务在连接时发送的一套简短流程（开始时加载摘要，工作时记录，结束时创建检查点）。 适用于 Claude Desktop、Cursor 及其他 MCP 客户端。

3. Claude Code 技能（skills/）——定义工作流，并且关键的是，会根据日常用语触发：

   • session-handoff——当你说“转到下个会话”或“今天就到这里”时，Agent 会知道自行执行 checkpoint。 它还会在首次使用时初始化项目的指令文件（根据客户端使用 CLAUDE.md， 或 AGENTS.md / .cursor/rules/handoff.mdc / .windsurfrules）。
   • session-planning——可选的配套技能：将大型任务拆分为适合单次会话完成的部分，并将计划保存到记忆中。

   将技能复制到你的技能目录即可安装：

   cp -r skills/handoff skills/planning ~/.claude/skills/   # user-wide
   # or .claude/skills/ inside a specific project
   

   （技能是 Claude Code / claude.ai 的功能；其他 Agent 依赖第 1–2 层。）

   对于非 Claude 客户端，请使用 handoff-init CLI 将记忆块添加到项目的指令文件中（可重复运行）：

   handoff-init                 # CLAUDE.md
   handoff-init --client codex  # AGENTS.md   ·   --client cursor / windsurf
   

4. Claude Code 插件——一次安装即可启用第 1–3 层；请参阅连接 MCP 客户端。

对于 Claude Code，还应将以下内容添加到 CLAUDE.md，这样即使没有技能，摘要也会自动加载：

会话开始时调用 get_brief。工作时使用 log_event 记录决策、走不通的方向和下一步——每次调用记录一条独立事项（用 1–2 句话说明原因），不要总结整个会话；通过 [[Entity]] 引用持久笔记。停止前调用 checkpoint。当我提到过去的工作或其他项目时，调用 search_memory。

局限性

如实说明 v0.4 的边界，让你了解自己将采用什么：

• 取代关系必须明确指定，而非推断。 handoff-mcp 不会自行判定某条记忆是否取代了另一条——Agent 必须通过 supersedes（按 id）或 supersedes_query（按最佳匹配）明确说明。这是有意为之（这样才能让简报具备确定性且可审计），但也意味着记忆的质量取决于 Agent 是否确实记录了撤回信息。它不会像尝试从 LLM 提取信息的存储那样，悄悄去重矛盾信息。例外：next_step——新记录的下一步会自动使先前会话中仍有效的下一步失效（基于规则，并记录在事件中；ADR-0009）。如果已失效的步骤仍然有效，请重新记录。
• 它依赖 Agent 的自律性。 服务不会主动推送任何内容；其价值取决于模型是否在合适的时机调用 log_event / get_brief / checkpoint。工具说明和技能会对此进行提示，但如果客户端从不调用这些工具，知识库就会是空的。跨会话记忆的质量取决于实际记录的内容。
• 默认的语义后端（hashing）只匹配词汇，不识别释义。 要实现真正的释义召回，需要使用 local 或 openai（参见语义召回（可选））。确定性简报本身绝不使用嵌入。
• 令牌预算是软限制。 它限制事件内容；章节标题和“相关知识”区块属于额外内容，因此渲染后的简报可能会略微超出预算。它能确保简报随着历史记录增长仍保持有界且精简——但不是严格的字节数上限。
• 单进程新鲜度。 多个进程／Agent 可以共享一个知识库（SQLite WAL 和忙碌超时机制允许写入者共存），但运行中的进程会在启动时刷新其知识库视图（_sync_index）——它能实时获取自身的写入内容，但只有在下次启动时才能获取其他进程的新事件（sync——手动执行，或通过 HANDOFF_AUTO_SYNC 在获取简报时拉取——会在拉取新事件时于会话中途重新建立索引）。对于单个进程内的并发线程，对共享索引的访问会通过锁进行串行化。
• 适用于个人／团队规模。 排序时会将项目的事件加载到内存中；处理数千个会话没问题，但并未针对数百万个会话进行优化（如果将来需要，可参见 ADR-0005 了解针对性修复）。

开发

uv pip install -e ".[dev]"
ruff check . && mypy && pytest
python examples/two_sessions_demo.py        # the hand-off in action
python examples/demo_presentation.py         # paced/narrated version (for recording a GIF)
python examples/stdio_smoke.py              # run it as a real stdio MCP server
python benchmarks/brief_reconstruction.py   # brief vs naive full-dump
python benchmarks/supersession_benchmark.py # supersession on vs off, in isolation

许可证

MIT — 详见 LICENSE。