Back to Details

session-close

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/session-close -- Session-to-Memory Reconciliation

/session-close -- 会话到内存的整合

Reconcile durable outcomes from the current session into persistent project memory files. This is state reconciliation, not session logging -- the output should be indistinguishable from a human updating the project memory after a week of work.
将当前会话中的持久化成果整合到项目内存文件中。这是状态整合，而非会话日志记录——最终生成的内容应与人工在一周工作后更新的项目内存毫无差别。

Core Principle

核心原则

Code captures outcomes; memory captures reasoning. Git already records what changed. Project memory files exist to capture why decisions were made, what state the project is in, and what comes next -- things that can't be derived from a diff.
代码记录成果；内存记录推理过程。 Git已经记录了代码的变更内容。项目内存文件用于记录决策背后的原因、项目当前的状态以及下一步计划——这些信息无法从代码差异中推导出来。

The Anti-Pattern This Skill Prevents

本技能避免的反模式

Files like 
project_session_apr8_9.md
-- unstructured dumps of everything done across multiple projects in one session. These fail the "new team member" test: a developer joining tomorrow can't distinguish signal from noise. State reconciliation produces files that answer "what is this project?" not "what happened today?"
类似
project_session_apr8_9.md
这类文件——将多个项目在一次会话中的所有操作进行无结构转储。这类文件无法通过“新成员测试”：第二天加入的开发者无法从噪音中分辨出有效信息。状态整合生成的文件回答的是“这个项目是什么？”，而非“今天发生了什么？”。

Arguments

参数

  • Argument 1 (optional): Project name to update. If omitted, the skill identifies projects from conversation context and working directory.
  • 参数1（可选）： 要更新的项目名称。如果省略，技能会从对话上下文和工作目录中识别项目。

Procedure

流程

Phase 1: IDENTIFY -- What projects were touched?

阶段1：识别——哪些项目被操作过？

Determine which projects received meaningful work in this session using three sources:
  1. Conversation context (primary). Review the current conversation to identify projects discussed. This is the richest source -- it captures intent, decisions, and outcomes that git alone cannot.
  2. Working directory. Check the current working directory:
    • If cwd is a project dir (has 
      .git/
      ), that's the primary project
    • If cwd is a workspace containing multiple project subdirectories, check which ones have recent activity
    • If cwd is home (
      ~/
      ), rely on conversation context entirely
  3. Git state (verification). For each identified project directory:
    bash
    # Cross-platform: works on macOS and Linux
git -C $PROJECT log --oneline --since="12 hours ago" 2>/dev/null
git -C $PROJECT status --porcelain 2>/dev/null  # uncommitted work
    Git confirms what code actually changed. If conversation mentions work but git shows nothing, flag the discrepancy. Also note any uncommitted changes -- these are critical to capture in Status.
Project-to-memory mapping: Resolve the memory directory dynamically:
  • Claude Code stores project memory at 
    ~/.claude/projects/<escaped-project-path>/memory/
  • The escaped path replaces 
    /
    with 
    -
    (e.g., 
    /Users/alice/Projects/myapp
    becomes 
    -Users-alice-Projects-myapp
    )
  • Memory files follow the naming convention 
    project_{name}.md
  • If a memory directory already exists for the project, use it. If not, create it.
Convergence rule: A project must appear in conversation context AND at least one other source (git or cwd) to be included. This prevents updating memory for projects that were merely mentioned.
通过三个来源确定本次会话中哪些项目有实质性的工作：
  1. 对话上下文（主要来源）。回顾当前对话以识别讨论过的项目。这是最丰富的信息来源——它捕获了Git无法记录的意图、决策和成果。
  2. 工作目录。检查当前工作目录：
    • 如果当前目录是项目目录（包含
      .git/
      ），则将其作为主要项目
    • 如果当前目录是包含多个项目子目录的工作区，检查哪些子目录有近期活动
    • 如果当前目录是主目录（
      ~/
      ），则完全依赖对话上下文
  3. Git状态（验证）。对于每个识别出的项目目录：
    bash
    # 跨平台：适用于macOS和Linux
