> ## Documentation Index
> Fetch the complete documentation index at: https://forgekit-docs-mintlify-efdb1a73.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 time 大于等于会话开始时间的提交涉及到的文件,加上工作树变更减去 `SessionStart` 时快照的脏文件 —— 因此已存在的编辑、分支切换和 `git pull` 永远不会被算到代理头上。

<Note>
  如果代码动了但没有对应的文档或状态产物跟进,该门会**阻断一次**,阻断原因就是修复清单。其他情况一律放行,内部错误也一律放行(失败开放)。`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 与决策

两个存储让知识跨越会话:

| 存储                    | 语义                                          |
| --------------------- | ------------------------------------------- |
| `.forge/state.md`     | 一份有界的**重写**(快照)—— loader 成本永远保持 `O(bound)`。 |
| `.forge/decisions.md` | 只追加的**精简版 ADR**(`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` 只是文件和提示词记忆 —— **不是**权重级学习。合并是一个可能出现幻觉的摘要,所以它一直是建议性的、可人工审阅的、且不含密钥。
</Warning>