stratagate-dsh 0.2.96 → 0.3.0

package/docs/DSH.md

@@ -87,7 +87,7 @@ Activated memory uses the current human message plus the latest two open-tail tu
 
 Automatic context contains only compact Event and fact fields from other conversations and is explicitly marked as historical background rather than instructions. Current-session Block evidence is excluded because each Block's current decayed representation already exists in native DSH history. Building automatic context never calls `recordMemoryUse`, increments `mentionCount`, or changes `lastAdoptedTurn`. The existing `memory_*` tools remain available for deeper, evidence-gated retrieval and are the only path to adoption reinforcement.
 
-Every explicit retrieval creates an independent batch. The model passes its `batch_id` to `memory_assess`, then closes that same batch with `memory_record_use`. It passes the exact `evidence_refs` from that batch used in its answer, or `[]` when it used none. Selected Event evidence is reinforced once; an empty list writes a zero-increment receipt with the real batch ID.
+Every explicit retrieval creates an independent batch. All batches must complete Evidence Gate and `memory_record_use` before the final user answer starts: retrieve → assess → close all batches → answer. If the stop callback finds omitted receipts, it first steers cleanup; after all receipts succeed, the answer step receives an instruction to restate the complete user answer and exposes no tools. Internal batch status must never replace the answer. Normal turns do not repeat answers. Recovery with no progress reports an error instead of steering indefinitely. The model passes its `batch_id` to `memory_assess`, then closes that same batch with `memory_record_use`. It passes the exact `evidence_refs` from that batch used in its answer, or `[]` when it used none. Selected Event evidence is reinforced once; an empty list writes a zero-increment receipt with the real batch ID.
 
 ### Agent-recorded memory
 
@@ -170,7 +170,9 @@ Open DSH Settings and select **StrataGate-AgentMemory**. The page provides:
 
 Events, graph facts, and source messages cannot be edited, deleted, or approved in the UI. The UI can manually expand a Block, import memory exported by another AI, and change the completed turns per Block or the global Block decay coefficient λ in Advanced Settings. When the Block size changes, the UI explains their relationship and suggests a λ that preserves the decay rate per conversation turn; the user decides whether to adopt it. Saved settings immediately apply to every existing workspace, become the defaults for future workspaces, and survive restarts. Existing sealed Blocks are never repartitioned.
 
-The primary Persistent Profile tab edits nine fixed fields in compact groups, one field at a time. It refreshes about every five seconds while visible, preserves an open draft, and prevents a stale same-field save from overwriting a concurrent change. The same installation-wide Profile is used by `memory_profile_update`, across sessions and namespaces. The preferred answer language applies only to the final answer; the independent visible reasoning language applies only to reasoning/thinking text exposed by the host UI when supported, never to hidden internal reasoning. An empty visible reasoning language adds no extra requirement. Each saved field takes effect on the next model call; empty fields are omitted. Profile values use Unicode code-point limits of 100/100/100/100/1000/1000/1500/1000/1200 characters, with a 6000-character total budget and a 4800-character maintenance trigger. The SQLite database records each Settings, tool, and maintenance change with its previous value and source. Maintenance runs when 24 hours have passed since the first nonempty write or the last successful run, or when a capacity threshold is reached; it sees only the current Profile and may compress wording without adding facts or semantically rewriting the four short fields. Event extraction and Graph projection never write Profile fields.
+The primary Persistent Profile tab shows eleven fixed fields in compact groups, one field at a time. An existing `homeCity` value adds a separate editable legacy row. It refreshes about every five seconds while visible, preserves an open draft, and prevents a stale same-field save from overwriting a concurrent change. The same installation-wide Profile is used by `memory_profile_update`, across sessions and namespaces. The preferred answer language applies only to the final answer; the independent visible reasoning language applies only to reasoning/thinking text exposed by the host UI when supported, never to hidden internal reasoning. An empty visible reasoning language adds no extra requirement. Each saved field takes effect on the next model call; empty fields are omitted. The stored Profile has twelve fields with Unicode code-point limits of 100/100/100/100/200/100/100/1000/1000/1500/1000/1200 characters, with a 6000-character total budget and a 4800-character maintenance trigger. The SQLite database records each Settings, tool, and maintenance change with its previous value and source. Maintenance runs when 24 hours have passed since the first nonempty write or the last successful run, or when a capacity threshold is reached; it sees only the current Profile and may compress wording without adding facts or semantically rewriting the seven short fields. Event extraction and Graph projection never write Profile fields.
+
+The Common addresses group has a usual/default address (`defaultLocation`, 200 characters) and current city (`currentCity`, 100 characters). A travel or business-trip city can be temporary while its saved value remains injected across sessions until the user updates or clears it; it does not expire automatically. Local tasks use an explicit task location first, otherwise current city when set, then default location. Existing `homeCity` (100 characters) retains its original residence meaning and remains editable when nonempty; it is never copied into current city. Updates retain the Profile explicit-request or proposal-and-consent rule. Old databases read missing fields as empty, using the existing field storage, revisions, and audit trail without a new database migration.
 
 The UI validates and previews pasted `stratagate.external-memory.v2` JSON before writing. Malformed input uses a model-backed recovery fallback whose candidates always require review. Exact duplicates are ignored deterministically; the configured model adjudicates other candidates against Top-K local Events as add, merge, supersede, conflict, or ignore. Analysis jobs persist per-candidate progress in SQLite, resume after the import page is reopened, and let users choose the action for low-confidence decisions. High-confidence decisions remain automatic, and a committed import can be undone as one batch. Common token and credential patterns are redacted in message content and structured tool traces before they leave the local server. The SQLite database remains the source of truth.
 

