stratagate-dsh 0.2.86 → 0.2.89

package/docs/DSH.md

@@ -89,6 +89,42 @@ Automatic context contains only compact Event and fact fields from other convers
 
 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.
 
+### Agent-recorded memory
+
+Choose by scope: `memory_profile_update` changes a global Persistent Profile field supplied to every future conversation without retrieval; `memory_remember` stores an Event surfaced when relevant, such as a project-specific preference or a past decision. A one-turn request needs neither. The word "remember" does not select a tool, and the same information should normally be stored in one place. An inferred Profile change still requires the consent specified by that tool.
+
+`memory_remember` lets the agent record facts proactively: context-specific user preferences or
+corrections, decisions, and durable project facts when they need to be recalled in relevant situations.
+Recordings enter the same long-term Event pipeline as conversation-derived memory, with
+two differences:
+
+- **Isolated storage.** Agent-recorded Events live in dedicated `agent_events` tables that
+  mirror the Event model but are physically separate from the passive conversation tables.
+  Their provenance cites the **real conversation messages** of the recording session — the
+  open-tail user/assistant messages when available, otherwise the latest sealed Block of
+  that thread — so no fabricated user message is ever created. Only when a session has no
+  ingested messages at all does a synthetic `agent-memory:` provenance Block get created.
+- **Pre-write resolution.** Before writing, StrataGate searches existing memory (both pools)
+  for duplicates and conflicts. Exact and near duplicates reinforce the existing card instead
+  of writing a new one. Ambiguous lexical overlap triggers one synchronous model adjudication
+  reusing the external-memory decision contract: `ADD`, `MERGE`, `SUPERSEDE` (high confidence
+  only — low-confidence merge/supersede is downgraded to a non-destructive conflict mark),
+  `CONFLICT` (symmetric back-links), or `IGNORE`. The tool result reports `action`, `gate`,
+  and `reason`. Facts with no meaningful overlap write directly without a model call.
+
+Everything else is ordinary Event behavior: agent recordings project into the Knowledge
+Graph, persist across sessions, decay and reinforce through the same turn-based lifecycle
+(`memory_assess` → `memory_record_use`), and can be forgotten through that lifecycle.
+Retrieval gives each pool its own top-k lane — the passive pool and the agent pool are
+ranked independently, then fused with weighted RRF, so neither pool can crowd the other
+out of the result window. The agent lane's share is the configurable
+`agentMemoryRetrievalWeight` (default `1` = equal footing; `0` = recordings stay stored but
+never surface; higher values boost agent recordings), and cards carry
+`source: 'agent-recorded'`. The memory dashboard lists them under
+`/api/stratagate/agent-memories` (query parameters `session` and `includeArchived=true`).
+The feature can be disabled entirely with `agentMemoryEnabled: false`, which also
+unregisters the tool.
+
 The plugin registers these tools:
 
 ```text
@@ -96,7 +132,7 @@ memory_search_events   memory_expand_event
 memory_search_graph    memory_expand_graph_node
 memory_search_raw      memory_get_blocks
 memory_expand_block    memory_assess
-memory_record_use
+memory_record_use      memory_remember
 memory_profile_update
 ```
 
@@ -149,6 +185,8 @@ config:
   blockTurnSize: 6
   blockDecayLambda: 0.3
   ingestSubagents: false
+  agentMemoryEnabled: true
+  agentMemoryRetrievalWeight: 1
   maxOutputTokens: 10000
   structuredTaskTimeoutMs: 120000
   structuredReasoningEffort: auto # auto | force-off
@@ -165,6 +203,8 @@ config:
 
 `blockDecayLambda` controls decay by the distance between a Block's pointer anchor and the latest sealed Block in the same DSH session. It defaults to `0.3`. Smaller values decay more slowly; values above `0.4` are not recommended. Turns in the open tail do not increase Block age.
 
+`agentMemoryEnabled` (default `true`) controls agent-recorded memory (see above); disabling it also unregisters `memory_remember`. `agentMemoryRetrievalWeight` (default `1`, range `0`–`5`) sets the agent lane's share in merged retrieval. Recordings are stored in the same SQLite database as the rest of StrataGate data.
+
 If `provider` and `model` are omitted, memory processing uses the session's latest request route, then the DSH default model as fallback. They must be configured as a pair.
 
 ## Privacy and failure behavior
