# 记忆目录与主题整合

本次实现两项能力：默认可见的记忆目录，以及按需展开的跨事件主题概览。经验提炼不在本次范围内。

## 使用方式

- 用户画像继续单独常驻。默认目录提供 Chapter 标题、description 和按稳定顺序排列的 Section 标题，并保留主题编号；不注入 `.0` / overview 正文。
- 目录只用于导航；主题概览把已有事件整理为背景、进展、决定、变化和待确认问题，每段保留事件来源。
- 一个 Topic 对应长期的大章节，例如“StrataGate”“求职与职业发展”。节是能持续容纳同类事件的长期类别，例如“缺陷排查与修复”“版本发布与安装”“架构与配置决策”；单个 bug、版本、日期、任务和处理状态留在节内总览与原事件，不独立成节。已有类别能容纳时复用原标题，同类不同状态或不同版本不再拆节。分类随章的实际内容归纳，不套全局固定表，不设硬节数上限；归类不改变任何事件事实。
- 小节归属单独保存在 `sections` 的标题与事件编号中；总览只概括内容并保留各段自己的证据引用。同一章内同名小节及总览按全半角、大小写和空白规范化匹配，与段落类型无关。新总览的展示标题必须匹配本轮声明或继承的小节；省略标题时，其类型对应的默认名称也必须匹配，模型解析和显式 `sections` 写入共用同一校验。总览不能自行建立无事件的小节；旧快照及无 `sections` 的旧 SDK 调用仍按来源和类型名称恢复，有效旧总览可原样保留。节的 `.0 总览` 按各段最早来源在章节中的位置排序并原样展示内容，同位置按最晚来源位置及稳定内容排序；`.1~N` 分页展示归入该节的事件，不要求总览引用每条事件。没有总览的小节仍展示事件，界面不显示空的 `.0 总览`。
- 新模型结果必须为每条本批章节成员分配至少一个小节；总览可为空，旧小节归属和有效概要由存储层继承。只有本批事件可按显式新归属重新分类；非本批旧事件确认某条关系时，保留其其他小节归属。存储层先确定最终小节，再处理总览：重分类使旧小节没有事件时，丢弃对应旧总览，包括本轮原样回传的旧段；新总览指向已消失的小节则拒绝整次写入。小节仍有成员时继续保留有效旧总览，不为保存总览恢复已移走的事件归属。界面“待归类事件”只包含本章尚无小节归属的事件，与未被概括的事件数量分别计算。旧快照按已有总览来源恢复确定的小节归属；0.3.3 首次 writer 打开时，为已完成整理但仍缺少小节关系的旧事件排队一次定向补归类，包括此前已持久化 `sections` 的候选数据。补归类按原章分批，只更新该章的小节成员关系，保留章 ID、章名、描述、成员顺序、已知归属和有效总览，不重新提取事件。某事件属于多个章时逐章补齐；没有总览也必须写入真实归属。迁移标记及剩余关系持久化，重启不反复排队；只读访问不启动补归类。旧 SDK 调用缺少 `sections` 时仍兼容普通整理，补归类任务必须提供显式 `sections`。
- 旧事件补归类复用历史整理后台，全库每 10 分钟最多 2 个历史任务，不重置已有额度；新增或修改的事件仍走优先增量路径。模型不可用或额度耗尽时暂留待归类，后台恢复后继续。工作单位是“章节、事件、来源版本”的关系：一个章节等待重试或耗尽重试不会阻止其他章节补齐同一事件。每个任务最多 3 次尝试，失败可通过现有“重新整理”入口发起新的有限周期；重启不会自动清零重试。目录保留未完成关系数及失败关系数，不把多个章节的关系压成一个事件来判断结算；仍有其他关系待处理时显示处理中，只剩终态失败关系时返回 `failed` 并显示未完成和重新整理入口，不报全部完成，也不保持正在处理的轮询状态。遗忘、归档或来源修改会撤销旧版本的补归类关系及过期结果。为控制输入，补归类候选省略旧总览，最多显示 120 个且合计不超过 4,000 字符的完整小节标题，明确提供省略数量；原章必须在实际模型输入中，不能静默裁掉或改分到其他章。
- 小节按其成员在章内成员列表中的最早位置排序，不跟随模型输出段落的先后顺序；同位置用稳定节编号排序。已有成员在前、新事件追加在后，因此新事件形成的新节置后，旧节不会因为新总览前置而改号。更新后的目录视图版本使旧编号及分页缓存失效。
- 主模型按需打开主题，再通过现有事件、图谱或原文工具取证，继续使用现有证据检查与采用流程。
- 现有自动召回继续工作，目录与概览不能成为唯一检索入口。

