Session Memory

English README

这是一个用于跨会话保留高价值项目上下文的 AI agent 记忆工具，让你不必反复翻长聊天记录。

这是什么

session-memory 用来保留真正会影响后续推进的上下文，而不是保存整段聊天历史。

它主要保留这些内容：

• 当前目标
• 当前思路
• 关键决策
• 已确认结论
• 失败路径
• 下一步动作

它解决什么问题

• 会话太长，重要上下文被聊天噪声淹没
• 新会话接手时，需要重新解释目标、约束和结论
• 方案变了，但之后很难回忆“为什么变”
• 分支研究很多，主线和旁路容易混在一起

快速开始

作为本地 agent skill 使用时，可以直接对 agent 说：

session-memory 恢复
session-memory 保存
session-memory 搜索 <关键词>

第一次接触这个仓库的用户，只要先知道这 3 个动作分别是恢复上下文、保存主线和检索旧结论，就可以开始使用。

这些是 agent 口令，不是仓库自带的 shell 命令。直接从命令行使用时，请运行 scripts/ 里的 Python 脚本，例如：

python3 scripts/restore_session_memory.py --workspace "$PWD" --scope auto
python3 scripts/save_session_memory.py --workspace "$PWD" --scope auto --stage prepare
python3 scripts/search_session_memory.py --workspace "$PWD" --scope auto --query "关键词"

session-memory 检查 是 agent 的保存闸门，主要用来判断现在值不值得保存；通常不需要你手动执行。session-memory 研究保存 用于旁路研究，只在结论还没并入主线、但又值得保留时使用。

保存不是把本轮聊天继续堆进 current.md。正确动作是先归层：现在仍影响下一步的内容留在 current.md；已经过去但以后要追溯原因的内容放进 history.md；未并入主线的旁路研究放进 research.md；工具噪音丢弃。

什么时候用

• 当前会话已经变长，准备结束或切到新会话
• 当前主目标、主方案、关键结论或下一步发生了变化
• 你想保留某条分支研究，但不想污染主线
• 你只想快速查一个旧结论，而不是恢复整份上下文

不适合什么

• 完整文档系统
• 长期知识库
• 项目管理工具
• 原始聊天记录备份

设计取向

这个工具来自一种偏轻量化的工作方式：少记录无效过程，少引入复杂机制，只保留真正影响项目推进的上下文。

最核心的取舍是：current.md 只做当前最小恢复快照，history.md 承接过去但不能丢的关键变化。这样保存间隔变长时，也不需要把所有中间过程塞回当前层。

隐性维护层

这个工具还带有轻量的 sleep/dream 机制和 archive 冷层。它们属于隐性维护层：在合适的时机按需触发提炼和瘦身，不是用户主入口，也不是后台常驻进程。

dream-notes.md 是覆盖式提炼稿，不会因为 sleep 次数持续在项目里无限追加；真正会逐步增加的是全局 dreams/ 快照目录，以及项目里的追加式 history.md。

默认热路径只看 current.md、history.md、dream-notes.md。archive 是 dream 之后瘦身出来的冷层，除非主动要求查看归档，否则不应默认读取。

对于同项目下的分叉研究，最小版研究层使用 research.md 作为研究流水账。研究保存 只往这里追加，不直接覆盖主线 current.md。research.md 会参与 dream 提炼和 dream 后归档，但默认不进入恢复/检索热路径，除非你明确要求查看研究层。

现在 current.md 会维护一个 Last Updated 字段；dream-notes.md 也会写入 Last Updated。如果时间已经过久，它们只能视为弱参考，继续前应优先核对当前代码和真实状态。

记忆空间路由

默认 --scope auto 会优先把当前目录解析到“共享项目记忆”：

• Git 项目：默认落到 <git-root>/.session-memory/
• 非 Git 项目：如果某个祖先目录已经存在 .session-memory/，默认继续复用那一层
• 只有上述共享根都不存在时，才退回当前目录自己的 .session-memory/

如果同一项目里需要两套或多套互不覆盖的研究记忆，在项目根创建 .session-memory/config.toml：

[spaces]
"当前路线" = "current-research"
"旧路线" = "legacy-research"

