session-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Session Memory

会话内存

Keep a durable, human-readable record of the current working session so another agent can resume after a disconnect with minimal context loss.

为当前工作会话保留一份持久化、人类可读的记录，以便其他Agent在断开连接后能够以最小的上下文损失恢复工作。

When To Use

使用场景

Use this skill when:

The user asks to preserve, recover, checkpoint, or manage agent memory.
Work is long-running, experimental, or likely to span disconnects.
You are about to make nontrivial edits, run long jobs, switch branches, or pause for user input.
You resume in a repo that already has
```
./session/
```
directories.

在以下场景使用此技能：

用户要求保存、恢复、检查点记录或管理Agent内存时。
工作是长时间运行、实验性的，或可能跨断开连接场景时。
即将进行非 trivial 代码编辑、运行长时间任务、切换分支或暂停等待用户输入时。
在已有
```
./session/
```
目录的仓库中恢复工作时。

Session Directory

会话目录

Create one directory per working session:

bash

mkdir -p session
date +%Y%m%d_%H%M%S
mkdir -p session/<session_date_time>

Use local time from the machine. Reuse the same session directory for all checkpoints in the same conversation unless the user explicitly starts a new session.

Expected files:

```
session_state.md
```
- overall goal, current subtask, loaded skills, status, plan, assumptions, blockers, and next actions.
```
timeline.md
```
- append-only log of major actions, commands, results, and decisions.
```
files.md
```
- files inspected, files changed, and why they matter.
```
handoff.md
```
- concise resume instructions for the next agent.

Add other files only when useful, such as

experiments.tsv

review_notes.md

, or copied command logs.

为每个工作会话创建一个目录：

bash

mkdir -p session
date +%Y%m%d_%H%M%S
mkdir -p session/<session_date_time>

使用机器的本地时间。除非用户明确启动新会话，否则同一对话中的所有检查点都复用同一个会话目录。

预期文件：

```
session_state.md
```
- 整体目标、当前子任务、已加载技能、状态、计划、假设、阻塞点和下一步操作。
```
timeline.md
```
- 追加式记录主要操作、命令、结果和决策的日志。
```
files.md
```
- 已检查的文件、已修改的文件及其重要性说明。
```
handoff.md
```
- 供下一个Agent使用的简洁恢复说明。

仅在有用时添加其他文件，例如

experiments.tsv

、

review_notes.md

或复制的命令日志。

Start Or Resume

启动或恢复会话

At the start of a session:

Check for existing session directories:

bash