git -C $PROJECT log --oneline --since="12 hours ago" 2>/dev/null
git -C $PROJECT status --porcelain 2>/dev/null  # 未提交的工作
    Git确认实际变更的代码。如果对话中提到了某项工作但Git没有记录，需标记这种差异。同时注意任何未提交的变更——这些内容对于状态记录至关重要。
项目与内存的映射： 动态解析内存目录：
  • Claude Code将项目内存存储在
    ~/.claude/projects/<escaped-project-path>/memory/
  • 转义路径将
    /
    替换为
    -
    （例如，
    /Users/alice/Projects/myapp
    变为
    -Users-alice-Projects-myapp
    ）
  • 内存文件遵循
    project_{name}.md
    的命名规则
  • 如果项目的内存目录已存在，则使用该目录；否则创建新目录。
收敛规则： 项目必须同时出现在对话上下文和至少一个其他来源（Git或工作目录）中才会被纳入。这避免了仅被提及但未实际操作的项目被更新内存。

Phase 2: READ -- Load existing project memory

阶段2：读取——加载现有项目内存

For each identified project:
  1. Read the project's memory file (
    project_{name}.md
    ) from the resolved memory directory
  2. Parse the structure: frontmatter, section headings, content
  3. If no file exists, note it -- a new one will be created following existing templates
  4. Size check: Count lines. If >80 lines, flag for potential pruning during reconciliation. MEMORY.md loads the first 200 lines across all files -- bloated project files crowd out other memories.
Also read:
  • MEMORY.md
    index (to check whether index updates are needed)
  • The project's CLAUDE.md if you need stack/architecture context
对于每个识别出的项目：
  1. 从解析后的内存目录中读取项目的内存文件（
    project_{name}.md
    ）
  2. 解析文件结构：前置元数据、章节标题、内容
  3. 如果文件不存在，记录该情况——将按照现有模板创建新文件
  4. 大小检查： 统计行数。如果超过80行，标记为在整合过程中可能需要精简。MEMORY.md会加载所有文件的前200行——臃肿的项目文件会挤占其他内存文件的空间。
同时读取：
  • MEMORY.md
    索引（检查是否需要更新索引）
  • 项目的CLAUDE.md（如果需要栈/架构上下文）

Phase 3: EXTRACT -- Classify and filter session events

阶段3：提取——分类和过滤会话事件

Review the conversation and git history. For each significant event, classify it:
TypePersist?Example
DECISIONAlways"Switched from session cookies to JWT for auth"
STATUS_CHANGEAlways"Promoted to staging", "deployed to production"
DISCOVERYIf novel"Learned Neon has a 100-connection limit on free tier"
IMPLEMENTATIONOutcome only"Built MCP server" (not "created 12 files in src/mcp/")
TROUBLESHOOTINGPattern only"Vercel Blob needed for files >4.5MB" (not the 5 debugging steps)
EXPLORATIONNeverReading docs, searching code, trying approaches that were abandoned
Then apply the three-gate filter -- every item must pass ALL three:
  1. DURABILITY: Will this still be true/relevant in 30 days?
    • YES: architecture decisions, features shipped, config changes, deployment state
    • NO: debugging steps, error messages, intermediate attempts, commands run
  2. SPECIFICITY: Can I state this as a concrete claim with a subject, verb, and specific value?
    • YES: "Imported 457K swim results from HyTek MDB files"
    • NO: "Worked on the import system"
  3. RETRIEVAL: Is a future session likely to need this?
    • YES: constraints, conventions, decisions with rationale, integration details
    • NO: how we discovered something, which files we read, what order we tried things
