# 设置与使用说明（运动记忆）

> 本文是 [README.md](README.md) 的配套文档：全部配置项、各功能工作原理、引用格式与工具详解。

设置界面入口：DSH 设置页 →「运动记忆」（记忆面板在对话页的「记忆」页签）。

> 所有改动自动保存：文本框/数字框**失焦即保存**，复选框/下拉**改动即保存**，右上角浮窗提示结果。

---

## 一、基础配置

| 配置 | 说明 | 默认 |
|---|---|---|
| **记忆根目录** | 所有记忆文件存放的文件夹路径。换路径 = 换一套记忆，历史记忆留在旧目录 | 自动生成 |
| **归档天数** | 记忆文件在 N 天后进入归档压缩（重要 → 补充区；事件/无模型按年月归档）。数值可带小数 | 30 |
| **记忆衰减天数** | 记忆得分随时间线性衰减的窗口（天）：窗口内从 100% 降到"衰减下限"，超过窗口保持下限。影响查询排序 | 30 |
| **总结摘要字数（k token）** | 会话工作的摘要/注入长度预算（k token，换算走内部语言表：中文约 1.5 字/token）。① **works 记录链总量预算**：超了把最旧记录压缩为"指向+短摘要"；② **对话跟踪注入【本会话现有工作信息】的软字数限制**（md 超链接不计入，允许略超，输出上限兜底） | 2 |
| **提示词注入**（折叠） | 会话启动时自动加载记忆总览，让模型"带着记忆开工" | 开 |
| └ 启用提示词注入 | 开=注入；关=完全不注入，模型需要时自行 `memory_query`（省 token） | 开 |
| └ 注入上限（字节） | 注入文本总量上限，超出从最早的记录开始截断 | 4096 |
| └ 最近事件总览 | 首轮总览注入「最近会话工作」显示最近 n 条工作段摘要（各智能体活跃文件 works，按更新时间取最近 n 条） | 3 |
| **阅读与查询设置**（折叠） | 工具读取记忆时的行为 | — |
| └ 关联记忆展开（层数） | 阅读一条记忆时，按关联引用展开子记忆 n 层（0=不展开）。层数越多上下文越全也越费 token | 3 |
| └ 查询/增量历史显示条数 | 阅读记忆时附带最近 n 条查询/更新记录（0=不附带），用于理解记忆演变 | 5/5 |
| └ 历史分页条数 | 查看全部历史时每页加载 n 条 | 20 |
| └ 读取截断字符（每侧） | 读长文本时只保留开头+结尾各 N 字符，中间省略 | 500 |
| └ 跨智能体查询 | 开=可查询其他智能体的记忆；关（默认）=只查本智能体 | 关 |
| **活跃索引得分参数**（折叠） | 当前活跃文件里引用条目的得分机制 | — |
| └ 周期/事件/关键词初始分 | 三类记忆被引用进当前活跃时的初始得分（周期 5 / 事件 3 / 关键词 2） | 5/3/2 |
| └ 衰减下限 | 得分随时间衰减的最低保留比例（0.2 = 最低保留 20%） | 0.2 |
| └ 淘汰阈值 | 衰减后得分低于此值则从索引移除 | 0.3 |
| └ 索引最大条数 | 当前活跃 refs 最多保留条数 | 50 |
| └ 事件扫描月份 | 事件区按年月目录定向扫描的窗口（新→旧，最近 N 个月） | 3 |
| **活跃变更通知** | 对话跟踪每轮总结后，向其他会话注入"记忆有更新"的通知（关掉后各会话不再收到跨会话变更提示） | 开 |

## 二、记忆管理员（全局模型参数）

管理员是所有自动总结（对话跟踪 / 周期 / 强化）的**默认模型**。**管理员模型留空 = 管理员功能全部关闭**。

| 配置 | 说明 | 默认 |
|---|---|---|
| **管理员模型** | 指定 provider/model 后自动启用管理员功能。**建议用本地模型**（LM Studio / Ollama 等），模型越稳越好 | 空（关闭） |
| **上下文 token 上限** | 管理员模型的最大上下文长度（k token）。**要和模型实际支持的长度匹配**，设大了模型会溢出报错 | 128k |
| **总结占用百分比** | 总结内容最多占上下文的百分比（总结预算 ≈ 上下文 × 百分比）。内容超过预算会自动分块、逐块总结再合并 | 50% |
| **并发（段裁剪并行）** | 内容切块后同时发起多少个总结请求；0=串行（一块处理完再下一块），N=同时最多 N 块并行。**本地小模型建议 0** | 0 |
| **输出上限** | 管理员模型单次输出的最大长度（k token） | 1024k |
| **自定义 JSON** | 给模型调用附加参数（如 `{"temperature": 0.3}`、`{"enable_thinking": false}`），可控制采样/思考开关 | 无 |
| **token 估算语言表**（折叠） | 估算 token 用量用的每字(词)值：中文按字、英文按词、日/韩按字、其他按字符 | 1.5 / 1 / 1.5 / 1.5 / 1 |

