session-handoff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Session Handoff — Multi-Agent Three-Tier Memory System

会话交接 — 多Agent三层记忆系统

The Problem

问题背景

Claude Code sessions are stateless. When a session ends, all context is lost. The next session starts from scratch — no memory of what was done, what's in progress, or what decisions were made.

This skill solves that by writing structured handoff notes to Apple Notes before each session ends, and reading them back at the start of the next session via a SessionStart hook.

Claude Code会话是无状态的。会话结束后所有上下文都会丢失。下次会话将从头开始，不记得之前完成的工作、进行中的任务，或是已经做出的决策。

本技能通过在每次会话结束前将结构化的交接笔记写入Apple Notes，并在下次会话启动时通过SessionStart钩子读取这些笔记，解决了这个问题。

Configuration

配置说明

Read the user's CLAUDE.md for a

Session Handoff

config section. If found, use those values. If not found, use defaults.

Example config in CLAUDE.md:

markdown

undefined

读取用户CLAUDE.md中的

Session Handoff

配置部分。如果存在则使用对应配置值，不存在则使用默认值。

CLAUDE.md中的配置示例：

markdown

undefined

Session Handoff Config

Agent ID: Pro CC
Notes folder: Claude Workspace
Other Agents: Mini CC
Private budget: 1500 chars
Shared budget: 1000 chars


**Defaults (when no config section exists):**

| Setting | Default | How it's determined |
|---------|---------|---------------------|
| Agent ID | Machine hostname | `hostname -s` |
| Notes folder | `Claude Workspace` | Fixed |
| Other Agents | _(none — single-agent mode)_ | |
| Private budget | 1500 chars | |
| Shared budget | 1000 chars | |

When Other Agents is empty, automatically use Single-Agent Mode (skip Shared note, no AgentID suffix on note title).

Agent ID: Pro CC
Notes folder: Claude Workspace
Other Agents: Mini CC
Private budget: 1500 chars
Shared budget: 1000 chars


**默认值（无配置段时生效）：**

| 设置项 | 默认值 | 确定方式 |
|---------|---------|---------------------|
| Agent ID | 设备主机名 | `hostname -s` |
| 笔记文件夹 | `Claude Workspace` | 固定值 |
| 其他Agent | _(无 — 单Agent模式)_ | |
| 私有笔记配额 | 1500字符 | |
| 共享笔记配额 | 1000字符 | |

当其他Agent列表为空时，自动使用单Agent模式（跳过共享笔记，笔记标题不添加AgentID后缀）。

Architecture

架构设计

Session ends
    ↓
[Private] Session Handoff — {AgentID}   ← read by this agent's hook
[Shared]  Session Handoff — Shared      ← read by all agents' hooks
    ↓ old content prepended to
[Mid-term] Session Handoff — Archive    ← merged history, tagged by agent
    ↓ periodic consolidation
[Long-term] Memory files (MEMORY.md)    ← distilled universal knowledge

会话结束
    ↓
[私有] 会话交接 — {AgentID}   ← 由当前Agent的钩子读取
[共享]  会话交接 — 共享      ← 由所有Agent的钩子读取
    ↓ 旧内容追加到
[中期] 会话交接 — 归档    ← 合并后的历史记录，按Agent标记
    ↓ 定期整合
[长期] 记忆文件 (MEMORY.md)    ← 提炼出的通用知识

Agent Identification

Agent标识

Define your agents in CLAUDE.md (see Configuration above). Example:

AgentID	Machine	Role
`Pro CC`	MacBook Pro	Interactive development
`Mini CC`	Mac mini server	Unattended tasks, cron jobs

To add a new agent, just add it to the "Other Agents" list in your config. Note naming extends automatically.

在CLAUDE.md中定义你的Agent（见上方配置部分）。示例：

AgentID	设备	角色
`Pro CC`	MacBook Pro	交互式开发
`Mini CC`	Mac mini服务器	无人值守任务、定时任务

要添加新Agent，只需将其添加到配置中的「其他Agent」列表即可，笔记命名规则会自动适配。

Note Naming

笔记命名规则

Note	Title	Written by	Read by
Private	`Session Handoff — {AgentID}`	Self	Self
Shared	`Session Handoff — Shared`	Any agent	All agents
Archive	`Session Handoff — Archive`	Any agent	On demand

笔记类型	标题	写入方	读取方
私有	`Session Handoff — {AgentID}`	当前Agent	当前Agent
共享	`Session Handoff — Shared`	任意Agent	所有Agent
归档	`Session Handoff — Archive`	任意Agent	按需读取

Content Routing (Key to Deduplication)

内容路由（去重核心逻辑）

This session's output
    ↓
Does another agent need to know?
    ├── Yes → Write to Shared
    └── No  → Write to Private

Where	Content type	Example
Private	Work only this agent is doing	A feature branch in progress
Private	Environment-specific issues	PATH problems on this machine
Shared	Cross-agent project state	App developed on Main, deploying to Server
Shared	User decisions/preference changes	User decided to deprecate a tool
Shared	One side done, other needs to know	Main installed a new MCP, Server needs it too