@@ -175,7 +215,7 @@ For diagnostics, the five most recent successful memory-model responses are reta
 
 ## Compatibility and permissions
 
-Release gates exercise the complete DSH `0.1.2-rc.1` family, `@deepseek-ai/dsh@0.1.5-rc.1`, `@deepseek-ai/dsh@0.1.6-alpha.1`, and `@deepseek-ai/dsh@0.1.7-rc.1` on Node `24`, on both Linux and Windows. The 0.1.5 CLI's real dependency tree resolves its internal DSH packages to `0.1.5-rc.2`; the 0.1.6 and 0.1.7 CLIs resolve the tested internal DSH and Session Format packages to their respective versions. The 0.1.7 host also supplies Cordis `4.0.4` and Schemastery `3.18.4`. The plugin declares these packages as optional, exact-version peers so the host supplies one coherent runtime instead of npm installing a second copy. Other `0.1.x` versions are not implicitly supported.
+Release gates exercise the complete DSH `0.1.2-rc.1` family, `@deepseek-ai/dsh@0.1.5-rc.1`, `@deepseek-ai/dsh@0.1.6-alpha.1`, `@deepseek-ai/dsh@0.1.7-rc.1`, and `@deepseek-ai/dsh@0.1.7-rc.2` on Node `24`, on both Linux and Windows. The 0.1.5 CLI's real dependency tree resolves its internal DSH packages to `0.1.5-rc.2`; the 0.1.6 and 0.1.7 CLIs resolve the tested internal DSH and Session Format packages to their respective versions. The 0.1.7 host also supplies Cordis `4.0.4` and Schemastery `3.18.4`. Optional peers for the DSH `0.1.7` packages now accept `>=0.1.7-rc.1 <0.1.8-0`. Startup still requires one coherent DSH internal version and limits Cordis and Schemastery to compatible patch lines. Later `0.1.7` releases can install without a plugin update, but the release gate only tests the versions listed above; compatibility checks remain advisable after a host upgrade. DSH `0.1.8` is excluded.
 
 DSH core packages are host-provided optional peers. After upgrading a profile that once installed those peers locally, run `dsh plugin --profile <name> exec stratagate-dsh-repair` before starting it. The command moves only the known DSH runtime packages into `.stratagate-runtime-backups` inside that profile and writes a recovery receipt; it does not delete them or touch session data. At startup, a bootstrap resolver also forces StrataGate's own imports through the installation-owned module fallback, then verifies the resolved DSH core family and stops with an actionable error for an unknown host family. On DSH `0.1.5` through `0.1.7`, v0 sessions containing the retired `stratagate/memory-citations` event are copied to a validated v1 generation before the host continues its migration chain. The original v0 log is never modified; a `stratagate-legacy-citations-v1.json` receipt records source/target hashes and recovery instructions.
 

package/docs/DSH.zh-CN.md

@@ -89,6 +89,17 @@ DSH_HOME/stratagate/memory.db
 
 每次主动检索都会创建独立批次。模型先把该批次的 `batch_id` 传给 `memory_assess`，再用 `memory_record_use` 结算同一批次。模型需要传入回答中实际使用且属于该批次的 `evidence_refs`；若一条也没有使用，则传入 `[]`。被选中的 Event 证据会强化一次，空数组会写入一条包含真实批次 ID 的零强化回执。
 