> 提示：`上下文 × 百分比 − 输出上限` 需 ≥ 一定余量，否则总结预算会非常小；设百分比/输出时留意。

## 三、对话跟踪（轮次自动总结）★ 核心功能

每个会话每轮对话结束时，自动把本轮内容压成一条记忆（含经验教训），累积进该会话的聚合文件。

| 配置 | 说明 | 默认 |
|---|---|---|
| **启用对话跟踪** | 主开关 | 关 |
| **模型配置** | 独立模型（留空继承管理员）；选「**无模型**」则不调模型，只把用户消息以引用形式累积到"无模型记忆整理"区，可经周期总结转正 | 继承 |
| **触发间隔** | 0=每轮总结；N=每 N 轮总结一次。**首次总结时把间隔记录到该会话的记忆文件里（trackMeta）**，之后该会话按自己的记录判断；改配置后换回继续对话，会新增一条记录，跨重启不丢 | 0 |
| **修改当前活跃后通知注入** | 开=每轮尝试向其他会话注入当前活跃新变化；关（默认）=不注入，模型需要时自行查询，省 token | 关 |
| **摘要注入长度** | 注入其他会话的摘要截取字符数 | 300 |
| **精确到步骤** | 勾=溯源精确到 `会话@轮次:stepN`（高精度，适合强模型）；不勾=整轮指向 `会话@轮次`（一般模型即可） | 关 |
| **节约控制** | 读取轮次内容时的裁剪方式，省 token：`不看工具使用和输出` = 只留用户+assistant 文本；`只保留用户消息+末尾 k` = 最省（用户消息 + 末尾 k token） | 都关 |
| └ 截断保留量 | 「只保留末尾 k」的 k 值 | 2k |

工作原理：
- 同一会话的多轮总结**累积进一个聚合文件**（`记忆累积/年/月/session-<id>.json` 的 `turns[]`）；
- 每会话独立记录 `trackMeta`（起始轮次 + 触发间隔），换配置 / 换回继续对话都能正确识别轮次间隔；
- **程序保证每个会话的 works 工作段存在**：新会话首次总结前程序自动建空白段（不依赖模型输出 prepend），模型只负责更新编写内容；总结失败/无内容时空白段保留，总览注入会提醒待总结；
- 空白段 + 无模型整理区有该会话内容时，对话跟踪读取无模型内容推断总结，成功后填充工作段并移除无模型文件；
- 总结时模型维护本会话的 works 段（增量/整合/覆盖，超字数预算自动转"指向+短摘要"），被覆盖的旧内容进历史；works 段被压缩/周期下沉删除前**归档到 补充/YYYY/MM/<sid>.json**（按年月分散，同名文件 entries 按天合并，含查询记录）；
- 历史记录按 **agent + 会话 + 天** 合并（times 内部记准确时间，delta 留当天最终版）；查询计分按天去重（同一天重复阅读只计一次）；
- **未跟踪的会话**：轮次页仍按"1 到当前轮次"显示空白区间，可手动「补充」创建事件记忆。

## 四、强化记忆搜索

| 配置 | 说明 | 默认 |
|---|---|---|
| **启用强化记忆搜索** | 手动调用 `memory_enhance` 时生效，帮 agent 做更广的检索，避免只按字面词漏掉相关内容 | 关 |
| **模型配置** | 独立模型（留空继承管理员） | 继承 |
| **查阅深度** | 展开命中记忆的关联层数（越深上下文越全，也越费 token） | 3 |

工作原理：模型读取「真实命中记忆 + 引用记忆展开 + 对话上下文」后，输出扩展检索词和相关记忆；扩展词二次召回，相关项逐条做真实性校验，模型编造的直接忽略。

## 五、周期总结记忆 ★ 核心功能

定时把"**未周期总结过的**当前活跃 + 重要 + 事件记忆"批量收拢，压缩成一份周期摘要，防止记忆越积越多。