工具按需要选择：`memory_list_topics` 浏览或查询目录；需要主题脉络时用 `memory_expand_topic` 查看概览，需要事实证据时可直接用 `memory_search_events(query, topic_id)` 核实事件，再进入既有证据评估与采用流程。前两个工具不生成证据批次。空查询可浏览主题事件，使用返回的 `nextOffset` 继续分页；`temporalIntent` 可选择最早或最新记录。

## 范围与维护

- 目录覆盖当前命名空间内可见的对话事件和主动记忆，含没有图谱节点的事件。
- 图谱展示聚类只是可选分组线索，不能将不相连节点的展示拼组当作语义主题。
- 后台用已有事件分批整理历史，后续只处理内容、状态或关联变化。检索时间、采用次数和衰减不触发重新生成。
- 首次写连接打开命名空间时，固定已有历史事件的版本清单，持久记录“待处理 → 处理中 → 已完成”；新命名空间冻结空集合并直接完成，随后新增事件都按增量处理。关闭或重启后接着处理未完成批次，已成功批次和主题编号保留；整理器版本升级时才开启新的回填清单。并发打开沿用先成功保存的清单，只读访问不初始化、不迁移。
- 整个数据库的历史回填每 10 分钟最多启动 2 批，每批最多 12 条事件。额度在调用前持久预扣，各命名空间共用，重启不重置，失败重试也占额度；达到上限后保留简略入口，下一窗口继续。这个上限约束后台整理任务，模型桥内部的格式重试和适配器降级仍分别有固定上限，并不承诺固定金额。新增或语义变化的事件优先整理，不占历史额度。旧章因某条来源或背景依赖变化而整章失效时，其余未变化成员的重建必须共用这份历史额度，不能变成无限制增量任务。重建版本单独持久记录，不改写首次打开冻结的历史清单；旧测试版已失效的积压也保守归入历史额度。
- 每轮最多尝试 3 次，失败等待至少 30 / 60 秒，历史额度不足时等待更久。用尽次数后停止自动重试。用户可在历史整理的失败详情中选择“重新整理这 N 条”：仅将该批当前有效来源排队为新一轮，仍占共享历史额度；成功批次不重做。来源变化、遗忘、过期目录及重复提交均不能强行复用旧失败；新任务编号拒绝旧结果。排队和进度持久保存，重启不重置预算。“已完成”表示本轮任务已结算，不代表所有批次成功。
- 本次主题整理器升级到第 3 代。首次写连接打开第 2 代目录时，保留来源及依赖仍有效的章 ID、章名、成员顺序和创建时间，清空旧细节小节与旧派生任务/进度，冻结当时可见事件按新规则重新分批整理；节及节内编号会因本次重新分组更新。第 1 代碎章及混合/未知代目录仍整体退休，依赖已变化或隐藏的旧章语言不沿用。全程不修改事件、原文、图谱或采用记录，也不重置全库历史额度；新增及发生变化的事件继续优先。只读访问仅在内存预览：保留有效第 2 代章的导航，隐藏旧小节并保留事件入口；不启动历史整理、不写库。第 1 代旧目录仍隐藏。第 3 代成功进度和编号在重启后保留，不反复重建。
- 旧章候选仍最多 12 个，排序结合全部已有节标题以及少量成员标题和标签。每个已展示候选提供全部轻量节标题、最多 4 段正文；节标题不授予未展示事件的引用权限。提示要求可容纳新事项时逐字复用已有节标题，不近义改名。同名章在已展示候选中唯一匹配时复用编号；全局已有同名正式章但未展示时拒绝结果，不静默创建重复章，显式改名也不能撞上另一章；不同项目仍独立归类，不引入永久跨章合并机制。
- 失效只标记一次。模型遗漏主题编号时，存储层为明确的成员延续复用编号；无法唯一对应的旧失效主题，在所有仍可见成员成功处理后移除。分批成功进度不会被旧主题再次清零，过期模型结果仍拒绝。
- 每章每次模型响应最多 8 段概要；这限制单次输出，不是累计段数或节数上限。有效旧段自动保留，不被新段挤掉；同名段仍聚合成一个节。章节累计内容与全量 JSON 存储的增量化另行跟踪。
- 每批模型输入及输出有固定上限，调用有超时、有限重试和重启恢复；主模型上下文组装只读取目录。
- 尚未整理和暂时失败的事件仍提供可验证的简略入口，不阻塞普通检索。
- 每批最多整理 12 个事件，候选旧主题最多 12 个，模型输入含结构约束不超过约 20,000 词元。每段概览注明来源；主题展开限制约 2,400 词元。展开结果优先保留轻量 `sections` 索引（标题和 `sourceEventCount`），包括无总览的小节，并用 `totalSections`、`omittedSections` 说明省略范围；索引、概要、省略计数和外层响应共用预算。全量小节成员关系只在服务端分页，不加入模型展开结果。
- 主题目录按偏好与要求、决定与计划、工作与结果、交流与协作、其他经历分类；分类仅用于浏览，不改变主题内容和编号。完整目录每页最多 20 项。
- 正式主题按创建时间从早到晚排列，新增主题追加；同一时刻仅以不可变的主题编号排序，改名不改变章序。注入目录、主题工具与界面共用这一顺序，待整理入口置后，展示章号不写入数据库。
- Dashboard 只返回主题、节、总览段落及事件数量，不返回事件成员编号、全量标题或摘要；Bootstrap 失败详情也只传数量。完整成员关系保留在服务端。节编号由规范化标题派生，界面与分页共用同一聚合规则。展开节、待整理或失败详情时，用只读接口每页最多读取 9 条事件；数据版本变化时丢弃旧页。同类型但不同标题仍是不同节，同名段落合为一个节。
- 目录默认预算不超过 400 个估算词元，原相关记忆预算为 900 词元。超预算时先预留分类、`memory_list_topics(category, offset)` 分页和 `memory_expand_topic(id)` 小节入口；优先保留章标题与 description，再逐轮为各章加入小节标题。章信息仍放不下时优先保留各分类的章入口，必要时省略 description；全部输出共用预算，未展示的章和小节可继续按需浏览。

## 必须始终成立

1. 事件和原文是证据底座，目录与概览不写回为新事件，不登记采用证据，不强化记忆。
2. 主题编号独立于展示聚类成员；每条可见目录文字和概览都有可验证的来源依赖。
3. 来源被遗忘、归档、撤销或修改后，旧派生文字先停止曝光，后台再重建。不能通过原始对话重新总结来复活已隐藏的事件。
4. 模型结果提交前重新核对读取时的来源版本；过期任务不能覆盖新版主题。
5. 主题只在当前命名空间可见；安装级画像不自动并入项目主题。
6. 历史、计划、取消、争议和当前事实不能在整合时混为一谈；缺少信息保留为待确认问题。
7. 升级、失败和重启不会修改或删除已有事件、图谱和原始对话；目录可独立重建。

## 验收

验证模糊查询发现主题、无图谱事件覆盖、按主题取证、增量整合与稳定编号、隐藏来源即时失效、过期提交拒绝、零采用强化、命名空间隔离、旧库升级、重启恢复、有限重试、输入和目录预算，以及后台失败时原搜索继续可用。测试只使用临时数据库与模拟模型。