> ## Documentation Index
> Fetch the complete documentation index at: https://forgekit-docs-mintlify-7cd64f48.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 跨会话记忆

> 会话锚定、完成门、handoff 快照和决策日志 —— 用来终结会话失忆和半成品工作的一层。

这一层存在的意义是要消灭两种失败模式：**半成品工作**（代码改了，但依赖
它的产物没跟着改）和**会话失忆**（下一个会话把这一个知道的东西又假设了
一遍）。指令只是提升正确行为的 *概率*；确定性的钩子才能保证一个 *底线*。

## 会话锚定

在 `SessionStart` 上（`src/session.js`），Forge 每次会话记录一次 `HEAD`，清理
一周前的会话产物，并注入一份新鲜的定位信息：

<CardGroup cols={2}>
  <Card title="已学到的经验" icon="graduation-cap">
    从过去的修正中挖掘出来的 Cortex 经验。
  </Card>

  <Card title="锚定的目标" icon="bullseye">
    既定的目标，好让漂移可以对着它衡量。
  </Card>

  <Card title="handoff 快照" icon="camera">
    上一个会话写下的、有界的 `.forge/state.md`。
  </Card>

  <Card title="最近的提交 + 变更" icon="code-commit">
    最近的提交和未提交的变更 —— 证据，而不是先验假设。
  </Card>
</CardGroup>

新会话是基于证据定位的，而不是基于先验。

## 完成门

Stop 路径上唯一有资格作出回应的 guard 是 `completion-gate.sh`
（`src/gate.js`）。它同步运行；负责挖掘经验的 `cortex.sh stop` 保持后台运行
并永远不能阻塞。

变更集合是**会话范围**的：来自 committer 时间不早于会话开始时间的提交里的
文件，加上工作区的变更，减去 `SessionStart` 时快照的脏东西 ——
所以已存在的编辑、切分支、`git pull` 都不会被算到代理头上。

<Note>
  如果代码动了，但没有对应的文档或状态产物跟进，这个门会**阻塞一次**，
  并以一份修复清单作为原因。其他所有情况都放行，任何内部错误
  也都放行（fail-open）。`FORGE_STOPGATE=0` 可以关掉它。
</Note>

修复清单指向那些能收尾工作的工具：

```bash theme={null}
forge docs sync                      # sweep the diff for stale doc mentions
forge handoff "<done>" --next "<next>"   # write the bounded session snapshot
forge decide "<decision> — <reason>"     # record a choice so no session re-decides it
```

## Handoff 和 decisions

两个存储把知识跨会话保留下来：

| 存储                    | 语义                                          |
| --------------------- | ------------------------------------------- |
| `.forge/state.md`     | 有界的**重写**（快照）—— 加载成本永远是 `O(bound)`。         |
| `.forge/decisions.md` | 只追加的 **ADR-lite**（`D-####`），带一份机器可读的决策账本副本。 |

两者在写入时都拒收秘密。`state.md` 每次会话开始时会重新注入；
`decisions.md` 在重新决定过去某个会话已经定下的事情之前会被读一遍。

```bash theme={null}
forge handoff "<what's done>" --next "<what's next>"
forge decide "<decision> — <reason>"
forge decide                 # read the log before re-deciding
```

## 由 diff 驱动的文档扫描

`forge docs sync` 回答一个 diff 形状的问题：变化过的标识符（路径、
定义和被调用的符号，来自新增 *和* 删除的行）对着每份文档
产物扫描 → UPDATED / STALE（带 file:line 命中）/ VERIFIED-UNAFFECTED，并把
原因记录下来。它只做汇报；牙齿由完成门提供。

<Warning>
  `recall` 和 `cortex` 只是文件加提示词的记忆 —— **不是**权重级别的学习。
  Consolidate 是一个可能产生幻觉的摘要器，所以它保持建议性、
  可由人审阅、且不含秘密。
</Warning>