[首页](../README.md) / 记忆与接力基础

# 记忆与接力基础

记忆用于让表达更符合用户偏好，并保留有来源的互动记录。工作会话仍使用原始内容；记忆不会向 Agent 发指令或替它完成任务。

## 当前可用

- 明确的简短表达偏好由本地规则及时记录，支持共享、人格和会话范围。
- 设置页可以手动添加、修改、置顶、删除，查看依据，并采纳或忽略候选。
- 默认关闭的后台整理可把有上限的用户短消息片段发送给当前转述模型，提炼候选。它增加模型用量，不阻塞前台转述。
- 每次转述最多选取 5 条表达偏好或互动约定，总内容不超过 600 字符。
- 接力记录已经具备持久化、范围检查、接收与关闭接口；自动切换角色、多人格调度和伴随台词尚未接入。

## 条目与范围

| 类型 | 用途 | 当前如何使用 |
| :--- | :--- | :--- |
| `preference` | 称呼、语言、表达长短与语气偏好 | 生效后可供正文转述参考。 |
| `agreement` | 与某个人格约定的表达方式、昵称等 | 人格或会话内使用，不自动共享。 |
| `context` | 当前会话的情况与临时约定 | 可管理、可在共享会话交接中引用，不直接加入汇报正文。 |
| `episode` | 有依据的共同经历摘要 | 保留为后续交互基础，不直接加入汇报正文。 |

每条记录包含 ID、内容、分类键、适用范围、状态、来源片段、标签、版本、创建/更新时间和过期时间。

- `shared`：同一插件所有人格共享的表达偏好。
- `persona`：绑定稳定的预设 ID；改名不改变归属，新建或另存预设不自动继承旧角色的私有互动。
- `session`：绑定会话，可进一步限定人格；本地识别的临时纠正默认同时限定当前人格。管理界面手动选择「当前会话（角色共享）」时，明确允许同会话角色引用。

当前存储以单一 owner 为使用边界，`ownerId` 为本地所有者标记，不是多用户认证系统。管理路由沿用插件 HTTP 认证；未来接入多用户时需要增加真实身份隔离。

较新的同范围、同分类偏好替代旧条目；当前会话条目优先于当前人格，当前人格优先于共享偏好。同级优先考虑置顶和相关标签，再比较更新时间。显式识别的临时偏好默认保留一天；会话范围不向其他会话传播。

正文输入将记忆作为引用数据，要求只调整表达，仍以原汇报的事实、条件与风险为准。候选、已替代、已忽略和已过期条目不参与选择；共同经历不进入正文。提示约束与字面量校验不构成完整语义证明。

## 来源与后台整理

只观察已恢复设置、已启用的主会话中用户发布的消息；助手输出、子代理与工具事件不形成用户记忆。注入上下文、可识别的代码、路径和引用块会先过滤；这仍是启发式处理，不保证去除所有技术或敏感片段。

本地规则只识别部分明确表达，如「简洁一点」「语气要轻松」「请用中文」。本地规则会跳过常见示例、引用块和条件句；复杂偏好可手动添加或通过后台候选整理。

后台默认每 5 分钟处理待整理消息，积累 8 条同会话、同人格消息时可提前启动；全插件同时最多一个整理任务，每批最多 12 条消息，最多生成 5 个候选。它使用当前转述路由，模型查询和生成共用超时，要求明确正常结束。失败保留尚未消费的批次，之后再尝试。

模型必须引用本批实际消息 ID 和原话中的连续片段。来源不匹配、跨会话或跨人格引用会拒绝整批提交；共享候选还要求来源中存在所有人格或全局共享的明确表达。模型提供的证据只说明出处，不证明其概括正确，因此模型结果始终作为候选，采纳后才生效。

本地序号游标用于防止同一消息在重放、重启或重试时重复采集。整理提交只消费当前批次，新到消息留给下一批。手动修改、删除、清空和关闭功能会使过时任务失效，不允许迟到结果写回。

## 管理、迁移与容量

旧统计 profile 继续用于诊断；其语言比例、句长等不再直接转为表达偏好。旧版保存的语气纠正只迁移一次，作为标记了来源缺失的候选；原 profile 中重复的纠正文本随迁移移除。

关闭记忆保留已存条目，停止采集与使用，同时取消整理并丢弃待整理片段。关闭后台整理只停止模型整理，明确偏好仍可本地记录。后台整理关闭时，无明确偏好的普通消息不保留文本，只记录用于去重的序号。

清空会移除条目、来源片段、待整理内容、交接记录及诊断样本；只保留不含正文的消息序号游标，防止旧事件重放后重新学回。删除单条记忆会清理其待整理来源和相同引用的重复片段，并撤销交接记录中对它的引用；其他独立条目不连带删除。用户以后重新明确提出的偏好可再次建立。

当前上限：200 条记忆、48 条短消息来源、32 条待整理消息、500 个会话序号索引、50 条交接记录（满时先回收已关闭的记录）；单条记忆 240 字符，单条源消息最多 1000 字符。缓冲超限保留较新的内容，不是完整会话档案；条目满时优先回收非生效且未置顶的记录，无法回收则拒绝新条目。会话索引满后停止为新会话采集，已跟踪会话仍可更新。

## 管理接口

所有接口均位于 `/persona-shell` 下，沿用现有 HTTP 认证。修改需要存储恢复完成；条目更新、删除、采纳和忽略必须携带当前 `version`，旧版本返回 `409`，避免覆盖其他操作。

| 路由 | 用途 |
| :--- | :--- |
| `GET /memory` | owner 管理视图：条目、当前人格、会话提示与整理状态。 |
| `POST /memory` | `add / update / delete / accept / reject`；`consolidate` 安排一次后台整理。 |
| `GET /memory/handoffs?session=...&persona=...` | 查询指定接收角色、指定会话的交接记录及当前仍可共享的引用。 |
| `POST /memory/handoffs` | `create / accept / close`，创建、接收、关闭交接。 |

### 为多个人设接力预留的规则

交接记录包含 `fromPersonaId / toPersonaId / sessionId / summary / memoryIds / status / version`。摘要当前由 owner 明确提交，来源标为 `owner-authored`，不声称是角色亲历或已经执行的工作。

`memoryIds` 只能引用生效的共享偏好，或明确向角色共享的同会话记忆。人格私有记忆、其他会话记录不能自动导出；读取交接时再次检查范围，避免创建后改成私有的条目仍被另一角色读到。接收者可以读取摘要，但不会把摘要自动复制成自己的长期经历。

状态为 `pending → accepted → closed`；接收操作对同一记录重复调用保持幂等，关闭需匹配当前版本。接收和关闭都绑定接收角色与会话。新增或关闭记录不会切换当前人格、启动模型或向工作线程发消息。

这套接口提供记忆层的交接基础。未来调度器仍需决定主持权、角色轮次、失败退回和展示方式；真实多用户授权与多人格自动协同另行设计。

---

[使用指南](./guide.md) · [架构与边界](./architecture.md) · [后续计划](./roadmap.md)