+### Agent 主动记忆
+
+选用写入工具时看信息的适用范围：`memory_profile_update` 修改每次对话都自动提供的全局常驻画像字段；`memory_remember` 保存只需在相关情境中想起的 Event，例如项目专属偏好和已做出的决定；仅本次有效的要求不写入记忆。“记住”一词本身不决定用哪个工具，同一信息默认只写入一处。主动提出修改画像仍须遵守该工具的“同意”规则。
+
+`memory_remember` 让 agent 主动记录值得记忆的事实：适用于特定情境的用户偏好、事实纠正、决定和持久的项目事实。记录会进入与对话派生记忆相同的长期 Event 管线，但有两点不同：
+
+- **隔离存储。** agent 记录的 Event 存放在专属的 `agent_events` 隔离表中，数据模型与普通 Event 完全一致，但与被动对话表物理分离。其溯源直接引用**记录会话中的真实对话消息** —— 优先取 open tail 中的 user/assistant 消息，其次取该会话最新封存 Block 的消息 —— 绝不生成虚构的 user 消息。仅当会话中没有任何已摄取消息时，才会创建合成的 `agent-memory:` 溯源 Block。
+- **写入前消解。** 写入前，StrataGate 会先在两个池中检索重复与冲突：精确或高度近似的重复会强化既有卡片而不新写；词面重叠模糊的记录会触发一次同步模型仲裁，复用外部记忆导入的决策契约 —— `ADD`、`MERGE`、`SUPERSEDE`（仅高置信度；低置信度的合并/取代会降级为非破坏性的冲突标记）、`CONFLICT`（双向回链）或 `IGNORE`。工具结果会回报 `action`、`gate` 与 `reason`。与既有记忆没有实质重叠的事实直接写入，不调用模型。
+
+其余行为与普通 Event 一致：agent 记录会投影进 Knowledge Graph，跨会话持久保存，走同样的 turn 衰减与引用强化生命周期（`memory_assess` → `memory_record_use`），也可以通过该生命周期遗忘。检索为两个池各开一条独立的 top-k 通道 —— 被动池与 agent 池分别独立排序，再按加权 RRF 融合，任何一方都无法把另一方挤出结果窗口。agent 通道的占比由 `agentMemoryRetrievalWeight` 配置（默认 `1` = 平权；`0` = 记录保留但不再浮现；更大值提升 agent 记录的排序权重），卡片带 `source: 'agent-recorded'` 标记。记忆面板通过 `/api/stratagate/agent-memories`（查询参数 `session` 与 `includeArchived=true`）展示这些记录。可用 `agentMemoryEnabled: false` 整体关闭该功能，同时注销对应工具。
+
 插件注册以下工具：
 
 ```text
@@ -96,7 +107,7 @@ memory_search_events   memory_expand_event
 memory_search_graph    memory_expand_graph_node
 memory_search_raw      memory_get_blocks
 memory_expand_block    memory_assess
-memory_record_use
+memory_record_use      memory_remember
 memory_profile_update
 ```
 
@@ -146,6 +157,8 @@ config:
   blockTurnSize: 6
   blockDecayLambda: 0.3
   ingestSubagents: false
+  agentMemoryEnabled: true
+  agentMemoryRetrievalWeight: 1
   maxOutputTokens: 10000
   structuredTaskTimeoutMs: 120000
   structuredReasoningEffort: auto # auto | force-off
@@ -162,6 +175,8 @@ config:
 
 `blockDecayLambda` 按当前 Block 锚点与同一 DSH 会话中最新已封存 Block 的距离控制衰减。默认值为 `0.3`；数字越小衰减越慢，不建议大于 `0.4`。open tail 中尚未封存的轮次不会增加 Block age。
 
+`agentMemoryEnabled`（默认 `true`）控制 Agent 主动记忆（见上文）；关闭后同时注销 `memory_remember`。`agentMemoryRetrievalWeight`（默认 `1`，范围 `0`–`5`）设置 agent 通道在融合检索中的占比。记录与其他 StrataGate 数据一样保存在同一个 SQLite 数据库中。
+
 如果省略 `provider` 和 `model`，记忆处理会优先使用会话最近一次请求的路由，并以 DSH 默认模型作为后备。这两个配置项必须同时设置。
 
 ## 隐私与故障处理
@@ -172,7 +187,7 @@ config:
 
 ## 兼容性与权限
 