package/docs/DSH.zh-CN.md

@@ -87,7 +87,7 @@ DSH_HOME/stratagate/memory.db
 
 自动上下文只包含来自其他会话的精简 Event 与 fact 字段，并明确标注为历史背景而非指令。当前会话 Block 的证据会被排除，因为每个 Block 当前衰减层级的表示已存在于 DSH 原生历史中。构建自动上下文不会调用 `recordMemoryUse`，不会增加 `mentionCount`，也不会更新 `lastAdoptedTurn`。现有 `memory_*` 工具仍用于更深入、经过 Evidence Gate 的主动检索，也是触发采用强化的唯一入口。
 
-每次主动检索都会创建独立批次。模型先把该批次的 `batch_id` 传给 `memory_assess`，再用 `memory_record_use` 结算同一批次。模型需要传入回答中实际使用且属于该批次的 `evidence_refs`；若一条也没有使用，则传入 `[]`。被选中的 Event 证据会强化一次，空数组会写入一条包含真实批次 ID 的零强化回执。
+每次主动检索都会创建独立批次。所有批次必须在开始输出最终用户回答之前完成 Evidence Gate 与 `memory_record_use`：检索 → 评估 → 全部结算 → 最终回答。若停止回调发现漏关批次，它先要求补结算，全部完成后的回答步骤会收到重述完整用户答案的指令且不再提供工具；批次状态不能作为最终答案。无漏关批次时不补答。兜底连续没有进展时会报告错误，不会无限 steer。模型先把该批次的 `batch_id` 传给 `memory_assess`，再用 `memory_record_use` 结算同一批次。模型需要传入回答中实际使用且属于该批次的 `evidence_refs`；若一条也没有使用，则传入 `[]`。被选中的 Event 证据会强化一次，空数组会写入一条包含真实批次 ID 的零强化回执。
 
 ### Agent 主动记忆
 
@@ -102,7 +102,10 @@ DSH_HOME/stratagate/memory.db
 
 插件注册以下工具：
 