Dedup rule: Content written to Shared is NOT repeated in Private.

本次会话的输出
    ↓
其他Agent需要知晓吗？
    ├── 是 → 写入共享笔记
    └── 否  → 写入私有笔记

存储位置	内容类型	示例
私有	仅当前Agent负责的工作	开发中的功能分支
私有	特定环境相关问题	当前设备的PATH配置问题
共享	跨Agent项目状态	在主设备开发的应用，需要部署到服务器
共享	用户决策/偏好变更	用户决定弃用某款工具
共享	单方完成需另一方知晓的内容	主设备安装了新的MCP，服务器也需要安装

去重规则：写入共享笔记的内容不会在私有笔记中重复出现。

Character Budget

字符配额

Note	Budget
Private	Per config (default 1500 chars)
Shared	Per config (default 1000 chars)
Hook-injected context total	~2500 chars

The budget exists because these notes get injected into every session start. Keeping them compact means less token waste and more room for actual work.

笔记类型	配额
私有	按配置（默认1500字符）
共享	按配置（默认1000字符）
钩子注入上下文总配额	约2500字符

设置配额的原因是这些笔记会在每次会话启动时注入到上下文中。保持内容紧凑可以减少token浪费，为实际工作留出更多额度。

Workflow

工作流

Phase 1: Archive (Preserve Old Content)

阶段1：归档（保留旧内容）

Search for own private note
```
Session Handoff — {AgentID}
```
If found, read its content
Search for
```
Session Handoff — Archive
```
- Exists → prepend old private content to Archive top (with date separator, tagged with AgentID)
- Not found → create Archive, move to configured notes folder
Search for
```
Session Handoff — Shared
```
, read existing shared content (Phase 2 determines what to update)

搜索当前Agent的私有笔记
```
Session Handoff — {AgentID}
```
若存在，读取其内容
搜索
```
Session Handoff — Archive
```
- 已存在 → 将旧私有笔记内容追加到归档顶部（附带日期分隔符，标记AgentID）
- 不存在 → 创建归档笔记，移动到配置的笔记文件夹
搜索
```
Session Handoff — Shared
```
，读取现有共享内容（阶段2决定更新内容）

Phase 2: Write (Overwrite Private + Update Shared)

阶段2：写入（覆盖私有笔记 + 更新共享笔记）

Review this session's conversation, route content:
- Only relevant to self → write to Private
- Useful across agents → write to Shared
Overwrite private note
```
Session Handoff — {AgentID}
```
- First time:
```
create-note
```
  +
```
move-note
```
  to configured notes folder