-发布门禁会在 Node `24`、Linux 和 Windows 上测试完整的 DSH `0.1.2-rc.1` 依赖族，以及 `@deepseek-ai/dsh@0.1.5-rc.1`、`@deepseek-ai/dsh@0.1.6-alpha.1` 和 `@deepseek-ai/dsh@0.1.7-rc.1`。0.1.5 CLI 的真实依赖树会把内部 DSH 包解析为 `0.1.5-rc.2`；0.1.6 和 0.1.7 CLI 的受测内部 DSH 与 Session Format 包分别解析为对应版本。0.1.7 宿主还提供 Cordis `4.0.4` 和 Schemastery `3.18.4`。插件将这些包声明为可选且精确版本的 peer，由宿主提供一套一致的运行时，避免 npm 在插件目录再安装第二套核心包；不会笼统承诺其他 `0.1.x` 版本。
+发布门禁会在 Node `24`、Linux 和 Windows 上测试完整的 DSH `0.1.2-rc.1` 依赖族，以及 `@deepseek-ai/dsh@0.1.5-rc.1`、`@deepseek-ai/dsh@0.1.6-alpha.1`、`@deepseek-ai/dsh@0.1.7-rc.1` 和 `@deepseek-ai/dsh@0.1.7-rc.2`。0.1.5 CLI 的真实依赖树会把内部 DSH 包解析为 `0.1.5-rc.2`；0.1.6 和 0.1.7 CLI 的受测内部 DSH 与 Session Format 包分别解析为对应版本。0.1.7 宿主还提供 Cordis `4.0.4` 和 Schemastery `3.18.4`。插件将 DSH `0.1.7` 内部包的可选 peer 范围放宽到 `>=0.1.7-rc.1 <0.1.8-0`，启动时仍要求它们全部来自同一版本，并限制 Cordis 与 Schemastery 在已知的小版本补丁范围内。未来 `0.1.7` 更新可直接安装，但发布门禁只覆盖上面列出的版本；更新后仍应运行兼容性检查。不包含 `0.1.8`。
 
 DSH 核心包现在都是由宿主提供的可选 peer。若某个 profile 曾在本地安装这些 peer，升级后、启动前运行 `dsh plugin --profile <名称> exec stratagate-dsh-repair`。该命令只会把已知 DSH 运行时包移动到 profile 内的 `.stratagate-runtime-backups` 并写入恢复收据，不会删除包或触碰会话数据。启动时 bootstrap 还会把 StrataGate 自身的 DSH 导入定向到宿主维护的共享模块回退目录，再检查实际解析出的 DSH 核心族；未知宿主会立即给出明确错误并停止，而不是让正文区域空白。对于 DSH `0.1.5` 至 `0.1.7`，含已废弃 `stratagate/memory-citations` 事件的 v0 会话会先复制成经过校验的 v1 代际，再由宿主继续其迁移链；原始 v0 日志不会被修改，并写入 `stratagate-legacy-citations-v1.json` 记录源/目标哈希和恢复说明。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratagate-dsh",
-  "version": "0.2.86",
+  "version": "0.2.89",
   "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",
@@ -118,7 +118,8 @@
         "0.1.2-rc.1",
         "0.1.5-rc.1",
         "0.1.6-alpha.1",
-        "0.1.7-rc.1"
+        "0.1.7-rc.1",
+        "0.1.7-rc.2"
       ]
     },
     "permissions": [
@@ -151,19 +152,19 @@
     "node": "^22.19.0 || >=24.0.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "4.0.2 || 4.0.4",
-    "@deepseek-ai/dsh-agent-default-model": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-llm": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-native-command": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-format": "0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-format-catalog": "0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-format-v0-to-v1": "0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-settings": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.7-rc.1",
-    "@deepseek-ai/schemastery": "3.18.2 || 3.18.4"
+    "@deepseek-ai/cordis": "4.0.2 || ~4.0.4",
+    "@deepseek-ai/dsh-agent-default-model": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-native-command": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-session-format": "0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-session-format-catalog": "0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-session-format-v0-to-v1": "0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-settings": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/schemastery": "3.18.2 || ~3.18.4"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -208,18 +209,18 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-agent-default-model": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-native-command": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-format": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-format-catalog": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-format-v0-to-v1": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-settings": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.1",
+    "@deepseek-ai/dsh": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent-default-model": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-native-command": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-format": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-format-catalog": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-format-v0-to-v1": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
     "@deepseek-ai/schemastery": "3.18.4",
     "@types/node": "^22.0.0",
     "cytoscape": "^3.34.1",