For items that pass all three, record:
  • WHAT changed (the concrete fact)
  • WHY it changed (the reasoning -- this is what code alone can't tell you)
  • WHAT it affects downstream (scope of impact)
回顾对话和Git历史。对于每个重要事件，进行分类：
类型是否持久化？示例
DECISION（决策）始终"将身份验证从会话Cookie切换为JWT"
STATUS_CHANGE（状态变更）始终"升级到预发布环境"、"部署到生产环境"
DISCOVERY（发现）仅当具有新颖性时"了解到Neon免费版有100连接限制"
IMPLEMENTATION（实现）仅记录成果"构建了MCP服务器"（而非"在src/mcp/中创建了12个文件"）
TROUBLESHOOTING（故障排查）仅记录模式"Vercel Blob适用于大于4.5MB的文件"（而非5个调试步骤）
EXPLORATION（探索）从不阅读文档、搜索代码、尝试后被放弃的方案
然后应用三重过滤门——每个条目必须通过所有三个条件：
  1. 持久性： 30天后该信息是否仍然真实/相关？
    • 是：架构决策、已交付的功能、配置变更、部署状态
    • 否：调试步骤、错误信息、中间尝试、执行的命令
  2. 具体性： 是否可以将其表述为包含主语、谓语和具体值的明确陈述？
    • 是："从HyTek MDB文件导入了457K条游泳比赛结果"
    • 否："处理了导入系统"
  3. 可检索性： 未来会话是否可能需要该信息？
    • 是：约束条件、约定规则、带有理由的决策、集成细节
    • 否：我们如何发现某件事、阅读了哪些文件、尝试的顺序
对于通过所有三个条件的条目，记录：
  • 变更内容（具体事实）
  • 变更原因（推理过程——这是代码本身无法体现的）
  • 影响范围（下游受影响的内容）

Phase 3.5: ROUTE by layer (V2) -- repo vs local

阶段3.5：按层级路由（V2）——仓库 vs 本地

Local memory is the wrong home for knowledge a clone-only agent or collaborator needs. The 2026 consensus is a three-layer split: conventions → 
CLAUDE.md
/
AGENTS.md
, decisions + rationale → repo 
docs/decisions/
(ADRs), current status/next → 
docs/PROJECT_STATUS.md
 — and local memory keeps only the residue (personal scratch, secret-locations, cross-project notes). Before persisting each durable item, route it:
ItemBelongs inAction
Decision + rationale a teammate/remote agent needsrepo ADR (
docs/decisions/
)		write it to the repo; don't bury rationale in local memory
Convention / architecture rule
CLAUDE.md
/ 
AGENTS.md
suggest the edit there
Current state / next steps
PROJECT_STATUS.md
if the repo uses one, else memory Status		route accordingly
Secret-location, personal/tooling scratch, cross-project notelocal memory onlykeep (never commit)
This isn't extra work — it's putting each fact where the next reader will actually look. If the repo isn't yet set up for this (no ADRs / PROJECT_STATUS), note it and suggest creating those committed docs; until then, memory is the fallback. Memory then holds only what genuinely has no repo home. Phase 7 acts on the 
CLAUDE.md
/
AGENTS.md
items this step identifies — handing them to the 
claude-md
audit for surgical promotion.
仅克隆的Agent或协作者需要的知识不适合存储在本地内存中。2026年的共识是分为三层：约定规则 → 
CLAUDE.md
/
AGENTS.md
，决策+理由 → 仓库
docs/decisions/
（ADRs），当前状态/下一步 → 
docs/PROJECT_STATUS.md
 ——而本地内存仅保留剩余内容（个人草稿、保密位置、跨项目笔记）。在持久化每个条目之前，进行路由：
条目所属位置操作
队友/远程Agent需要的决策+理由仓库ADR（
docs/decisions/
）		写入仓库；不要将理由隐藏在本地内存中
约定规则 / 架构规则
CLAUDE.md
/ 
AGENTS.md
建议在该处进行编辑
当前状态 / 下一步计划如果仓库使用
PROJECT_STATUS.md
则写入该文件，否则写入内存的Status章节		按对应方式路由
保密位置、个人/工具草稿、跨项目笔记仅本地内存保留（绝不提交）
这并非额外工作——而是将每个事实放在下一个读者实际会查看的位置。如果仓库尚未设置相关文件（无ADRs / PROJECT_STATUS），记录该情况并建议创建这些提交的文档；在此之前，内存作为备选方案。内存仅保留确实没有仓库存储位置的内容。阶段7会处理本步骤识别出的
CLAUDE.md
/
AGENTS.md
条目 ——将它们交给
claude-md
审核以进行精准升级。

Phase 4: RECONCILE -- Section-aware merging

阶段4：整合——按章节合并

For each project memory file, classify each section by its merge type, then apply the appropriate strategy:
对于每个项目内存文件，将每个章节按合并类型分类，然后应用相应的策略：

REPLACE sections (overwrite entirely)

替换章节（完全覆盖）

Status section (identified by heading starting with 
## Status
):
  • Delete the existing Status block entirely
  • Write a new one: 
    ## Status (Mon DD, YYYY)
    with 3-5 bullets
  • Cover: current branch, deployment state, key metrics, immediate next steps
  • Include uncommitted work: If 
    git status --porcelain
    shows changes, note "N uncommitted files in working tree" to prevent confusion in the next session
  • This section is always fully overwritten -- it represents current state, not history
Status章节（标题以
## Status
开头）：
  • 完全删除现有的Status块
  • 写入新内容：
    ## Status (Mon DD, YYYY)
    ，包含3-5个项目符号
  • 覆盖内容：当前分支、部署状态、关键指标、立即下一步计划
  • 包含未提交工作： 如果
    git status --porcelain
    显示有变更，需注明"工作区中有N个未提交文件"，以避免下一次会话产生混淆
  • 本章节始终完全覆盖——它代表当前状态，而非历史记录

MERGE-LIST sections (deduplicate, update, append)

合并列表章节（去重、更新、追加）

Backlog (or equivalent: TODO, Next Steps, Roadmap):
  • Match existing items by their core description (ignore checkbox state, dates, tags)
  • Mark completed items: 
    - [ ]
    becomes 
    - [x]
    (keep for progress tracking)
  • Add new items identified during the session
  • Reorder by priority if the session revealed new priorities
Capability sections (What It Does, Features, Capabilities, etc.):
  • Match by entity name (e.g., "MCP server", "SSE streaming")
  • If the entity exists: update the bullet in place with new state
  • If new: append to the section
  • Never duplicate information already present
Backlog（或等效名称：TODO、Next Steps、Roadmap）：
  • 根据核心描述匹配现有条目（忽略复选框状态、日期、标签）
  • 标记已完成条目：
    - [ ]
    变为
    - [x]
    （保留用于进度跟踪）
  • 添加本次会话中识别出的新条目
  • 如果会话揭示了新的优先级，重新排序
Capability章节（What It Does、Features、Capabilities等）：
  • 根据实体名称匹配（例如，"MCP服务器"、"SSE流"）
  • 如果实体已存在：在原位置更新项目符号的新状态
  • 如果是新实体：追加到章节末尾
  • 绝不重复已存在的信息

PRESERVE sections (touch only if explicitly changed)

保留章节（仅在明确变更时修改）

Stack, Safety, Parameters, DB, Architecture, Config (or equivalent):
  • Only modify if the session explicitly changed something in this category
  • If untouched, leave the section byte-for-byte identical
  • Never regenerate these sections -- LLM rewrites subtly lose nuance and change voice
Stack、Safety、Parameters、DB、Architecture、Config（或等效名称）：
  • 仅当会话明确变更了该类别中的内容时才修改
  • 如果未被修改，保持章节内容完全不变
  • 绝不重新生成这些章节——LLM重写会微妙地丢失细节并改变语气

Frontmatter

前置元数据

  • Update 
    description
    only if the project's one-liner scope changed (rare)
  • Do not add or change 
    originSessionId
  • 仅当项目的单行范围描述发生变化时才更新
    description
    （这种情况很少见）
  • 不要添加或修改
    originSessionId

Reconciliation rules

整合规则

  1. Never duplicate information already present
  2. When updating a fact, find the existing statement and edit it in place
  3. Preserve the existing file's voice and structure -- do not rewrite prose you aren't changing
  4. If unsure whether something changed, leave existing text unchanged
  5. New sections should follow the established pattern in that file
  1. 绝不重复已存在的信息
  2. 更新事实时，找到现有陈述并在原位置编辑
  3. 保留现有文件的语气和结构——不要重写未变更的文本
  4. 如果不确定是否有变更，保持现有文本不变
  5. 新章节应遵循该文件中的既定模式

Phase 5: PRESENT -- Show changes for approval

阶段5：呈现——展示变更供批准

Do not write files without showing the user what will change.
For each project, present a clear summary of proposed changes:
undefined
在未向用户展示变更内容之前，不要写入文件。
对于每个项目，清晰呈现拟议的变更摘要：
undefined

project_{name}.md -- Proposed Changes

project_{name}.md -- 拟议变更

Status (full replace):

Status（完全替换）：

  • [new status bullets]
  • [新状态项目符号]

Backlog (N completed, M added):

Backlog（完成N项，新增M项）：

  • Completed item (done Mon DD)
  • NEW: New item description
  • 已完成条目（完成于Mon DD）
  • NEW: 新条目描述

[Section Name] (N updates):

[章节名称]（更新N项）：

  • Added: [item]
  • Changed: [old] -> [new]
  • 新增：[条目]
  • 修改：[旧内容] -> [新内容]

Size: current NN lines -> proposed NN lines

大小：当前NN行 -> 拟议NN行


Then ask: **"Apply these changes?"**
- **Yes** -- apply all
- **Edit** -- let the user modify before applying
- **Skip [project]** -- skip a specific project

On approval, use the Edit tool for surgical section updates. For the Status section, replace the entire block. **Never rewrite sections that didn't change.**

然后询问：**"应用这些变更？"**
- **是** ——应用所有变更
- **编辑** ——让用户在应用前修改
- **跳过[项目]** ——跳过特定项目

获得批准后，使用编辑工具进行精准的章节更新。对于Status章节，替换整个块。**绝不重写未变更的章节。**

Phase 6: INDEX -- Update MEMORY.md

阶段6：索引——更新MEMORY.md

If any new memory files were created:
  1. Add an entry to the 
    ## Projects
    section of MEMORY.md
  2. Follow the existing format: 
    - [Project Name](memory/project_name.md) -- one-line description
  3. Keep alphabetical order within the section
  4. Line count check: If MEMORY.md exceeds 180 lines, warn that it's approaching the 200-line context load limit
如果创建了新的内存文件：
  1. 在MEMORY.md的
    ## Projects
    章节中添加条目
  2. 遵循现有格式：
    - [Project Name](memory/project_name.md) -- 单行描述
  3. 在章节内保持字母顺序
  4. 行数检查： 如果MEMORY.md超过180行，警告其接近200行的上下文加载限制

Phase 7: CLAUDE.md AUDIT -- Promote cross-agent lessons (optional; needs the 
claude-md
skill)

阶段7：CLAUDE.md审核——推广跨Agent经验（可选；需要
claude-md
技能）

Memory captured this session's reasoning. But some of what Phase 3.5 routed isn't memory's job -- it's a convention or architecture rule every agent and teammate needs, which belongs in the committed 
CLAUDE.md
/
AGENTS.md
: the cross-agent layer a fresh clone or a different agent reads first. Lessons stranded in local memory are invisible to them, and get silently dropped when someone re-runs 
/init
.
For each touched project that has (or should have) a 
CLAUDE.md
/ 
AGENTS.md
:
  1. Collect the CLAUDE.md-worthy items surfaced in Phase 3.5 -- conventions, architecture rules, "always/never" guidance that emerged this session and a different agent would need. (If Phase 3.5 surfaced none, skip this phase.)
  2. Hand off to 
    claude-md
    if it's installed     (it ships alongside this skill in 
    ngmeyer/skills
    ): run 
    /claude-md audit
    (drift, leaked secrets, bloat across all CLAUDE.md files) or 
    /claude-md improve <path>
    (measure one file against best practices, propose surgical diffs), seeding it with the items from step 1. 
    claude-md
    already gates every diff on your approval.
  3. If 
    claude-md
    is absent, degrade gracefully:     print the items -- "N convention(s) from this session may belong in CLAUDE.md; install 
    claude-md
    or add them by hand"     -- so nothing is lost. Never block on it.
