memory

---
name: memory
description: "长期记忆库的读写协议。当需要记住跨会话的事实、偏好、决策，或需要回忆之前讨论过的东西时使用。覆盖：建册与建文件、提炼、遗忘、索引维护。触发词：记住、记一下、之前说过、上次、新建分册、归档。"
---

# 记忆库操作协议

记忆库在 `~/.memory/`（可用 `MEMORY_DIR` 覆盖）。**数据结构以 `~/.memory/README.md` 为准，本文件与它冲突时以库 README 为准。** 设计与运行时规则（四层结构、注入契约、判据、双 harness 差异）另有一份权威：记忆系统工作区内的 `docs/FRAMEWORK.md`——那份只在本机有效，换机器会指空，所以这里不写绝对路径。

CLI 在 `<插件根>/core/memory.py`，十一个入口：

| 命令 | 用途 |
| --- | --- |
| `status` | 总册：playbooks / topics / 项目册 / agent |
| `status --all` | 跨项目册汇总：每册几个子文件、几天日志、多久没动 |
| `checkup` | 体检，扫当前工作区的项目册日志 |
| `checkup --all` | 每个登记项目册都体检 |
| `index` / `index --write` | 查 / 修三张表漂移 |
| `workspaces` | 列登记的项目册，报路径丢失 |
| `workspaces --fix <id> <新路径>` | 路径丢了按 id 重绑 |
| `timeline [--days N]` | 跨项目册日志时间线，默认 30 天 |
| `init` | 建空库 |
| `init --agent <id> [--role <role>] [--from <id>]` | 建 agent 目录 + 角色卡，并写 `config.roles` |
| `roles --new <role> [--from <role> \| --blank] [--dry]` | 单独建角色卡，不写映射（下一步 `--map`） |
| `roles --map <agent> <role>` / `--unmap <agent>` | 改 `config.roles` |
| `roles --default <role\|none>` | 改 `config.defaultRole`（没映射的 agent 的兜底人格） |
| `init --project <路径> [--id <id>] [--title <标题>] [--kind <领域>]` | 建项目册 + git + 登记 + 同步索引。**`--kind` 没有默认值**：不传就永远不注入 playbook，checkup 会报缺 |

> **2026-10-26 结构变了**：`shared/domains/` 已拆掉。可枚举的东西是三类——**项目册**（`<workspace>/.memory/`）、**playbooks**（`shared/playbooks/<领域>/<类型>.md`）、**topics**（`shared/topics/<主题>.md`）。`index --write` 维护这三张表。

## 我是谁（agent 身份）

`agent_id` 现在是**人格名本身**（0.6.6 起不再拼 `-harness`；旧库里的 `moxie-dsh` / `moxie-wb` 由 `docs/tools/migrate_agent_id.py` 合成 `moxie`）。**人格不挂在 agent 上**——它读 `roles/<role>/SOUL.md`，agent 只是指向卡的指针：`config.roles` 定映射，`defaultRole` 兜没映射的 agent。

注入内容第一行 `# 长期记忆（agent: xxx，harness: yyy，库：...）` 就是当前身份，**不要猜**。

判定规则（代码在 `core/state.py`）：

1. `MEMORY_AGENT` 环境变量 → 整体覆盖
2. `payload.agent_type` → 专家 / 具名会话自带（普通会话没有这个字段）
3. `config.json` 的 `defaultAgent`（人格名）与 `config.roles`
4. 洗不出来 → `default`

**专家识别是半自动的**：专家会话大概率带 `agent_type`，会自动分到 `content-creator-wb` 这类目录；普通会话没有该字段，退回 `defaultAgent`；中文专家名会变成 `agent-<哈希>-wb`。拿不准就看注入首行的 `agent:`。

## 读

会话开始时记忆由 SessionStart hook 自动注入，不需要手动读。注入内容里如果有 `### 项目册 · <名字>`，那就是当前工作区的项目册入口，优先按它的子文件表取细节。

两级结构：

| 册子 | 路径 | 装什么 |
| --- | --- | --- |
| **项目册** | `<workspace>/.memory/`（cwd 向上找 `_meta.md`） | 只对这一部小说 / 这一个工程成立 |
| **总册** | `~/.memory/` | 跨项目、跨领域、关于用户本人 |

