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

# Memory

> Memory 保存以后还会用的结论，不是完整聊天。

以后还会影响判断的内容，才值得写成 Memory (经过选择、以后还会用到的项目知识。)。已经做出的决策、必须遵守的约束、当前项目状态，或者明确的下一步，都适合留下。

完整聊天不要整段塞进来。聊天可以先成为 Source (记录发生过什么。采集不会自动写成长期知识。)。只有值得跨任务复用的部分，才进入 Memory。

留什么才是关键。一条范围清楚、结论明确的短条目，通常比对话式摘要更好找。项目变了，它也更好修订或停用。

## 什么应该进入 Memory

下面几类内容通常值得保存。

* “公开 HTTP 契约变化后，先重新生成签入仓库的客户端。”
* “这个项目要求 Python 3.11 及以上。”
* “OpenClaw 项目模式当前仍按 agent 隔离。”
* “下一步运行契约测试，并检查生成代码没有漂移。”

这些内容换一个会话，或者过几天再看，仍然有用。

临时调试输出、礼貌寒暄、一次性的工具进度，通常不该直接写成 Memory。先保留 Source，需要时再提炼。

## Memory 不是一行可覆盖文本

Memory 看起来像一条结论，实际上有三层身份。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Memory Artifact Revision
└── logical entry_id
    └── immutable entry_version_id
```

### Artifact Revision

每次 Memory 生命周期发生有效变化，会形成新的不可变 Artifact Revision。Revision 保存当时的清单和 change set。

### 逻辑条目

`entry_id` 表示同一条长期知识。修订后仍是这个逻辑条目。

### 条目版本

`entry_version_id` 指向某次具体内容。修订会创建新条目版本，并保留 `previous_version_id`、来源和创建它的 Memory Revision。

维护一条 Memory 时，只保存 `entry_id` 不够。精确 Citation 还需要对应的 Memory Revision 和条目版本 ID。

## 清单决定当前状态

某个 Memory Revision 的清单，是当时的权威目录。每个条目都会记下稳定的 `entry_id`、精确的 `entry_version_id`、内容哈希，以及 `active` 或 `inactive`。

`retire` 把条目变成停用状态，使它退出默认召回。内容和旧 Revision 仍然保留。

修订也不是原地覆盖。它创建下一条目版本，再让新 Memory Revision 的清单指向它。

## 两条写入路径

身份和清单清楚以后，再看内容是怎么写进去的。

### 显式写入

你已经确认要保存的内容时，直接调用 `remember_memory`。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "scope_id": "project:powercontext-101",
  "kind": "decision",
  "text": "Regenerate and inspect the checked-in client before running contract tests."
}
```

这条路径不需要模型，也不需要先创建 Source。它可以带 `expected_revision` 保护并发更新。内容真的变了，就返回 Memory 版本引用和精确条目 Citation。内容规范化后和现有条目一样，就是无变更，这时只返回当前 Memory 版本引用，`entry` 可以是 `null`。

### 从 Source 抽取

自动路径先采集 Source，再由调度器或 `flush_memory` 处理 Source 窗口。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Source window
→ bounded evidence
→ model candidate
→ domain validation
→ canonicalization and deduplication
→ atomic Memory commit
→ cursor update
```

模型输出只是不可信 Candidate。它只能引用当前操作提供的证据 ID，不能凭空引用其他 Source 或 Artifact。

PowerContext 在同一事务中提交 Memory Revision、条目版本和启用状态搜索投影。任何一步失败，都不能留下“Revision 已提交但索引没更新”的半成品。

重复的规范形式内容可以变成无变更，不必制造一个没有语义变化的新 Revision。

> [!NOTE]
>
> 显式写入和 Source 抽取都能产生 Memory，但证据链不同。要证明某条 Memory 来自刚才的 Source，检查条目的精确 `source_refs`，不要只看搜索文本相似。

## 修订和停用

已经留下的条目还可以改，也可以先停用。修订应针对当前精确 Citation。新内容创建下一条目版本，旧版本仍可读取。

停用同样需要精确目标。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Memory Revision + entry_id + entry_version_id
```

停用后，默认启用状态列出和召回不再返回它。`include_inactive` 可用于审计。旧 Artifact Revision 和条目版本仍存在。

如果其他工作进程已经更新了 Memory 头版本，你手里的旧 Citation 会产生冲突。重新读取当前状态，检查差异后再决定，不要机械猜下一个 Revision。

## 搜索怎么工作

写入之后，下一次请求要靠搜索把它找回来。Memory 搜索不是把所有文本按一个相似度分数排序。它先确定当前 Memory 头版本，再根据能力和请求选择模式。