Never run 
/init
to update an existing CLAUDE.md. 
/init
regenerates the file wholesale: it invents architecture sections and discards the curated, hard-won lessons that were never written into it. This phase is surgical promotion (add the few lines that earned their place, leave the rest byte-for-byte), not regeneration. If a project has no 
CLAUDE.md
yet, suggest a minimal one -- don't auto-generate a large one.
This is a soft dependency by design -- it degrades to a printed list when 
claude-md
is absent, so session-close stays self-contained for a cherry-picked install.
内存记录了本次会话的推理过程。但阶段3.5路由的部分内容不属于内存的职责——它们是每个Agent和队友都需要的约定规则或架构规则，应存储在已提交的
CLAUDE.md
/
AGENTS.md
中：这是新克隆的Agent或其他Agent首先读取的跨Agent层级。滞留在本地内存中的经验对他们不可见，并且当有人重新运行
/init
时会被静默丢弃。
对于每个有（或应该有）
CLAUDE.md
/
AGENTS.md
的项目：
  1. 收集阶段3.5中发现的适合CLAUDE.md的条目——本次会话中出现的约定规则、架构规则、"始终/绝不"指南，且其他Agent需要这些内容。（如果阶段3.5未发现任何条目，跳过本阶段。）
  2. 如果已安装
    claude-md
    则移交    （该技能与本技能一同在
    ngmeyer/skills
    中发布）：运行
    /claude-md audit
    （检查所有CLAUDE.md文件的偏差、泄露的机密、臃肿问题）或
    /claude-md improve <path>
    （根据最佳实践评估单个文件，提出精准差异），并注入步骤1中的条目。
    claude-md
    已将每个差异的批准作为前置条件。
  3. 如果
    claude-md
    不存在，优雅降级：     打印条目——"本次会话中有N项约定规则可能适合放入CLAUDE.md；请安装
    claude-md
    或手动添加"    ——避免信息丢失。绝不因此阻塞流程。
