stash

stash：项目记忆持久化

把当前对话中跨会话仍有价值的信息落到项目级、可检查的 memory。Codex 原生 Memories 是运行时辅助层，不是本 Skill 的真相源；本 Skill 的记忆必须显式读写文件。

写法规范以 references/MEMORY_SPEC.md 为唯一真相源。本文件只定义流程。执行前必须完整读取该规范。

触发与优先级

• 只在用户明确要求持久化时运行，不做“会话结束自动 stash”。
• 先检查当前 repo 的 AGENTS.md 和 .agents/skills/。如果存在更具体的记忆 Skill 或明确的记忆真相源，例如 worklog 的 $worklog-memory，立即改用它，不要再创建一套通用 stash memory。
• 没有 repo 专用方案时，才继续本流程。

显式调用写作 $stash。Claude Code 也可通过其 Skills 列表、自然语言或 /stash 触发。

主流程

1. 定位并初始化 stash memory

项目根以 git rev-parse --show-toplevel 为准，非 Git 目录回退当前目录。路径不硬编码：

• 精确覆盖：PROJECT_MEMORY_DIR
• 根目录覆盖：PROJECT_MEMORY_ROOT
• 项目标识覆盖：PROJECT_MEMORY_ID
• 默认 stash 目录：~/.local/share/project-memory/<project-id>/memory
• 只读历史 Codex 候选：~/.local/share/codex-project-memory/-<legacy-key>/memory
• 只读历史 Claude 候选：~/.claude/projects/-<legacy-key>/memory

<project-id> 默认使用项目根目录名并做安全规范化，保持可读。相邻的 project.json 记录项目根与 origin；同名目录已属于另一项目时 resolver 必须拒绝复用，要求显式设置唯一的 PROJECT_MEMORY_ID。同一 origin 的检出路径移动可继续使用原记忆。status: deleted 或 status: archived 都是运行时硬门，resolver 与自动 Hook 默认拒绝加载，历史文件继续保留供显式考古。

PROJECT_MEMORY_DIR 与 PROJECT_MEMORY_ROOT 必须给绝对路径。旧 CODEX_PROJECT_MEMORY_DIR / CODEX_PROJECT_MEMORY_ROOT 不再参与 stash 路径解析。若 repo 存在 .agents/skills/*memory*/SKILL.md，resolver 直接拒绝通用路径，形成第二道防误写门。

第一次处理某项目时：

bash ~/.agents/skills/stash/scripts/init-memory.sh
MEM=$(bash ~/.agents/skills/stash/scripts/resolve-memory-dir.sh --canonical)

初始化脚本的行为：

1. 只创建或校验 canonical stash 目录、project.json 与空白 MEMORY.md 骨架。
2. canonical 路径若是软连接、身份冲突或已有条目却缺索引，立即拒绝。
3. 发现历史 Codex 或 Claude memory 时只报告路径，不复制、不合并、不回退读取，也不创建软连接。
4. migrate-legacy-memory.sh 仅保留为停用提示与初始化兼容入口，不再执行迁移。

~/.local/share/project-memory/ 只保存用户显式调用 $stash 后形成的人工项目记忆。Claude 历史 memory、Codex 自动 memory 与 stash memory 是三个独立来源。需要迁移历史信息时，必须由用户明确要求，逐条阅读、判断并提炼到当前项目的写入目标，不得复制整个目录或用软连接共写。

确认 MEMORY.md 存在；新项目创建以下骨架：

# Memory

## User

## Feedback

## Project

## Reference

Shell 变量不会跨工具调用持久；每个需要路径的调用都重新运行 resolver。