| 模式 | 前提 | 行为 |
| - | - | - |
| `fts` | FTS 投影可用 | 使用关键词证据召回 |
| `vector` | 嵌入模型、配置档、维度和 backend 向量能力完整 | 只走向量检索 |
| `hybrid` | FTS 与向量都可用 | 合并两路结果 |
| `auto` | 运行时判断 | 优先混合，不可用时选择 FTS |

如果查询嵌入暂时不可用或超时，`auto` 在 FTS 可用时可以退回 FTS。显式请求 `vector` 或 `hybrid` 时不能静默改模式，调用者应看到能力错误。

### Fusion 与重排序

混合搜索使用 reciprocal rank fusion 合并 FTS 和向量排名。当前实现的 RRF 常数是 60。

向量 admission 会把 unit-normalized L2 distance 换算为 cosine similarity，并应用最低相似度门槛。命中结果会保留 `matched_by`，说明来自 FTS、向量或两者。

可选重排序在检索之后运行。它可以改变最终顺序，但不会改写 Memory 或搜索索引。Rerank 开始后使用已选定的 Revision 快照，不应因为另一个写入推进头版本就悄悄换数据。

## PreparedContext 不是搜索响应的复制

搜到了，还不等于这一次请求就会把整段内容塞进模型。`prepare_context` 会先粗召回候选，再由构建器在共享 UTF-8 字节预算中选最终内容。

当前构建器有几个明确上限。最多 16 个 Memory 粗候选。最多 8 个 Experience 候选。最终合计最多 8 项，其中 Experience 最多 2 项。单项内容最多 2000 字节。

这些是当前实现细节，可能随版本调整。稳定契约是最终内容受 `max_bytes` 限制、带精确 Citation，并标记为 `untrusted_history`。

结果只有两种正常状态。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
empty → content is null, content_bytes is 0
ready → content is nonblank, content_bytes matches UTF-8 bytes
```

PreparedContext (这一次请求用的有界视图。带 Citation，不是长期资产。) 是本轮输入，不会自动变成新的 Memory。

## 用 OpenAPI 案例推演

先显式写入。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "scope_id": "project:powercontext-101",
  "kind": "decision",
  "text": "Regenerate and inspect the checked-in client before running contract tests."
}
```

再搜索它。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "scope_id": "project:powercontext-101",
  "query": "What should happen before contract tests?",
  "mode": "fts",
  "limit": 5
}
```

检查响应时看这四件事。命中的 `memory_ref` 应是当前精确 Revision。结果里应包含 `entry_id` 和 `entry_version_id`。`matched_by` 应符合请求模式。`prepare_context` 的 Citation 应指回同一个条目版本。

然后把内容修订成下面这样。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Regenerate the checked-in client, inspect the diff, and then run contract tests.
```

旧 Citation 此后仍能用于历史读取，但不能当作当前条目去修订或停用。

## 容易误判的情况

### `auto` 返回 FTS，不是混合

检查嵌入模型、配置档 ID、维度、backend 向量能力，以及当前 Memory 头版本的向量投影是否完整。

### 刷新处理了 Source，但没有新 Revision

模型可能返回无变更，或者 Candidate 经过规范化后与现有内容重复。先检查 Source 证据链和 change set。

### 搜索有命中，PreparedContext 却是空结果

PreparedContext 还有相关性、去重和字节预算约束。搜索命中不保证最终一定入选。

### Rerank 时 Memory 头版本已更新

当前搜索保持开始时选择的 Revision 快照。下一次搜索才会读取新头版本。

## 怎么知道分清了

1. Artifact Revision、条目 ID、条目版本 ID 是三层身份。
2. 停用是停用，不是删除。
3. 显式写入不需要模型，也不需要先有 Source。
4. 抽取 Candidate 要经过证据和领域校验。
5. `auto` 可以降级，显式向量或混合请求失败时不能静默改模式。
6. PreparedContext 仍是临时、不可信、有预算的视图。

对象已经清楚时，去[安装并运行 Server](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md) 写出第一条 Memory。要看采集路径，走 [Source 与 Memory](https://powercontext.mintlify.site/zh/basic-usage/source-and-memory.md)。

## 下一步

> [card] [再看谁来接着做](https://powercontext.mintlify.site/zh/mental-model/handoff.md)
>
> Memory 回答以后还要知道什么。Handoff 回答谁来接着做，以及从哪里开始。

> [card] [写出第一条 Memory](https://powercontext.mintlify.site/zh/basic-usage/install-and-run.md)
>
> 先启动本地 Server，写出一条 Memory，搜到它，再拿到带 Citation 的 PreparedContext。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.