绝不要运行
/init
来更新现有的CLAUDE.md。 
init
会完全重新生成文件：它会凭空生成架构章节，并丢弃从未写入其中的精心积累的经验。本阶段是精准推广（添加值得保留的几行内容，其余内容保持完全不变），而非重新生成。如果项目还没有
CLAUDE.md
，建议创建一个极简版本——不要自动生成大文件。
这是一个设计上的软依赖——当
claude-md
不存在时会降级为打印列表，因此session-close在单独安装时仍能保持独立；两个技能都在
ngmeyer/skills
中发布，因此这种关联是安全的。

Phase 8: CLEANUP -- Offer to remove artifacts

阶段8：清理——提供移除工件的选项

Check for and offer to delete:
  1. Session-specific plan files in 
    ~/.claude/plans/
    where all tasks are completed
  2. Session dump memory files (like 
    project_session_*.md
    ) whose content has been reconciled into per-project files
  3. Completed task directories in 
    ~/.claude/tasks/
    where all tasks show status 
    completed
  4. Stale Status sections in other project files: if any project file has a Status section dated >30 days ago, flag it for review
Always ask before deleting. Present the cleanup list and wait for confirmation.
检查并提供删除以下内容的选项：
  1. 会话特定的计划文件：位于
    ~/.claude/plans/
    中且所有任务已完成的文件
  2. 会话转储内存文件（如
    project_session_*.md
    ）：其内容已整合到每个项目的文件中
  3. 已完成的任务目录：位于
    ~/.claude/tasks/
    中且所有任务状态为
    completed
    的目录
  4. 其他项目文件中的过期Status章节：如果任何项目文件的Status章节日期超过30天，标记为需要审核