Update Shared note (only update own sections, never delete other agents' content)
- First time:
```
create-note
```
  +
```
move-note
```
  to configured notes folder
Use
```
<h2>
```
to separate multiple projects

回顾本次会话的对话内容，路由内容：
- 仅与当前Agent相关 → 写入私有笔记
- 对所有Agent有用 → 写入共享笔记
覆盖私有笔记
```
Session Handoff — {AgentID}
```
- 首次创建：执行
```
create-note
```
  +
```
move-note
```
  到配置的笔记文件夹
更新共享笔记（仅修改自己负责的部分，绝对不要删除其他Agent的内容）
- 首次创建：执行
```
create-note
```
  +
```
move-note
```
  到配置的笔记文件夹
使用
```
<h2>
```
标签分隔多个项目

Phase 3: Weekly Consolidation (Triggered when Archive >= 5 entries)

阶段3：每周整合（归档条目≥5条时触发）

Generate weekly report → save to memory/episodic directory
Distill patterns → scan Archive for recurring cross-agent issues
Clean Archive → keep only the most recent 5 entries

生成周报 → 保存到memory/episodic目录
提炼模式 → 扫描归档内容，查找反复出现的跨Agent问题
清理归档 → 仅保留最近5条记录

Phase 4: Spot Check (Real-time Detection)

阶段4：抽查（实时检测）

When a clear lesson is learned during the session, suggest writing it to long-term memory.

会话过程中获得明确的经验教训时，建议将其写入长期记忆。

Note Format

笔记格式

Notes use HTML because Apple Notes doesn't render markdown.

笔记使用HTML格式，因为Apple Notes不渲染markdown。

Private Note

私有笔记

html

<h1>Session Handoff — {AgentID}</h1>
<p><i>Updated: YYYY/MM/DD</i></p>

<h2>Project Alpha</h2>
<h3>Continuing work</h3>
<ul><li>NLP pipeline optimization</li></ul>
<h3>Completed this session</h3>
<ul><li>Refactored data fetcher</li></ul>

html

<h1>Session Handoff — {AgentID}</h1>
<p><i>更新时间: YYYY/MM/DD</i></p>

<h2>Alpha项目</h2>
<h3>待继续工作</h3>
<ul><li>NLP pipeline优化</li></ul>
<h3>本次会话完成内容</h3>
<ul><li>重构了数据获取器</li></ul>

Shared Note

共享笔记

html

<h1>Session Handoff — Shared</h1>
<p><i>Last updated: YYYY/MM/DD by {AgentID}</i></p>

<h2>Environment Sync</h2>
<ul>
<li>New MCP server installed — AgentA done, AgentB pending</li>
</ul>

<h2>Cross-Agent Project State</h2>
<ul>
<li>Project Alpha: developed on AgentA, ready to deploy to AgentB</li>
</ul>

<h2>User Decisions</h2>
<ul>
<li>Deprecated tool X, using tool Y going forward</li>
</ul>

html

<h1>Session Handoff — Shared</h1>
<p><i>最近更新: YYYY/MM/DD by {AgentID}</i></p>

<h2>环境同步</h2>
<ul>
<li>已安装新MCP服务器 — AgentA已完成，AgentB待处理</li>
</ul>

<h2>跨Agent项目状态</h2>
<ul>
<li>Alpha项目：已在AgentA上开发完成，可部署到AgentB</li>
</ul>

<h2>用户决策</h2>
<ul>
<li>已弃用工具X，后续使用工具Y</li>
</ul>

Archive Entry

归档条目

Each entry tagged with source agent:

html

<h3>YYYY/MM/DD [{AgentID}] — Project Alpha, Project Beta</h3>
<p>[compressed handoff content]</p>
<hr>

每个条目都会标记来源Agent：

html

<h3>YYYY/MM/DD [{AgentID}] — Alpha项目、Beta项目</h3>
<p>[压缩后的交接内容]</p>
<hr>

Rules

规则

NEVER skip handoff with "nothing was done" — even a briefing session gets a note
Confirm to user after writing handoff, include the note title
Private note title is always
```
Session Handoff — {AgentID}
```
Shared note title is always
```
Session Handoff — Shared
```
When updating Shared, only update own sections — never delete other agents' content
Multiple projects in one note, separated by
```
<h2>
```
Write notes in HTML format (not markdown) — Apple Notes doesn't render markdown

绝对不要以「没有完成任何工作」为由跳过交接 — 哪怕是仅做了需求沟通的会话也需要生成笔记
写入交接笔记后需向用户确认，并告知笔记标题
私有笔记标题固定为
```
Session Handoff — {AgentID}
```
共享笔记标题固定为
```
Session Handoff — Shared
```
更新共享笔记时，仅修改自己负责的部分 — 绝对不要删除其他Agent的内容
单条笔记中可包含多个项目，用
```
<h2>
```
分隔
用HTML格式编写笔记（而非markdown）—— Apple Notes不渲染markdown

Prerequisites

前置要求

macOS — Apple Notes is macOS/iOS only
Apple Notes MCP — for reading/writing notes (e.g., apple-notes-mcp)
SessionStart hook — to inject handoff content at session start (see
```
hooks/session-start.sh
```
for a working example)

macOS — Apple Notes仅支持macOS/iOS系统
Apple Notes MCP — 用于读写笔记（例如：apple-notes-mcp）
SessionStart钩子 — 用于在会话启动时注入交接内容（可参考
```
hooks/session-start.sh
```
获取可用示例）

SessionStart Hook Setup

SessionStart钩子配置

Copy the example hook script:

bash

cp hooks/session-start.sh ~/.claude/hooks/session-start.sh
chmod +x ~/.claude/hooks/session-start.sh

Edit the script — set your
```
AGENT_ID
```
and
```
NOTES_FOLDER
```
at the top.

Add to

.claude/settings.json

json

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "~/.claude/hooks/session-start.sh"
      }
    ]
  }
}

The hook reads your handoff notes via AppleScript and outputs their content to stdout. Claude Code injects this as context at session start.

复制示例钩子脚本：

bash

cp hooks/session-start.sh ~/.claude/hooks/session-start.sh
chmod +x ~/.claude/hooks/session-start.sh

编辑脚本，在顶部设置你的
```
AGENT_ID
```
和
```
NOTES_FOLDER
```
。

添加到

.claude/settings.json

：

json

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "~/.claude/hooks/session-start.sh"
      }
    ]
  }
}

该钩子通过AppleScript读取你的交接笔记，并将内容输出到stdout。Claude Code会在会话启动时将其作为上下文注入。

Single-Agent Mode

单Agent模式

Activated automatically when no "Other Agents" are configured (or for users with only one machine):

Skip the Shared note entirely
Use a single
```
Session Handoff
```
note (no AgentID suffix)
Archive and consolidation work the same way
Character budget: ~2000 chars for the single note

当未配置「其他Agent」时自动激活（或仅拥有单台设备的用户适用）：

完全跳过共享笔记
使用单条
```
Session Handoff
```
笔记（无AgentID后缀）
归档和整合逻辑保持不变
单条笔记的字符配额约为2000字符