+记忆目录默认提供约 400 词元的导航。`memory_list_topics` 可分类分页或查询主题，`memory_expand_topic` 展开有来源的概览；这两个工具不生成证据批次，也不强化记忆。概览中的事实需用 `memory_search_events` 的 `topic_id` 参数查证，再走证据评估和采用流程。后台从已有事件小批量整理，失败或尚未整理时仍保留事件入口。详见[记忆目录与主题整合](MEMORY_TOPICS.zh-CN.md)。
+
 ```text
+memory_list_topics    memory_expand_topic
 memory_search_events   memory_expand_event
 memory_search_graph    memory_expand_graph_node
 memory_search_raw      memory_get_blocks
@@ -142,7 +145,9 @@ ID、`blockId`、角色、轮次和有界摘录。`narrative`、`quotes`、来
 
 界面不允许直接编辑、删除或批准 Event、图谱事实和来源消息。用户可以手动展开 Block、导入其他 AI 的记忆，以及在“高级设置”中修改每个 Block 包含的完整对话轮数或全局 Block 衰减系数 λ。修改轮数时，界面会解释两者关系并给出保持单位对话衰减速度的建议 λ，是否采用由用户决定。保存后设置立即应用到所有已有工作区，同时成为新工作区默认值，并在重启后保持；已封存 Block 不会重新切分。
 
-顶部“常驻画像”页面可编辑固定的九项字段。页面按身份与语言、交互偏好、关于用户、其他分组，默认紧凑显示；编辑时只展开一个字段。“默认回答语言”仅用于最终回复，“思考过程语言”仅用于宿主界面向用户展示的 reasoning/thinking 文本（若支持），两项互不推导；后者为空时不额外要求思考语言，也不控制隐藏的内部推理。页面可见时约每 5 秒读取最新画像，隐藏或离开时停止，并保留正在编辑的草稿。同一字段被其他来源修改时会提示冲突，保存不会覆盖新值。Settings 与 `memory_profile_update` 修改同一份安装级画像，跨会话、跨命名空间生效；保存后下一次模型调用立即看到新值，空字段不注入。字段按 Unicode 码点计数，上限依次为 100、100、100、100、1000、1000、1500、1000、1200 字符，总预算 6000 字符；总容量 4800 字符触发后台整理。SQLite 会记录 Settings、工具及后台整理的每次变更、旧值和来源。后台整理在首次写入非空画像或上次成功整理满 24 小时后，或达到容量阈值时执行；只读取当前画像，只压缩表达，不新增事实，也不语义改写四个短字段。Event 提取和 Graph 投影都不会写入画像。
+顶部“常驻画像”页面默认显示十一项字段；旧常驻城市有值时额外保留一项编辑入口。页面按身份与语言、交互偏好、常用地址、关于用户、其他分组，默认紧凑显示；编辑时只展开一个字段。“默认回答语言”仅用于最终回复，“思考过程语言”仅用于宿主界面向用户展示的 reasoning/thinking 文本（若支持），两项互不推导；后者为空时不额外要求思考语言，也不控制隐藏的内部推理。页面可见时约每 5 秒读取最新画像，隐藏或离开时停止，并保留正在编辑的草稿。同一字段被其他来源修改时会提示冲突，保存不会覆盖新值。Settings 与 `memory_profile_update` 修改同一份安装级画像，跨会话、跨命名空间生效；保存后下一次模型调用立即看到新值，空字段不注入。存储结构有十二项字段，按 Unicode 码点计数，上限依次为 100、100、100、100、200、100、100、1000、1000、1500、1000、1200 字符，总预算 6000 字符；总容量 4800 字符触发后台整理。SQLite 会记录 Settings、工具及后台整理的每次变更、旧值和来源。后台整理在首次写入非空画像或上次成功整理满 24 小时后，或达到容量阈值时执行；只读取当前画像，只压缩表达，不新增事实，也不语义改写七个短字段。Event 提取和 Graph 投影都不会写入画像。
+
+“常用地址”显示“常驻地址（未说明时默认地址）”（`defaultLocation`，200 字符）和“当前所在城市（临时）”（`currentCity`，100 字符），没有附加说明段落。当前城市可记录旅游、出差所在地；“临时”不限制保存时长，值会跨会话持续注入，直到用户修改或清空，不自动过期。本地任务先用明确指定的地点，否则优先当前城市，为空时再用常驻/默认地址。旧 `homeCity`（100 字符）保留原来的稳定常驻城市含义，有值时仍可编辑，不自动复制成当前城市。所有更新沿用明确修改请求或先提议再获确认的授权规则。旧数据库缺少字段时读取为空，沿用原字段存储、修订与审计机制，无需新的数据库迁移。
 
 当前界面会在写入前校验并预览粘贴的 `stratagate.external-memory.v2` JSON：不合格内容会进入模型兜底恢复，恢复候选全部需要人工确认。完全重复项会被确定性忽略，其余候选由当前模型结合 Top-K 本地 Event 判断新增、合并、取代、冲突或忽略。分析任务和逐条进度持久化到 SQLite，关闭并重新打开页面后会恢复进度；高置信度判断自动采用，低置信度项可由用户选择具体动作；提交后可按批次撤销。消息内容和结构化工具轨迹中的常见令牌及凭证格式，会在离开本地服务器前被脱敏。SQLite 数据库始终是唯一可信数据源。
 

package/docs/MEMORY_TOPICS.zh-CN.md

@@ -0,0 +1,49 @@
+# 记忆目录与主题整合
+
+本次实现两项能力：默认可见的记忆目录，以及按需展开的跨事件主题概览。经验提炼不在本次范围内。
+
+## 使用方式
+
+- 用户画像继续单独常驻。目录说明记过哪些主题，并提供稳定的主题编号。
+- 目录只用于导航；主题概览把已有事件整理为背景、进展、决定、变化和待确认问题，每段保留事件来源。
+- 一个 Topic 对应长期的大章节，例如“StrataGate”“求职与职业发展”。节是能持续容纳同类事件的长期类别，例如“缺陷排查与修复”“版本发布与安装”“架构与配置决策”；单个 bug、版本、日期、任务和处理状态留在节内总览与原事件，不独立成节。已有类别能容纳时复用原标题，同类不同状态或不同版本不再拆节。分类随章的实际内容归纳，不套全局固定表，不设硬节数上限；归类不改变任何事件事实。
+- 同一章内同名总览段落归为一个稳定的节，与段落类型无关。标题按全半角、大小写及空白规范化匹配；没有标题时使用类型名称归组。节的 `.0 总览` 按各段最早来源在章节中的位置排序并原样展示内容；同位置按最晚来源位置及稳定内容排序，各段来源仍独立保存在原始派生数据中；`.1~N` 展示这些来源的去重并集，按事件在章节成员列表中的位置分页。增加段落不新增同名节，不改写旧总览，不增加模型调用或数据库迁移。
+- 小节按其来源在章内成员列表中的最早位置排序，不跟随模型输出段落的先后顺序；同位置用稳定节编号排序。已有成员在前、新事件追加在后，因此新事件形成的新节置后，旧节不会因为新总览前置而改号。更新后的目录视图版本使旧编号及分页缓存失效。
+- 主模型按需打开主题，再通过现有事件、图谱或原文工具取证，继续使用现有证据检查与采用流程。
+- 现有自动召回继续工作，目录与概览不能成为唯一检索入口。
+
+工具按需要选择：`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 词元，并说明省略范围。
+- 主题目录按偏好与要求、决定与计划、工作与结果、交流与协作、其他经历分类；分类仅用于浏览，不改变主题内容和编号。完整目录每页最多 20 项。
+- 正式主题按创建时间从早到晚排列，新增主题追加；同一时刻仅以不可变的主题编号排序，改名不改变章序。注入目录、主题工具与界面共用这一顺序，待整理入口置后，展示章号不写入数据库。
+- Dashboard 只返回主题、节、总览段落及事件数量，不返回事件成员编号、全量标题或摘要；Bootstrap 失败详情也只传数量。完整成员关系保留在服务端。节编号由规范化标题派生，界面与分页共用同一聚合规则。展开节、待整理或失败详情时，用只读接口每页最多读取 9 条事件；数据版本变化时丢弃旧页。同类型但不同标题仍是不同节，同名段落合为一个节。
+- 目录默认预算约 400 词元，原相关记忆预算为 900 词元。超过目录预算时提供可展开的分类和分页入口，不能静默隐藏剩余主题。
+
+## 必须始终成立
+
+1. 事件和原文是证据底座，目录与概览不写回为新事件，不登记采用证据，不强化记忆。
+2. 主题编号独立于展示聚类成员；每条可见目录文字和概览都有可验证的来源依赖。
+3. 来源被遗忘、归档、撤销或修改后，旧派生文字先停止曝光，后台再重建。不能通过原始对话重新总结来复活已隐藏的事件。
+4. 模型结果提交前重新核对读取时的来源版本；过期任务不能覆盖新版主题。
+5. 主题只在当前命名空间可见；安装级画像不自动并入项目主题。
+6. 历史、计划、取消、争议和当前事实不能在整合时混为一谈；缺少信息保留为待确认问题。
+7. 升级、失败和重启不会修改或删除已有事件、图谱和原始对话；目录可独立重建。
+
+## 验收
+
+验证模糊查询发现主题、无图谱事件覆盖、按主题取证、增量整合与稳定编号、隐藏来源即时失效、过期提交拒绝、零采用强化、命名空间隔离、旧库升级、重启恢复、有限重试、输入和目录预算，以及后台失败时原搜索继续可用。测试只使用临时数据库与模拟模型。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratagate-dsh",
-  "version": "0.2.96",
+  "version": "0.3.0",
   "description": "Recent conversations stay vivid. Older ones fade into summaries, not oblivion. StrataGate gives DeepSeek Harness six-layer, time-decaying memory, while lasting events and relationships settle into a knowledge graph. Bring your memories from other AIs with you—no need to start over.",
   "type": "module",
   "main": "./dist/index.js",