删除前始终询问用户。 呈现清理列表并等待确认。

Gotchas

注意事项

  • No session dumps. Never create 
    project_session_*.md
    files -- this is the anti-pattern the skill exists to prevent
  • No session framing. Never write "In the April 11 session, we..." -- write state, not history
  • No implementation details. Don't include file paths, line numbers, or function names unless they are architectural landmarks. Code captures outcomes; memory captures reasoning
  • No silent writes. Always show the diff preview and get approval before modifying memory files
  • No forced updates. If the session had zero durable outcomes (pure debugging, research, or exploration that was abandoned), report "No durable state changes detected" and exit
  • No scope creep. Only update 
    project_*.md
    files -- do not touch feedback, user, or reference memory files
  • No remote calls. Don't fetch from git remotes or make network requests. Use local state only
  • No phantom projects. Don't create memory for projects that were mentioned but not worked on
  • No date-stamped items in capability or stack sections. Dates belong only in the Status section
  • No section regeneration. Never rewrite a section you aren't changing. LLM rewrites subtly lose detail, change voice, and introduce drift. Use the Edit tool on specific lines, not Write on the whole file
  • No vague summaries. "Worked on auth improvements" fails the specificity gate. Every persisted fact must have a subject, verb, and concrete value
  • Never 
    /init
    to refresh an existing CLAUDE.md.     It regenerates wholesale and drops the curated lessons that lived only in memory. Promote to CLAUDE.md surgically via the 
    claude-md
    skill (Phase 7), never by regeneration. Memory is for reasoning; CLAUDE.md/AGENTS.md is the cross-agent convention layer -- keep each in its lane
  • 不要会话转储。绝不创建
    project_session_*.md
    文件——这正是本技能要防止的反模式
  • 不要会话框架。绝不要写"在4月11日的会话中，我们..."——记录状态，而非历史
  • 不要实现细节。除非是架构里程碑，否则不要包含文件路径、行号或函数名称。代码记录成果；内存记录推理过程
  • 不要静默写入。在修改内存文件之前，始终显示差异预览并获得批准
  • 不要强制更新。如果会话没有产生任何持久化成果（纯粹的调试、研究或被放弃的探索），报告"未检测到持久化状态变更"并退出
  • 不要范围蔓延。仅更新
    project_*.md
    文件——不要修改反馈、用户或参考内存文件
  • 不要远程调用。不要从Git远程仓库获取内容或发起网络请求。仅使用本地状态
  • 不要虚假项目。不要为仅被提及但未被操作的项目创建内存
  • 不要在能力或栈章节中添加日期戳。日期仅属于Status章节
  • 不要重新生成章节。绝不重写未变更的章节。LLM重写会微妙地丢失细节、改变语气并引入偏差。使用编辑工具修改特定行，而非重写整个文件
  • 不要模糊摘要。"处理了身份验证改进"不符合具体性要求。每个持久化的事实必须包含主语、谓语和具体值
  • 绝不要用
    /init
    刷新现有的CLAUDE.md    。它会完全重新生成文件并丢弃仅存储在内存中的精心积累的经验。通过
    claude-md
    技能（阶段7）精准推广到CLAUDE.md，绝不通过重新生成。内存用于存储推理过程；CLAUDE.md/AGENTS.md是跨Agent约定层级——保持两者各司其职