需要细节时的顺序：

1. 先看项目册 `index.md` 的子文件表，按 `when` 决定读哪个
2. 项目册装不下的（跨作品方法论、偏好）再去总册 `shared/index.md` 定位
3. **不要一上来读全部**

## 写

### 写之前必须做的事

1. 跑 `git -C ~/.memory status --porcelain`，看目标文件有没有用户的未提交改动
2. 有改动 → 先读全文，理解改了什么 → **只增补，不覆盖、不改写用户的句子**
3. 用户删掉的条目，不得自动加回
4. 用户和你的结论相反 → **问，不自行裁决**

### 写什么

只写跨会话还有价值的东西：稳定事实、偏好、决策与理由、项目进展、踩过的坑。

不写：一次性闲聊、能从当前对话直接看到的临时状态、路径与报错日志（那些进当天日志）。

### 冲突判定（四选一）

| 判定 | 什么情况 | 动作 |
| --- | --- | --- |
| **ADD** | 新事实，和已有不冲突 | 新增一行，行尾带 `（源：YYYY-MM-DD）` |
| **UPDATE** | 同一件事的新版本 | 改原行，旧值用 ~~删除线~~ 保留并标失效日期 |
| **DELETE** | 新结论推翻了旧结论 | 旧行标 `~~已失效 YYYY-MM-DD~~`，**不物理删除** |
| **NOOP** | 价值不大、重复、临时 | 什么都不做。**大部分信息属于这一类** |

判不准时选 NOOP，然后在日志里记一笔，等它第二次出现再处理。

### 写完必做

1. 更新项目册 `index.md`（当前状态、最近变更）
2. **在日志末尾补 `提炼：` 标记**——日志路径 `<项目册>/log/<当前 agent>/YYYY-MM-DD.md`。
   提炼了写目标文件，判断后不用提炼写 `提炼：无（理由）`。只写「无」不合格
3. 总册有改动就跑 `memory.py index --write` 同步总索引
4. `git -C <册子根> add <改过的路径> && git commit -m "<做了什么>"`（别用 `-A`）

### 日志三节模板

日志是过程，不是结论仓库。结论必须提炼出去，否则下次会话读不到。

```markdown
## 做了什么
（过程记录，不要求提炼）

## 结论
（可提炼的结论、决定、确认）

## 待确认
（悬而未决的）

提炼：无（理由）    ← 或 `提炼：world.md, characters.md`，必须写
```

**判据不靠关键词猜语义**：`## 结论` 非空 + 标记缺失或只有「无」→ 就是该提炼没提炼。只有 `## 做了什么` 的日志不报。

## 建东西（只由用户发起）

**AI 不提议建册或建文件。** 最多在对话里说一句「这块好像没地方放」。

先按判定树定类型，别一上来就问「建个分册？」：

| 类型 | 判据 | 怎么建 |
| --- | --- | --- |
| **项目册** | 换一个同类实例（另一部小说 / 另一个工程）就不成立 | `python memory.py init --project <工作区路径> --id <id> --title <标题>`，它会建骨架 + git + 登记注册表 + 同步索引 |
| **playbooks** | 换一个领域（小说 ↔ 科研 ↔ 工程）就不成立 | 手建 `shared/playbooks/<领域>/<类型>.md` |
| **topics** | 没有工作区、体量小、单一主题 | 手建 `shared/topics/<主题>.md` |

### 三问门槛

用户说要建之后，先问清三件事。**每个问题给至少 3 个具体选项 + 一个「其他」**，选项必须和当前内容相关，不能用通用模板凑数。

| # | 问什么 | 选项从哪来 |
| --- | --- | --- |
| 1 | 这东西装什么？ | 从现有文件推 2–3 个相邻边界 |
| 2 | 明确不装什么？ | 列出最容易混进来的 2–3 类 |
| 3 | 你想怎么分类？ | 给 2–3 套具体分类方案 |

三问全答清才建。答不清继续问，**没有「先建着看」这个选项**。

### 建完必做