| 配置 | 说明 | 默认 |
|---|---|---|
| **启用周期总结** | 主开关 | 关 |
| **模型配置** | 独立模型（留空继承管理员） | 继承 |
| **周期定时** | 间隔天数 + 小时，距上次周期总结达到即自动触发（后台每分钟检查一次） | 1 日 |
| **最近素材跳过天数** | 最近 N 天的事件素材不参与周期总结（默认 14，最小 7）——近期记忆保持"热"状态不被过早压缩；会话工作段仅被 N 天前的周期总结下沉 | 14 |
| **周期影响度** | 按影响度（查询次数权重 + 时间衰减，30 天线性 100%→20%）排序取前 N% 或前 N 个 | 100% |
| **总结方案** | 决定素材范围（见下） | 方案1 |
| **方案3 运行参数** | 「跳过工具输出」「只保留末尾 k token」（+ k 值）：读取**未总结轮次**原文时的节约参数，**持久生效**（不只是本次） | 都关 |
| **工具记忆参与总结** | 是否把工具产生的记忆纳入周期总结素材 | 开 |

三种方案：
- **方案1（省 token）**：仅收拢事件记忆（+无模型整理区 + **补充区关键词**——被遗忘/移补充到补充区的关键词也纳入素材，防止遗忘导致信息彻底丢失），适合记忆量小、求快的场景；
- **方案2（推荐）**：事件 + 每个会话的**首轮 + 尾轮**，兼顾事件与对话脉络；
- **方案3（最准最贵）**：**全部轮次**都纳入——**对话跟踪已总结的轮次直接合并其总结内容**，**未总结的轮次读取原文**（按方案3运行参数节约）触发总结。适合对会话完整性要求高的场景。

产物：一份周期记忆文件（`记忆累积/周期记忆/年/月/`），记录被覆盖的事件/关键词溯源；被覆盖的素材打上"已周期总结"标记，后续周期不再重复处理。

**B 下沉 + 会话复活复原**：
- 周期总结完成后，被覆盖会话的 works 工作段**先归档到 补充/YYYY/MM/<sid>.json，再移除**（只保留周期指向段）——避免工作段无限膨胀；
- 旧会话重新激活时，对话跟踪在"建空白段前"先尝试**复原**：从补充区同名文件取最近历史 → 写回 works（refs 带 period-restore 标记，history 记一条"复原"），复原成功则不建空段；
- 定位依据是周期文件 `range`/`sessionTurns` 事实 + 进程内 `sid→周期文件` 高缓存（周期完成时登记，不按配置天数计算），复杂度 O(1)。

## 六、记忆污染隔离

| 配置 | 说明 |
|---|---|
| 回溯到（年月日时间） | 指定一个过去时间点，触发隔离：把该时间之后被改动过的记忆快照到隔离文件夹 |
| 回滚 / 解除 | 回滚 = 恢复该时间点的内容；解除 = 保留隔离文件夹但解除通知（防止模型写入错误内容污染长期记忆的最后防线） |

---

## 七、引用转跳（记忆内容可点击溯源）

记忆正文中支持以下链接写法，页面点击即可转跳 / 读取对应记忆：

| 指向 | 写法 | 点击行为 |
|---|---|---|
| 会话轮次 | `[文字](会话id@轮次)` 或 `[文字](turn:会话id@轮次)` | 弹窗读该轮次内容 |
| 轮次步骤 | `[文字](会话id@轮次:stepN)` | 弹窗读该步内容 |
| 关键词/多词 | `[文字](记忆累积/重要/标题.json)` | 跳关键词页 |
| 补充记忆 | `[文字](记忆累积/补充/YYYY/MM/标题.json)` | 跳关键词页（归档） |
| 周期总结 | `[文字](记忆累积/周期记忆/YYYY/MM/...json)` | 跳周期页 |
| 事件记忆 | `[文字](记忆累积/YYYY/MM/DD_...json)` | 弹窗读该事件 |

弹窗内容同样支持内部引用：点击进入下一层，`← 返回` 逐级回退（引用翻页）。模型生成 / 创建记忆时按此格式输出引用，页面即获得"生成即引用、点击即溯源"的体验。

## 八、记忆页使用要点