Section Naming Conventions

章节命名约定

The reconciliation logic matches sections by these patterns. Your memory files should use these headings (or close equivalents):
Merge TypeSection Headings (matched flexibly)
REPLACE
## Status
, 
## Current Status
MERGE-LIST
## Backlog
, 
## TODO
, 
## Next Steps
, 
## Roadmap
, 
## What It Does
, 
## Features
, 
## Capabilities
PRESERVE
## Stack
, 
## Architecture
, 
## Safety
, 
## Config
, 
## Parameters
, 
## Database
Sections not matching any pattern are treated as PRESERVE (safe default).
整合逻辑通过以下模式匹配章节。你的内存文件应使用这些标题（或等效名称）：
合并类型章节标题（灵活匹配）
替换
## Status
, 
## Current Status
合并列表
## Backlog
, 
## TODO
, 
## Next Steps
, 
## Roadmap
, 
## What It Does
, 
## Features
, 
## Capabilities
保留
## Stack
, 
## Architecture
, 
## Safety
, 
## Config
, 
## Parameters
, 
## Database
不匹配任何模式的章节将被视为保留（安全默认）。

Edge Cases

边缘情况

No existing memory file: Create a new one following the template from existing project files (frontmatter + sections for What It Does, Stack, Status, Backlog). Present the full new file for approval.
Zero durable outcomes: Report "No durable state changes detected for any project. Nothing to update." Exit cleanly. This is the correct outcome for debugging sessions, research/reading sessions, or exploration that was abandoned. Do not force an update.
Conflicting information: Flag conflicts between conversation and git to the user. Example: "Conversation mentions deploying to Fly.io, but no deployment commits found. Include in status update?"
Multi-project session from home dir: Process each project independently. This is exactly what prevents the session-dump anti-pattern.
Very large session (4+ hours): Process projects sequentially, not all at once. Present one project's changes at a time.
File exceeds 80 lines after update: Warn the user and suggest pruning completed backlog items or compressing verbose sections. Project files should be lean -- they compete for the 200-line MEMORY.md context budget.
Uncommitted work detected: Always include in Status section. Previous sessions have lost track of uncommitted work, causing confusion in the next session.
无现有内存文件： 按照现有项目文件的模板创建新文件（前置元数据 + What It Does、Stack、Status、Backlog章节）。呈现完整的新文件供批准。
无持久化成果： 报告"未检测到任何项目的持久化状态变更。无需更新。" 干净退出。这是调试会话、研究/阅读会话或被放弃的探索的正确结果。不要强制更新。
信息冲突： 向用户标记对话与Git之间的冲突。示例："对话提到部署到Fly.io，但未找到部署提交。是否包含在状态更新中？"
从主目录进行多项目会话： 独立处理每个项目。这正是防止会话转储反模式的关键。
超长会话（4小时以上）： 按顺序处理项目，而非同时处理。一次呈现一个项目的变更。
更新后文件超过80行： 警告用户并建议精简已完成的待办事项或压缩冗长章节。项目文件应保持精简——它们会占用MEMORY.md的200行上下文预算。
检测到未提交工作： 始终包含在Status章节中。之前的会话曾丢失未提交工作的记录，导致下一次会话产生混淆。