1. 一句话定位（≤40 字；项目册写进 `_meta.md` 的「## 定位」）
2. 每个文件写 `title` / `summary` / `when` / `owner`（checkup 会查）
3. 写注意事项（见下）
4. `python memory.py index --write` 同步总索引
5. 记日志，提交

**不建空文件。** 记录模板（论文笔记、实验记录这类）等真有内容再建，格式写在引用它的地方。

### 子文件的三个检验

数量不限，但每个必须通过：

- 能写出一句话 `summary`，且**含具体名词**（出现「相关内容」「各种信息」「等等」判不合格）
- 能写出一个 `when`（说不出何时单独读它，说明该和别的文件合并）
- 和已有子文件的 `summary` 不重合

### 注意事项怎么写

写在 `_meta.md`，三类，**踩过坑才加**。判据：不知道它就会做错事。

| 类型 | 句式 | 例 |
| --- | --- | --- |
| 禁区 | `X 不进这里，去 Y` | 不贴正文段落。正文在作品文件里，这里只放设定和规则 |
| 前置动作 | `改 X 之前，先读 Y` | 改设定前，先读 `world.md` 的「已废弃设定」段 |
| 读取提示 | `X 以 Y 为准` | 数值以最新版为准。划掉的表示已失效，日期在后面 |

写不出就说不出「因为踩过什么坑」，那就留空。

## 遗忘

冷条目移入 `archive/<册子或主题>/`，主文件留一行指针。**永不物理删除。**

判据：`archive.staleDays`（默认 180 天）没被引用，且不是核心设定。归档前问用户。

## 每轮收尾（Stop hook 的两类提醒）

`Stop` **每次响应结束都触发**，不是会话结束才跑。两类提醒共用同一套门控：距上次提醒不足 6 小时 → 跳过；本会话已提醒过 → 跳过。

**第一类：今天的日志没提炼。** 当天日志有 `## 结论`，但缺 `提炼：` 标记（或只写了「无」）→ 提醒，并报出结论条数。

收到就做，别绕：把结论提炼进项目册对应文件，再补标记。

**第二类：记忆库久未写入。** 除上面两道门控，还要同时满足：

- 距上次写入超过 `afterMinutes`（默认 180 分钟）
- 本次会话至少 3 轮对话

收到提醒时二选一：

1. **有值得留的** → 写进项目册，更新索引，记日志
2. **没有** → 在当天日志记一条 `## digest | 无新增` 并说明原因，末尾补 `提炼：无（理由）`

**不要为了关掉提醒硬编内容。** 记「无新增」是正当操作，编内容是污染。

阈值在 `config.json` 的 `digest` 段，随时可改。

## 访问戳记

每次读记忆库里的文件，插件会把日期记进 `.state/access-<agent>.json`（**按 agent 分开**——同一个库多 agent 共用，混在一个文件里会互相覆盖）。你不用做任何事，也不要手改那个文件。

用途：攒够数据后，`checkup` 能判断哪些内容 180 天没被读过，作为归档候选。现在数据刚起步，还判断不了。

## 体检

`python memory.py checkup`，输出问题清单和「最该做的三件事」。

退出码：有严重问题 → 1，只有提醒 → 0。可以当脚本闸门用。

检查项共 **20 条**，按严重度分三级。**完整判据与阈值见 `docs/FRAMEWORK.md` §2.9，这里只列纲目**——两处都写全必然漂移，一处写细一处指路才对。

- **L1 严重**：日志未提炼、playbooks/topics 缺字段、项目册路径丢失、`kind` 格式非法
- **L2 该修**：`summary` 空话、注册表为空、`_meta` 缺字段 / 缺 `kind` / 缺「## 定位」段、focus 三条上限（5 条 / 600 字 / 7 天）、inbox 积压超 14 天、索引表漂移
- **L3 建议**：`when` 完全相同、目录里没有任何文件、`kind` 无对应 `method.md`、定位超 40 字、项目册 30 天没动、`index.md` 找不到某张表

第一条是头号问题：`## 结论` 非空但缺 `提炼：` 标记的日志，会以「严重」列在最前面。

## 硬规矩

1. `shared/raw/` 只读，永不修改
2. 每条结论带日期与来源，没来源的标 `AI 推断`
3. 删前先归档
4. 用户的手改优先于你的推断