- **会话记忆**：列表显示会话短标题（来自会话日志）+ 摘要副标题 + 完整会话 id（可复制）；支持按 标题/会话id/摘要 搜索。**默认不设时间窗、直接加载全部未归档**（时间条保留，需要收窄时手动选起止日期；"含归档"开关才会扫补充区）。
- **轮次总结**：固定只看**当前会话**（由会话视图传入；从会话记忆页点进某会话时聚焦该会话），每条轮次可「修改」「原文」（弹窗读原始对话记录）、重新总结（当前活跃 / 当时活跃双模式）；未总结的空白轮次按"轮次 1 ~ 当前轮次"逐段列出，可「补充」。
- **活跃记忆**：自定义设定 / 关键词 / 会话工作段 / **历史记录** 分块管理。**自定义设定**=本智能体必要记忆（agent.md 语义，手动维护、对话跟踪不覆盖）。**关键词区每个词是独立词条**：点击词条跳转对应记忆、`×` 直接移除（可随时再加回）；`+ 增加` 弹窗从关键词库挑选（时间范围 / 含归档 / 多智能体筛选与关键词页一致；点词条展开内容，`-`/`+` 选择并自动置顶，滚动位置保持），确认后去重合并进当前活跃。**历史记录区**：按设置条数显示、加载更早直到创建位置、分类过滤（默认只显示"增量更新+遗忘更新"）。
- **关键词**：顶部**智能体筛选**行默认只显示当前会话智能体的关键词（跟随当前窗口会话变化），点 `×` 移除某智能体、空白=显示全部、`+` 弹窗多选；每个词条显示归属智能体（预设显示名）与得分；新增 / 修改 / 删除（归档到补充区）；写入时自动查重分流（同名返回内容，近似候选提示，消歧自动关联）；内容区点击展开/折叠全文。
- **周期总结**：内容可编辑，「重新总结」可选「当前活跃」或「当时活跃」双模式，「升级方案」换素材范围重跑。

### 首轮总览注入（提示词注入）

会话首轮自动注入 `<system-reminder>运动记忆·会话总览</system-reminder>`，结构：
- **必要记忆**：本智能体活跃文件的「自定义设定」（agent.md 语义，手动维护、对话跟踪不覆盖）；为空不显示；
- **当前活跃关键词**：本智能体活跃 keywords（指针，指向重要记忆；不设数量上限，靠"与近期会话工作相关"维护）；
- **待总结提醒**：按对话跟踪状态区分——未开启：大段工作完成后请自行总结（写入当前会话 works；该会话无对应事件记忆时创建并写入同样轮次总结）；已开启：跟踪自动总结，不需全部自行总结；
- **最近会话工作**：各智能体活跃文件 works 最近 n 条摘要（条数用「最近事件总览」配置）；
- **记忆使用约定**：内置使用指引。

> 重要记忆标题列表不再注入（v6）：本体用 `memory_query` 按需查询；模型看到活跃关键词指针后，判断与当前聊天相关时用 `memory_query open`（带关联展开，默认 3 层）主动挂载详情。

## 九、工具详解

### memory（综合入口）

`status`（状态）· `config`（配置读写）· `notify`（变更通知开关）· `recent`（最近活动）· `history`（历史记录）· `recall_past`（往时回忆）· `restore`（捡回补充记忆）· `track_run`（对话跟踪手动）· `period_run` / `period_status`（周期总结）· `enhance`（查询强化）· `admin_view` / `admin_summarize`（记忆管理员）· `isolation` / `isolation_restore` / `isolation_clear`（隔离）

### memory_query（查询/回忆）

`keyword`（匹配记忆标题列表）· `open`（阅读指定标题：关联展开 + 历史记录）· `openTurn`（读会话轮次原文，`会话id@轮次[:stepN]`）· `recent`（最近事件）· `enhance`（深度增强：基础结果 + 关联展开 + 上下文整合，调模型）

### memory_add（写入）

- `kind=keyword`（默认）：创建关键词记忆；**同名返回已有内容，近似标题列出候选**（同一实体 → `kind=update` 更新；不同实体 → 用更具体标题新建并自动关联）；**默认自动挂载到当前活跃 keywords 成为指针**；同步维护活跃 keywords（对照近期会话工作，移除无关旧词，数量不设上限）
- `kind=necessary`：写入**本智能体**必要记忆（agent.md 语义：写入当前活跃「自定义设定」，随总览注入；`clear=true` 清空）
- `kind=event`：创建事件记忆（直接写入；带会话@轮次自动并入该会话聚合文件）
- `kind=update`：更新已有关键词记忆（diff + **mergeDated 默认自动合并日期变体** + forgetIndexes 遗忘历史）
- `kind=edit`：**用户明确确认后**修改任意记忆文件（含事件/周期等只读文件，必须 `force=true`）
- `kind=forget`：主动遗忘移入补充区（可 `restore` 捡回）
- `kind=reattach`：模型通过上下文判断后挂回/晋升——补充区记忆与会话工作强相关时挂回当前活跃（或 `promote=true` 移动回重要），触发「当前活跃启用得分」计分（设置页可配分值/加成）

规则：重要内容先落关键词，当前活跃里再指向它；更新活跃时同步整理 keywords 块（移除过时/重复，保持与近期工作相关）；引用必须真实溯源，禁止编造。

### memory_noop

无更新占位：本次总结/整理判定无有效记忆更新时触发，不写任何记忆文件。