ls -dt session/* 2>/dev/null | head

If the user is resuming work, read the latest relevant
```
session_state.md
```
,
```
timeline.md
```
, and
```
handoff.md
```
.
If no relevant session exists, create a new timestamped directory.
Write an initial
```
session_state.md
```
with the user's overall goal, current subtask, loaded skills, repo path, branch, and known constraints.

Do not treat session notes as the only source of truth. Verify important claims against git state, files, and command output before acting.

会话开始时：

bash

ls -dt session/* 2>/dev/null | head

如果用户正在恢复工作，读取最新相关的
```
session_state.md
```
、
```
timeline.md
```
和
```
handoff.md
```
。
如果没有相关会话，创建一个带时间戳的新目录。
编写初始的
```
session_state.md
```
，包含用户的整体目标、当前子任务、已加载技能、仓库路径、分支和已知约束。

不要将会话笔记视为唯一的真相来源。在执行操作前，务必根据git状态、文件和命令输出验证重要信息。

Checkpoint Rhythm

检查点节奏

Write a checkpoint:

After gathering enough context to form a plan.
Before and after meaningful code edits.
Before long-running commands, experiments, branch switches, or anything hard to reconstruct from chat.
When the user changes direction.
Before final response if the session has meaningful state worth resuming.
At least every 30 minutes during active long-running work.

Prefer updating the same files rather than creating many small checkpoint files. Keep the record compact and scannable.

在以下时机写入检查点：

收集到足够上下文以制定计划后。
有意义的代码编辑前后。
运行长时间命令、实验、切换分支或任何难以从聊天记录重构的操作之前。
用户改变工作方向时。
如果会话有值得恢复的有意义状态，在最终响应之前。
在活跃的长时间工作中，至少每30分钟一次。

优先更新同一文件，而非创建多个小检查点文件。保持记录简洁且易于浏览。

File Templates

文件模板

session_state.md

session_state.md

markdown

undefined

markdown

undefined

Session State

Session: <session_date_time>
Repo: <absolute repo path>
Branch: <branch name>
Started: <local timestamp>
Updated: <local timestamp>

Session: <session_date_time>
Repo: <absolute repo path>
Branch: <branch name>
Started: <local timestamp>
Updated: <local timestamp>

Goal

Current Subtask

Loaded Skills

```
<skill-name>
```
- <why it was loaded and any important instructions to preserve.>

```
<skill-name>
```
- <why it was loaded and any important instructions to preserve.>

Current Status

Plan

<Next concrete step>
<Next concrete step>

<Next concrete step>
<Next concrete step>

Assumptions

<Assumption and how to verify it if needed.>

<Assumption and how to verify it if needed.>

Blockers

<Blocker or "None known".>

undefined

<Blocker or "None known".>

undefined

timeline.md

timeline.md

markdown

undefined

markdown

undefined

Timeline

<local timestamp>

User asked: <brief request>
Context gathered: <files/commands and key result>
Decision: <important choice and rationale>
Result: <edits/tests/outcome>

undefined

User asked: <brief request>
Context gathered: <files/commands and key result>
Decision: <important choice and rationale>
Result: <edits/tests/outcome>

undefined

files.md

files.md

markdown

undefined

markdown

undefined

Files

Inspected

```
<path>
```
- <why it mattered>

```
<path>
```
- <why it mattered>

Changed

```
<path>
```
- <what changed and why>

```
<path>
```
- <what changed and why>

Generated

```
<path>
```
- <purpose>

undefined

```
<path>
```
- <purpose>

undefined

handoff.md

handoff.md

markdown

undefined

markdown

undefined

Handoff

Resume From Here

Next Actions

<Most important next action>
<Verification or cleanup still needed>

<Most important next action>
<Verification or cleanup still needed>

Watch Outs

<Risks, user preferences, or repo constraints the next agent must preserve.>

undefined

<Risks, user preferences, or repo constraints the next agent must preserve.>

undefined

Recovery Workflow

恢复流程

When resuming after a disconnect:

Find the likely latest session directory.
Read
```
handoff.md
```
first, then
```
session_state.md
```
, then recent
```
timeline.md
```
.
Run lightweight verification such as
```
git status --short
```
,
```
git branch --show-current
```
, and targeted file reads.
Continue from the latest verified next action.
Append a timeline entry noting the recovery and any mismatches found.

断开连接后恢复工作时：

找到可能的最新会话目录。
先读取
```
handoff.md
```
，再读取
```
session_state.md
```
，最后读取最新的
```
timeline.md
```
。
执行轻量级验证，例如
```
git status --short
```
、
```
git branch --show-current
```
和针对性的文件读取。
从最新已验证的下一步操作继续。
在时间线中追加一条记录，说明恢复操作及发现的任何不匹配情况。

Quality Rules

质量规则

Keep notes factual and terse. Future agents need state, not a transcript.
Record command outcomes that matter, especially failed tests or skipped verification.
Mention uncommitted changes and whether they were made by the current agent or pre-existing.
Do not store secrets, tokens, private credentials, or large logs in session files.
If a session file becomes large, summarize old details and keep the latest next actions near the top of
```
handoff.md
```
.

保持笔记真实简洁。未来的Agent需要的是状态，而非对话记录。
记录重要的命令结果，尤其是失败的测试或跳过的验证步骤。
提及未提交的更改，以及这些更改是当前Agent做出的还是预先存在的。
不要将会话文件用于存储密钥、令牌、私人凭据或大型日志。
如果会话文件变大，总结旧细节并将最新的下一步操作放在
```
handoff.md
```
的顶部附近。