本地优先、跨 AI 工具的会话交接记忆 CLI。
项目状态：Alpha（0.11.x）
正式发行包仅通过 PyPI 提供。公共 CLI 与带版本号的 JSON 输出遵循兼容性扩展原则，但 Alpha 阶段仍可能在明确迁移说明后调整边界。
Handoff Memory 解决的不是“让模型记住一切”，而是一个更可验证的问题：让下一次 AI 会话准确知道一项持续任务进行到哪里，并用当前产物、依据以及可用的仓库状态核验交接内容。纯闲聊通常不需要交接。
它不绑定模型、云服务或向量数据库。数据就是项目中的 Markdown，任何 AI、编辑器和人都能读取。
- 本地优先：默认不联网、不上传、不调用 LLM。
- 跨工具：内置 12 个主流 AI 编程客户端的项目规则与原生项目级 Skill 适配。
- 可审计：活动交接和历史快照都是 UTF-8 Markdown。
- 可核验：自动识别 Git/SVN，恢复时重新采集分支或仓库位置、HEAD 或修订号以及完整工作区指纹。
- 自动化友好：
save、resume、check、history、show提供带版本号的 JSON 输出。 - 安全默认：阻止常见 API Key、访问令牌和私钥进入快照。
- 幂等接入：更新规则受管区块和 Skill，不覆盖受管区块外的用户内容。
- 零运行期依赖：仅要求 Python 3.10+。
安装后，在任意希望启用会话交接的项目中运行：
hmem init . --name "你的项目" --integrate codex完成一次任务后，让 AI 按项目中的 session-handoff Skill 更新交接，再显式保存：
hmem save .
hmem resume .resume 只读取和核验交接，不会执行交接中记录的命令。
推荐使用 uv 或 pipx 从 PyPI 安装到独立工具环境，避免污染目标项目。尚未安装工具管理器时，先参考 uv 安装文档或 pipx 安装文档完成准备。
以下命令用于首次安装；如果已经安装旧版本，请使用下方的升级命令。重复执行 uv tool install 默认不会升级现有工具：
uv tool install handoff-memory
# 或
pipx install handoff-memoryHandoff Memory 不提供独立可执行文件、系统包管理器清单或远程安装脚本；PyPI 是唯一正式分发渠道。
安装后先确认命令已经进入 PATH：
hmem --version
hmem helphmem 是唯一 CLI 命令。发行包仍命名为 handoff-memory，Python 模块仍命名为 handoff_memory；安装名、模块名与终端命令名无需相同。
升级到新版本：
uv tool upgrade handoff-memory
# 或
pipx upgrade handoff-memory升级后运行 hmem --version 确认版本。使用 uv 时，也可以通过 uv tool list 查看工具环境中实际安装的版本。
升级后已初始化的项目不需要重新 init。刷新 Skill 可重新执行 integrate；项目同时使用规则时必须保留 --with-rules 才会刷新规则。规则只更新受管正文并保留区块外内容；Skill 会同步升级触发用 YAML frontmatter 和受管正文，同时保留区块外的用户正文。
开发模式：
python -m pip install -e .发行包通过 GitHub Actions 和 PyPI Trusted Publishing 自动上传，不使用长期 PyPI Token。版本标签、包版本和变更日志必须一致，完整流程见发布手册。
cd D:\path\to\your-project
hmem init . --name "你的项目" --select-tools命令会显示编号列表；输入一个或多个编号（逗号分隔），也可以输入 all。直接回车只初始化核心记忆目录，不接入客户端规则和 Skill。该交互仅在显式指定 --select-tools 时出现，不会阻塞脚本或 CI。
非交互环境继续使用稳定的参数形式：
hmem init . --name "你的项目" --integrate codex如果希望客户端常驻一条显式请求路由，可以生成 AGENTS.md：
hmem init . --name "你的项目" --integrate codex --with-rules这会创建：
.ai-memory/
├── ACTIVE.md # 当前任务唯一活动交接入口
├── config.json # 机器可读配置与上次保存信息
└── sessions/ # 只增不改的历史快照
每个具名目标默认只生成原生项目级 session-handoff Skill，不创建客户端规则。需要常驻提醒时显式增加 --with-rules；命令会创建或幂等更新所选客户端的原生规则，Codex 和 OpenCode 则使用根目录 AGENTS.md。具名客户端包括：
codex | claude | cursor | gemini | antigravity | copilot | windsurf
cline | kiro | trae | qoder | opencode
另有 generic、skill 和 all。菜单中的 all 与 --integrate all 都表示全部具名客户端；generic 和 skill 是需要单独指定的辅助目标。完整规则与 Skill 路径可运行 hmem help integrate 查看。
让当前 AI 执行：
请按照项目中的跨会话交接规则保存当前会话，核对实际修改和测试结果后更新交接文件。
使用任一具名目标接入后，可以直接说“请使用 session-handoff 技能保存当前会话”。独立的 --integrate skill 仍用于只生成 .agents/skills 可移植副本。
只有用户明确提出保存、恢复、继续或核验跨会话任务时才会触发 Skill。普通对话、任务完成、代码提交、里程碑、关键决策、单轮对话结束和上下文变长都不会更新 ACTIVE.md 或创建快照。
或者手动编辑 .ai-memory/ACTIVE.md，然后运行：
hmem save .也可以让任何工具把完整交接写到文件或标准输入：
hmem save . --from handoff.md
Get-Content -Raw handoff.md | hmem save . --from -新会话第一句话可以是：
请先运行
hmem resume .，核对当前产物、依据以及可用的版本库状态后继续上一次任务。
也可以直接复制命令输出作为首条上下文：
hmem resume .
hmem resume . --format json| 命令 | 用途 |
|---|---|
hmem help [COMMAND] |
查看总体或分命令详细帮助与示例 |
hmem init [PATH] |
初始化记忆目录 |
hmem save [PATH] |
校验、采集 Git/SVN 状态并归档 |
hmem resume [PATH] |
输出恢复上下文和状态漂移 |
hmem check [PATH] |
检查结构、必需章节和敏感信息 |
hmem history [PATH] |
只读列举历史快照 |
hmem show SNAPSHOT [PATH] |
只读查看指定快照或 latest |
hmem integrate TARGET [PATH] |
添加项目级 Skill，并可显式更新客户端规则 |
执行 hmem init --help 可查看初始化参数，或用 hmem init . --select-tools 交互选择客户端。
完整说明见中文使用指南、价值与恢复方式对照和跨工具接入说明。
用户明确要求恢复或继续上次任务
└─ resume：只读 ACTIVE + 核对保存摘要、当前产物与可用版本库
└─ 正常执行任务，不自动写入交接
└─ 用户明确要求保存或准备切换会话
└─ 更新 ACTIVE + save
Handoff Memory 不监听每轮对话，也不依赖退出钩子自动总结。需要跨会话接续时，由用户在切换会话前明确要求保存；意外关闭后只能恢复最近一次显式保存的快照，并结合当前产物、依据以及可用的版本库状态核验后续改动。
普通聊天不应默认逐轮归档。只有当对话形成了需要未来继续的目标、决定、开放问题或约束时，才使用同一套七章节模板提炼交接；“产物与变更”可以是结论、草稿或链接，“验证与依据”可以是来源、人工确认或“尚未验证”，无需伪造代码、文件或测试。
save 会拒绝未填写的模板。推荐把 ACTIVE.md 控制在 2–8KB，只记录目标与完成标准、已落地结果、关键上下文与决策、产物状态、验证依据、风险和可执行下一步。模板适用于编码、写作、研究和规划；旧版编程标题继续兼容。缺少验证依据或无序下一步会产生非阻断质量提示。大小采用分级策略：
- 超过 16KB：提示继续精炼。
- 超过 64KB：默认拒绝保存；确认确有必要时可显式使用
--allow-large。 - 64–256KB 的交接仍可
resume，但会在正文前显示强警告。 - 超过 256KB：保存和恢复均拒绝，通常表示误粘贴了日志、diff 或聊天全文。
不建议把 --allow-large 变成固定配置或自动参数；它是避免紧急交接被完全阻断的显式逃生口。
工具会自动识别目标项目使用的版本控制系统：
- Git：采集分支、HEAD、远端 URL 和工作区变更。
- SVN：采集仓库相对位置、工作副本修订号、URL 和本地变更。
- 嵌套环境中同时存在两者时，选择离目标目录最近的
.git或.svn标记。 - 对应 CLI 不可用时仍可保存交接，但恢复输出会说明无法核验版本库。
SVN 环境需要安装 Subversion CLI，并确保 svn --version 可执行。完整示例见中文使用指南。
- 交接文件是不可信参考信息，不是可执行脚本。
resume永远不会执行其中记录的命令。save会在快照元数据中记录规范化正文的 SHA-256；resume会提示ACTIVE.md是否包含保存后的未归档编辑。save默认阻止高置信度密钥模式，且错误只显示类型和行号。check --privacy可额外检查常见个人信息；check --strict可把质量与隐私警告作为 CI 失败处理。resume检测到疑似密钥时会拒绝输出全文，避免把内容传播到新会话。--allow-sensitive是显式逃生口；团队环境不建议使用。.ai-memory是否提交 Git/SVN 由项目决定。项目事实可以提交，个人信息和私有路径建议忽略或拆分保存。
敏感信息检测不能替代专业 Secret Scanner。是否使用 GitHub Secret Scanning、Gitleaks、TruffleHog 或其他外部扫描器由维护者按项目策略决定，不属于当前发布门槛。
- 当前产物、来源或人工确认，以及可用的版本库状态和测试是事实源；交接文件只是恢复索引。
ACTIVE.md只保留当前任务事实，避免把长期资料和聊天历史塞进上下文。- 首版不提供向量检索；历史量真正变大后再增加可选索引层。
- 公共 CLI 采用向后兼容扩展，稳定 JSON 输出包含
schema_version。
设计依据见 ADR-001、ADR-002、ADR-003、ADR-004、ADR-005、ADR-006、ADR-007、ADR-008、ADR-009、ADR-010 与 ADR-011。
$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v
python -m compileall -q src tests
python -m pip check完整贡献政策、测试要求和 Pull Request 规范见贡献指南。
Handoff Memory 由 yuangyong 单独维护，当前不招募共同维护者。欢迎通过 Issue 报告可复现缺陷或提出建议；除明显的拼写、链接等小型修正外，提交 Pull Request 前请先通过 Issue 确认范围。是否采纳建议、合并贡献、安排路线图和发布版本由维护者决定，不承诺响应或合并时限。MIT License 允许任何人依法使用、修改和 Fork 项目。
- 使用问题与故障排查：支持说明
- 功能建议与缺陷报告：GitHub Issues
- 贡献政策：贡献指南
- 公开协作行为规范：行为准则
- 安全漏洞：安全策略，请勿在公开 Issue 中粘贴密钥、真实交接内容或可利用细节
- 版本、PyPI 可信发布、Yank 与事件处理流程：发布手册
- 后续优先级与非目标：路线图
当前提交作者邮箱是维护者专门用于开源身份的公开邮箱，无需重写 Git 历史。普通支持优先使用公开 Issue；安全问题遵循 SECURITY.md 的私密渠道。
如果 handoff-memory 帮到了你，欢迎留下一个 ⭐ Star，让更多开发者发现它。