如果你更喜欢最简写法，也兼容直接写 "记忆1" = "current-research"。

规则很简单：

• key 是记忆空间名，value 是相对项目根的子目录
• 当当前工作目录落在某个子目录内时，读写目标会切到 <子目录>/.session-memory/
• 多条路径重叠时，按最长匹配优先
• 不会自动混读项目共享层和其他记忆空间
• 研究保存 仍然只是追加当前命中的 research.md

旧路径兼容

现在正常读写只使用 agent-neutral（智能体中立）的新路径：

• 项目级：<project>/.session-memory/
• 全局级：${SESSION_MEMORY_HOME:-$HOME/.session-memory}/

如果发现旧路径里已有记忆，会自动迁移到新路径后继续运行：

• 项目级旧路径：<project>/.codex/session-memory/、<project>/.claude/session-memory/
• 全局级旧路径：${CODEX_HOME:-$HOME/.codex}/session-memory/、${CLAUDE_HOME:-$HOME/.claude}/session-memory/

迁移会把旧目录内容搬进新目录，然后删除旧的 session-memory 目录。项目内 .codex/ 或 .claude/ 如果因此变空，也会一并清理；如果还有其他内容则保留。重名冲突不会覆盖新文件，旧文件会放到 .session-memory/archive/legacy-imports/。

常用口令

本节描述的是 agent 口令。用户主入口只有三个：

• session-memory 保存 / session-memory save
• session-memory 恢复 / session-memory restore
• session-memory 搜索 <关键词> / session-memory search <keyword>

辅助入口不占主心智：

• session-memory 研究保存 / session-memory research-save：记录尚未并入主线的旁路研究，不覆盖 current.md
• session-memory 检查 / session-memory check：agent 用来判断是否值得保存，默认只给保存建议

使用案例

• 当一个会话已经积累了较多研究和决策时，可以用 session-memory 保存 / session-memory save 留下当前上下文，而不是下次重新解释。
• 当你在新会话中继续同一项目时，可以用 session-memory 恢复 / session-memory restore 快速接上当前目标、思路和下一步。
• 当你只想确认某个方案为什么被放弃，或某个结论是否已经验证过时，可以用 session-memory 搜索 <关键词> / session-memory search <keyword> 做轻量检索。
• 当你只是在同一个记忆空间里分阶段记录研究时，用 session-memory 研究保存 / session-memory research-save 把阶段性结论追加到当前空间的 research.md。
• 当你在同一项目里同时推进两条不同研究路线时，先在项目根配置 config.toml 划分独立记忆空间，再分别运行 保存 / 研究保存 / 恢复 / 搜索。这样不同本地 fork 或不同研究目录就不会互相覆盖。

核心文件

• current.md：当前最小恢复快照，只保留现在从哪里继续
• current.md 头部会记录 Last Updated
• history.md：关键变化、决策，以及已经过去但不能丢的旧当前层内容
• research.md：同项目多工作上下文的研究流水账
• dream-notes.md：提炼后的经验、错因与预警信号，头部会记录 Last Updated
• config.toml：可选的项目级路由配置，用来把不同子目录映射到独立记忆空间

归档

归档不是主读取层，也不是日常用户入口，而是 dream 成功后触发的冷层瘦身。它会存放已被新主线覆盖、但暂时不想直接删除的旧历史、旧 dream 快照，以及 research.md 里那些“已经并入主线”或“已经判定无效”的旧研究条目。

python3 "<skill-root>/scripts/archive_session_memory.py" --workspace "$PWD" --scope auto --dry-run

默认情况下不应读取 archive；只有当你明确要“查归档”“看旧分支为什么被放弃”时，才应显式带上归档开关。当前搜索脚本的 --include-archive 会检索当前记忆空间里的 archive/history-archive.md 和 archive/research-archive.md。

限制

• 这个工具依赖是否持续记录高价值信息；如果 current.md 和 history.md 长期不更新，恢复质量会下降。
• 它适合提炼和延续项目上下文，不适合替代完整文档、知识库或正式项目管理工具。
• sleep/dream 只做轻量提炼，不保证自动生成的内容总是完美，重要结论仍然需要人工判断。

说明

这个项目主要面向本地 AI agent 工作流。

License

MIT