Changelog

更新日志

V2.1 (2026-06-11) -- CLAUDE.md audit handoff (Phase 7)

V2.1（2026-06-11）——CLAUDE.md审核移交（阶段7）

Added Phase 7: CLAUDE.md AUDIT. After reconciling memory, promote the cross-agent conventions Phase 3.5 identified into the committed 
CLAUDE.md
/
AGENTS.md
by handing off to the 
claude-md
 skill's surgical, approval-gated 
audit
/
improve
-- never 
/init
, which regenerates the file and drops curated lessons that lived only in memory. Closes the loop Phase 3.5 opened: it identified CLAUDE.md-worthy items but nothing acted on them. Soft dependency -- degrades to a printed list when 
claude-md
isn't installed, so session-close stays self-contained; both skills ship in 
ngmeyer/skills
, so the sibling reference is safe. CLEANUP renumbered 7 -> 8.
新增阶段7：CLAUDE.md审核。整合内存后，通过将阶段3.5识别的跨Agent约定规则移交到**
claude-md
**技能的精准、需批准的
audit
/
improve
功能，推广到已提交的
CLAUDE.md
/
AGENTS.md
中——绝不要使用
/init
，因为它会重新生成文件并丢弃仅存储在内存中的精心积累的经验。完成了阶段3.5开启的闭环：它识别了适合CLAUDE.md的条目，但没有处理这些条目。软依赖——当
claude-md
未安装时降级为打印列表，因此session-close保持独立；两个技能都在
ngmeyer/skills
中发布，因此这种关联是安全的。清理阶段编号从7改为8。

V2 (2026-05-27)

V2（2026-05-27）

Optimized via 
skillforge optimize
(outcome research: AI agent memory / context engineering 2026).
  • Phase 3.5 ROUTE by layer — route durable items to their right home (conventions→CLAUDE.md/AGENTS.md, decisions→repo ADRs, status→PROJECT_STATUS) instead of defaulting everything into local memory; memory keeps only the residue. The three-layer split is the 2026 engineering consensus.
  • Reinforces the existing "not a dump" / size-check rules with the documented reason: context rot (quality degrades as memory bloats), and selective memory is ~10–20× cheaper than fat context.
  • Outcome target: resume-critical knowledge ends up where any agent or teammate will find it, not siloed in one machine's local memory. Sources: State of AI Agent Memory 2026 (mem0); Agent Memory vs Context Engineering (Augment).
通过
skillforge optimize
优化（成果研究：2026年AI Agent内存/上下文工程）。
  • 阶段3.5按层级路由 ——将持久化条目路由到正确的存储位置（约定规则→CLAUDE.md/AGENTS.md，决策→仓库ADRs，状态→PROJECT_STATUS），而非默认全部存入本地内存；内存仅保留剩余内容。三层划分是2026年的工程共识。
  • 通过文档化的原因强化现有的"不转储"/大小检查规则：上下文腐烂（内存臃肿时质量下降），选择性内存的成本比臃肿上下文低约10–20倍。
  • 成果目标：关键知识最终存储在任何Agent或队友都能找到的位置，而非孤立在某台机器的本地内存中。来源：State of AI Agent Memory 2026 (mem0); Agent Memory vs Context Engineering (Augment)。

Credits

致谢

Skill by: Neal Meyer
技能作者：Neal Meyer