stratagate-dsh 0.2.60 → 0.2.61

package/docs/ARCHITECTURE.md

@@ -48,20 +48,20 @@ A completed user/assistant pair is one turn. The default block boundary is 12 co
 
 Hosts may attach a `threadId` to each turn. Open tails, Block boundaries, neighboring extraction context, turn ranges, and decay pointers are then isolated by thread. Persisted Blocks remain available as provenance for long-term cards, while host integrations must inject only the active thread's short-term Block context.
 
-When the boundary is reached:
-
-1. One atomic sealing transaction moves the source messages into permanent L5 and writes deterministic L4 and L3.
-2. The sealed Block is marked model-pending. It is provenance, but it is excluded from decay and cannot replace native conversation history.
-3. A background summarizer produces and validates L0-L2 plus a conservative `shouldExtract` decision.
-4. Event extraction completes with either validated Events or an explicit valid empty result.
-5. Only then is the Block marked ready: its pointer starts at L5, it may replace native history, and it decays toward L0 as newer ready Blocks enter the same thread.
+When the boundary is reached:
+
+1. One atomic sealing transaction moves the source messages into permanent L5 and writes deterministic L4 and L3.
+2. The sealed Block is marked model-pending. It is provenance, but it is excluded from decay and cannot replace native conversation history.
+3. A background summarizer produces and validates L0-L2 plus a conservative `shouldExtract` decision.
+4. Event extraction completes with either validated Events or an explicit valid empty result.
+5. Only then is the Block marked ready: its pointer starts at L5, it may replace native history, and it decays toward L0 as newer ready Blocks enter the same thread.
 
 The block weight is:
 
 ```text
 w(age) = exp(-lambda_block * age)
 
-age = latest ready Block position - pointer anchor Block position
+age = latest ready Block position - pointer anchor Block position
 lambda_block = 0.30 by default
 ```
 
@@ -78,13 +78,13 @@ L3 may remove only:
 
 Short repeated natural-language messages are retained. L3 never performs semantic paraphrasing.
 
-## Event extraction
-
-After L0-L2 validates, a candidate Block is extracted independently; a later Block is not required. The extractor receives:
+## Event extraction
+
+After L0-L2 validates, a candidate Block is extracted independently; a later Block is not required. The extractor receives:
 
 - target block `N`, including its L5 source and legal evidence IDs;
 - previous block `N-1` L2 keypoints for context, if it exists;
-- the nearest available later ready Block's L2 keypoints for context, if one exists;
+- the nearest available later ready Block's L2 keypoints for context, if one exists;
 - a compact timeline of existing event IDs, titles, and temporal fields.
 
 The target is the only legal source of new facts and quotations. Neighbor blocks are context-only and must not contribute events or source references. Source message IDs are checked against the target block. The reference implementation falls back to all target messages when an extractor returns no valid source ID; stricter adapters may reject the card instead.
@@ -144,12 +144,12 @@ Applications that manage their own model loop may use `claimNextElementProjectio
 
 ## Hybrid retrieval
 
-Event and fact-level element search use two inspectable ranking sources:
-
-1. BM25 over field-weighted lexical tokens, including overlapping Han bigrams;
-2. structured rankings from fields such as participant, event type, time range, element name, and element type.
-
-Reciprocal-rank fusion combines the available rankings. A non-empty query with no lexical or structured match returns an empty result rather than all candidates. Element search returns the matched fact plus its element ID, validity interval, and event provenance; callers expand the full element card only when needed. The reference path does not use embeddings or vector similarity.
+Event and fact-level element search use two inspectable ranking sources:
+
+1. BM25 over field-weighted lexical tokens, including overlapping Han bigrams;
+2. structured rankings from fields such as participant, event type, time range, element name, and element type.
+
+Reciprocal-rank fusion combines the available rankings. A non-empty query with no lexical or structured match returns an empty result rather than all candidates. Element search returns the matched fact plus its element ID, validity interval, and event provenance; callers expand the full element card only when needed. The reference path does not use embeddings or vector similarity.
 
 Integration tool responses intentionally expose compact search cards. They retain stable IDs, summaries,
 timestamps, and evidence references while leaving narrative/quotes/source-message lists and full graph
@@ -220,19 +220,19 @@ If the retrieval budget ends without sufficient evidence, the caller should pass
 
 Every namespace has a monotonically increasing revision. A write supplies the revision it loaded; SQLite commits the new revision and all related rows in one immediate transaction. A stale process receives `StorageConflictError` rather than overwriting newer state.
 
-External model calls are never made inside a database transaction:
-
-1. a completed raw turn is committed immediately;
-2. every complete Block is sealed atomically with real L3-L5 before any model call;
-3. summarization first claims a persisted job, runs outside the transaction, and commits validated L0-L2 or a failed job with bounded retry metadata;
-4. extraction first commits a running job, calls the extractor, then atomically commits either the event cards, a valid empty result, or a failed job state;
-5. element projection follows the same claim/call/complete boundary after its source events are durable;
-6. failed model jobs retry at most three total attempts with exponential backoff; completed empty extraction is terminal and is not retried.
+External model calls are never made inside a database transaction:
+
+1. a completed raw turn is committed immediately;
+2. every complete Block is sealed atomically with real L3-L5 before any model call;
+3. summarization first claims a persisted job, runs outside the transaction, and commits validated L0-L2 or a failed job with bounded retry metadata;
+4. extraction first commits a running job, calls the extractor, then atomically commits either the event cards, a valid empty result, or a failed job state;
+5. element projection follows the same claim/call/complete boundary after its source events are durable;
+6. failed model jobs retry at most three total attempts with exponential backoff; completed empty extraction is terminal and is not retried.
 
 The adapter preserves these invariants:
 
-- blocks and L5 messages are append-only, including when every derived task fails;
-- model-pending Blocks are excluded from decay and native-history replacement;
+- blocks and L5 messages are append-only, including when every derived task fails;
+- model-pending Blocks are excluded from decay and native-history replacement;
 - card provenance references an existing source block and message set;
 - search hits do not increment adoption state;
 - supersession retains the old event;
@@ -241,4 +241,4 @@ The adapter preserves these invariants:
 - forget is reversible unless an application explicitly implements irreversible deletion;
 - usage receipts are idempotent for one answer turn through a unique `receiptId`.
 
-SQLite schema v10 includes durable external-memory import jobs and per-candidate progress, in addition to the normalized Block processing state, summary/extraction retry jobs, graph, element, provenance, receipt, decay-anchor, and lift-source data introduced earlier. Opening a schema-v1 through v9 database migrates it in one transaction and preserves existing namespaces, Blocks, Events, jobs, and receipts. Existing pre-v9 Blocks are treated as ready because their persisted L0-L5 layers were already accepted by the older engine. Schema-v5 turn anchors are converted to per-thread Block positions; schema-v6 lift timestamps retain an unknown legacy source. Pre-v5 Blocks retain no inferred thread ownership, so they remain archival provenance without being attached to a new session. SQLite uses WAL, foreign keys, and per-namespace optimistic concurrency. It does not provide encryption at rest. Search still uses the reference in-memory ranking after hydration, so enabling persistence does not silently change retrieval semantics. Database-native lexical/vector indexes and a Postgres implementation remain separate future work.
+SQLite schema v10 includes durable external-memory import jobs and per-candidate progress, in addition to the normalized Block processing state, summary/extraction retry jobs, graph, element, provenance, receipt, decay-anchor, and lift-source data introduced earlier. Opening a schema-v1 through v9 database migrates it in one transaction and preserves existing namespaces, Blocks, Events, jobs, and receipts. Existing pre-v9 Blocks are treated as ready because their persisted L0-L5 layers were already accepted by the older engine. Schema-v5 turn anchors are converted to per-thread Block positions; schema-v6 lift timestamps retain an unknown legacy source. Pre-v5 Blocks retain no inferred thread ownership, so they remain archival provenance without being attached to a new session. SQLite uses WAL, foreign keys, and per-namespace optimistic concurrency. It does not provide encryption at rest. Search still uses the reference in-memory ranking after hydration, so enabling persistence does not silently change retrieval semantics. Database-native lexical/vector indexes and a Postgres implementation remain separate future work.

package/docs/DSH.md

@@ -1,6 +1,6 @@
 # StrataGate for DeepSeek Harness
 
-[English](../README.md) · [简体中文](DSH.zh-CN.md)
+[English](../README.md) · [简体中文](DSH.zh-CN.md)
 
 Automatic, local-first cross-session memory for DeepSeek Harness. StrataGate remembers user preferences, project decisions, completed conversations, and tool results, then checks recalled evidence and can expand it back to the original messages before the agent answers. No separate memory server is required.
 
@@ -10,11 +10,11 @@ The plugin adapts DSH session events to the existing StrataGate memory engine; i
 
 ### Knowledge graph and event timeline
 
-![StrataGate knowledge graph and event timeline view](assets/stratagate-knowledge-graph.png)
+![StrataGate knowledge graph and event timeline view](assets/stratagate-knowledge-graph.png)
 
 ### Layered short-term memory
 
-![StrataGate layered short-term memory view](assets/stratagate-short-term-memory.png)
+![StrataGate layered short-term memory view](assets/stratagate-short-term-memory.png)
 
 ## How it is designed
 
@@ -80,7 +80,7 @@ Removing the plugin does not delete that database.
 - Subagent turns are not ingested by default; subagents in the same project can still read project memory.
 - Each DSH turn has a durable ingestion receipt, so replay or retry cannot store it twice.
 - StrataGate performs Block summarization, Event extraction, versioned Knowledge Graph projection, search, Evidence Gate, and use-only reinforcement.
-- When a Block reaches its boundary, StrataGate first seals durable L3-L5 without touching the DSH surface. Only after validated L0-L2 and Event processing make the Block ready does the plugin use native surface `replace`; pending or failed Blocks keep their original conversation messages. Later decay, manual lift, or λ changes update only ready checkpoints. Unsealed open-tail messages and complete tool-call/result chains remain native DSH messages.
+- When a Block reaches its boundary, StrataGate first seals durable L3-L5 without touching the DSH surface. Only after validated L0-L2 and Event processing make the Block ready does the plugin use native surface `replace`; pending or failed Blocks keep their original conversation messages. Later decay, manual lift, or λ changes update only ready checkpoints. Unsealed open-tail messages and complete tool-call/result chains remain native DSH messages.
 - Before every main-model call, dynamic system context injects only up to four project-scoped activated Events and four active Graph nodes. It never serializes the current conversation, open tail, sealed Blocks, or tool calls into that prompt.
 
 Activated memory uses the current human message plus the latest two open-tail turns from the current session as its query. Existing BM25 search remains the lexical relevance gate; pinned and safety memory are the only exceptions. Existing memory weights provide a second ranking, and RRF fuses the relevance and weight rankings. The activated section has a fixed budget of about 900 tokens, so it does not grow with the database.
@@ -131,9 +131,9 @@ Open DSH Settings and select **StrataGate-AgentMemory**. The page provides:
 - manual Block expansion and a two-step external-memory import flow;
 - a Usage Audit chain from a recorded answer turn, through the Evidence Gate verdict and selected memories, back to source messages.
 
-Events, graph facts, and source messages cannot be edited, deleted, or approved in the UI. The UI can still change memory state in three explicit ways: manually expand a Block, import memory exported by another AI, and use Advanced Settings to change the completed turns per Block or the global Block decay coefficient λ. 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 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.
+Events, graph facts, and source messages cannot be edited, deleted, or approved in the UI. The UI can still change memory state in three explicit ways: manually expand a Block, import memory exported by another AI, and use Advanced Settings to change the completed turns per Block or the global Block decay coefficient λ. 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 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.
 
 ## Configuration
 
@@ -145,13 +145,12 @@ config:
   globalNamespace: global
   blockTurnSize: 6
   blockDecayLambda: 0.3
-  ingestSubagents: false
-  maxOutputTokens: 10000
-  structuredTaskTimeoutMs: 120000
-  structuredReasoningEffort: auto # auto | force-off
-  # Optional: use a dedicated model for memory processing.
+  ingestSubagents: false
+  maxOutputTokens: 10000
+  structuredReasoningEffort: auto # auto | force-off
+  # Optional: use a dedicated model for memory processing.
   # provider: deepseek
-  # model: deepseek-chat
+  # model: deepseek-chat
 ```
 
 `blockTurnSize` and `blockDecayLambda` are initial fallbacks. Once changed in **Advanced Settings**, persisted UI values take precedence. λ defaults to `0.3`; smaller values forget more slowly and consume more tokens, and values above `0.4` are not recommended.
@@ -172,7 +171,7 @@ For diagnostics, the five most recent successful memory-model responses are reta
 
 ## Compatibility and permissions
 
-Release gates exercise DSH `0.1.2-rc.1` on Node `24`, plus the core package on Node `22.19` and `24`. The published peer range accepts compatible DSH releases from `0.1.2-rc.1` up to, but not including, `0.2.0`.
+Release gates exercise DSH `0.1.2-rc.1` on Node `24`, plus the core package on Node `22.19` and `24`. The published peer range accepts compatible DSH releases from `0.1.2-rc.1` up to, but not including, `0.2.0`.
 
 The package declares local filesystem read/write and Harness tool registration. It does not request direct network, subprocess, shell, Python, or credential access. Model calls still flow through DSH's existing LLM service.
 

package/docs/DSH.zh-CN.md

@@ -1,6 +1,6 @@
 # StrataGate for DeepSeek Harness
 
-[English](DSH.md) · [简体中文](../README.zh-CN.md)
+[English](DSH.md) · [简体中文](../README.zh-CN.md)
 
 面向 DeepSeek Harness 的自动、本地优先跨会话记忆。StrataGate 能够记住用户偏好、项目决策、已完成的对话和工具结果；Agent 回答前会检查找回的证据，并可将其展开追溯到原始消息。无需单独部署记忆服务器。
 
@@ -80,7 +80,7 @@ DSH_HOME/stratagate/memory.db
 - 默认不保存子 Agent 的对话轮次；同一项目中的子 Agent 仍然可以读取项目记忆。
 - 每个 DSH 对话轮次都有持久化的写入回执，因此重放或重试不会导致重复保存。
 - StrataGate 会执行 Block 摘要、Event 提取、版本化 Knowledge Graph 投影、搜索、Evidence Gate（证据门控）以及仅在使用后触发的强化。
-- Block 到达边界时，StrataGate 先持久化真实的 L3–L5，不修改 DSH surface。只有 L0–L2 校验通过且 Event 处理完成、Block 进入可衰减状态后，插件才使用原生 surface `replace`；待处理或失败的 Block 始终保留原始会话消息。后续衰减、手动提升或 λ 调整也只更新已就绪 checkpoint。尚未封存的 open tail 与完整工具调用/结果链继续作为 DSH 原生消息保留。
+- Block 到达边界时，StrataGate 先持久化真实的 L3–L5，不修改 DSH surface。只有 L0–L2 校验通过且 Event 处理完成、Block 进入可衰减状态后，插件才使用原生 surface `replace`；待处理或失败的 Block 始终保留原始会话消息。后续衰减、手动提升或 λ 调整也只更新已就绪 checkpoint。尚未封存的 open tail 与完整工具调用/结果链继续作为 DSH 原生消息保留。
 - 每次主模型调用前，动态系统上下文只注入最多 4 条项目级激活 Event 和 4 个 active Graph Node，不再序列化 Current conversation、open tail、已封 Block 或 tool calls。
 
 激活查询由当前人类消息和当前会话 open tail 的最近两个 turn 组成。现有 BM25 搜索继续作为词面相关性门槛，只有 pinned 和 safety 记忆可以例外进入候选；现有记忆权重提供第二路排序，再由 RRF 融合相关性与权重排序。激活区固定使用约 900 tokens 的预算，不会随数据库增大而增长。
@@ -128,9 +128,9 @@ ID、`blockId`、角色、轮次和有界摘录。`narrative`、`quotes`、来
 - 手动展开 Block，以及分两步导入其他 AI 的记忆；
 - Usage Audit（使用审计）链路：从已记录的回答轮次出发，经由 Evidence Gate 的判断与选中的记忆，追溯到来源消息。
 
-界面不允许直接编辑、删除或批准 Event、图谱事实和来源消息，但可以通过三种明确操作改变记忆状态：手动展开 Block、导入其他 AI 的记忆，以及在“高级设置”中修改每个 Block 包含的完整对话轮数或全局 Block 衰减系数 λ。修改轮数时，界面会解释两者关系并给出保持单位对话衰减速度的建议 λ，是否采用由用户决定。保存后设置立即应用到所有已有工作区，同时成为新工作区默认值，并在重启后保持；已封存 Block 不会重新切分。
-
-当前界面会在写入前校验并预览粘贴的 `stratagate.external-memory.v2` JSON：不合格内容会进入模型兜底恢复，恢复候选全部需要人工确认。完全重复项会被确定性忽略，其余候选由当前模型结合 Top-K 本地 Event 判断新增、合并、取代、冲突或忽略。分析任务和逐条进度持久化到 SQLite，关闭并重新打开页面后会恢复进度；高置信度判断自动采用，低置信度项可由用户选择具体动作；提交后可按批次撤销。消息内容和结构化工具轨迹中的常见令牌及凭证格式，会在离开本地服务器前被脱敏。SQLite 数据库始终是唯一可信数据源。
+界面不允许直接编辑、删除或批准 Event、图谱事实和来源消息，但可以通过三种明确操作改变记忆状态：手动展开 Block、导入其他 AI 的记忆，以及在“高级设置”中修改每个 Block 包含的完整对话轮数或全局 Block 衰减系数 λ。修改轮数时，界面会解释两者关系并给出保持单位对话衰减速度的建议 λ，是否采用由用户决定。保存后设置立即应用到所有已有工作区，同时成为新工作区默认值，并在重启后保持；已封存 Block 不会重新切分。
+
+当前界面会在写入前校验并预览粘贴的 `stratagate.external-memory.v2` JSON：不合格内容会进入模型兜底恢复，恢复候选全部需要人工确认。完全重复项会被确定性忽略，其余候选由当前模型结合 Top-K 本地 Event 判断新增、合并、取代、冲突或忽略。分析任务和逐条进度持久化到 SQLite，关闭并重新打开页面后会恢复进度；高置信度判断自动采用，低置信度项可由用户选择具体动作；提交后可按批次撤销。消息内容和结构化工具轨迹中的常见令牌及凭证格式，会在离开本地服务器前被脱敏。SQLite 数据库始终是唯一可信数据源。
 
 ## 配置
 
@@ -142,13 +142,12 @@ config:
   globalNamespace: global
   blockTurnSize: 6
   blockDecayLambda: 0.3
-  ingestSubagents: false
-  maxOutputTokens: 10000
-  structuredTaskTimeoutMs: 120000
-  structuredReasoningEffort: auto # auto | force-off
-  # 可选：为记忆处理指定专用模型。
+  ingestSubagents: false
+  maxOutputTokens: 10000
+  structuredReasoningEffort: auto # auto | force-off
+  # 可选：为记忆处理指定专用模型。
   # provider: deepseek
-  # model: deepseek-chat
+  # model: deepseek-chat
 ```
 
 配置文件中的 `blockTurnSize` 和 `blockDecayLambda` 是初始后备值；一旦在“高级设置”中修改，持久化的界面值优先生效。λ 默认值为 `0.3`；数字越小，记忆遗忘越慢、消耗 token 越多，不建议大于 `0.4`。
@@ -169,7 +168,7 @@ config:
 
 ## 兼容性与权限
 
-发布门禁会在 Node `24` 上测试 DSH `0.1.2-rc.1`，并在 Node `22.19` 和 `24` 上测试核心包。发布包声明的 peer 版本范围接受从 `0.1.2-rc.1` 开始、低于 `0.2.0` 的兼容 DSH 版本。
+发布门禁会在 Node `24` 上测试 DSH `0.1.2-rc.1`，并在 Node `22.19` 和 `24` 上测试核心包。发布包声明的 peer 版本范围接受从 `0.1.2-rc.1` 开始、低于 `0.2.0` 的兼容 DSH 版本。
 
 该包申请本地文件系统读写权限和 Harness 工具注册权限，不申请直接网络访问、子进程、Shell、Python 或凭证访问权限。模型调用仍通过 DSH 现有的 LLM 服务进行。
 

package/docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md

@@ -1,54 +1,54 @@
-# 外部 AI 记忆导入
-
-StrataGate 提供 `importExternalMemory()` 编排外部记忆迁移：
-
-```text
-外部 AI JSON
-    ↓ extractor（候选 Event）
-每个候选 Event → searchEvents()（确定性 BM25，Top-K）
-    ↓ decider（ADD / MERGE / SUPERSEDE / CONFLICT / IGNORE）
-写入新的规范 Event，保留来源和 supersedes/conflicts 关系
-    ↓
-只为新 Event 创建元素/知识图谱投影任务
-```
-
-## 最小接入
-
-```ts
-import {
-  EXTERNAL_MEMORY_EXPORT_PROMPT_ZH_CN,
-  StrataGate,
-  externalMemoryJsonExtractor,
-} from '@diqier/stratagate';
-
-// 把 EXTERNAL_MEMORY_EXPORT_PROMPT_ZH_CN 交给外部 AI，并把它返回的 JSON 放入 text。
-const result = await memory.importExternalMemory({
-  text,
-  extractor: externalMemoryJsonExtractor,
-  topK: 5,
-  decider: async ({ candidate, matches }) => {
-    // 这里通常调用你的 LLM；它只能从 matches 中选择 existingEventIds。
-    // 返回的 MERGE/SUPERSEDE 会创建新 Event，不会覆盖旧 Event。
-    return {
-      action: matches.length === 0 ? 'ADD' : 'MERGE',
-      existingEventIds: matches.slice(0, 1).map(({ event }) => event.id),
-      mergedCandidate: candidate,
-    };
-  },
-});
-```
-
-`decider` 的 `matches` 已经被限制为 `topK` 条；即使模型返回其它事件 ID，库也会丢弃这些越界引用。`IGNORE` 只留下审计记录，不会写入 Event。`CONFLICT` 会在新旧事件两侧建立对称的 `conflictsWithEventIds`。
-
-## 给外部 AI 的提示词
-
-直接使用导出的 `EXTERNAL_MEMORY_EXPORT_PROMPT_ZH_CN`。它要求外部 AI 只输出 `stratagate.external-memory.v2` JSON，并区分 `memoryKind`（instruction/preference/fact/event）与 `category`，同时特别约束时间：
-
-- `mentionedAt`（被提及时间）与 `happenedStart/happenedEnd`（实际发生/计划时间）分开；
-- 没有明确时间或可靠参照时，不填写日期，不把当前时间、导出时间或聊天顺序当作事件时间；
-- 保留 `originalText`，用 `precision` 和 `basis` 标记粒度与依据；
-- “上周”等相对时间只有在能依据已知消息时间唯一换算时才转换，否则保持 `unknown`。
-
-如果外部 AI 仍然返回 Markdown 代码块，`parseExternalMemoryExport()` 会自动去除围栏；其它非 JSON 文本会被拒绝，避免把模型解释误写进记忆。
-
-用于第二阶段裁决的系统提示词可使用 `EXTERNAL_MEMORY_DECIDER_PROMPT_ZH_CN`。它明确规定了五种写入动作的边界，并要求模型只能引用本次 Top-K 结果中的事件 ID。
+# 外部 AI 记忆导入
+
+StrataGate 提供 `importExternalMemory()` 编排外部记忆迁移：
+
+```text
+外部 AI JSON
+    ↓ extractor（候选 Event）
+每个候选 Event → searchEvents()（确定性 BM25，Top-K）
+    ↓ decider（ADD / MERGE / SUPERSEDE / CONFLICT / IGNORE）
+写入新的规范 Event，保留来源和 supersedes/conflicts 关系
+    ↓
+只为新 Event 创建元素/知识图谱投影任务
+```
+
+## 最小接入
+
+```ts
+import {
+  EXTERNAL_MEMORY_EXPORT_PROMPT_ZH_CN,
+  StrataGate,
+  externalMemoryJsonExtractor,
+} from '@diqier/stratagate';
+
+// 把 EXTERNAL_MEMORY_EXPORT_PROMPT_ZH_CN 交给外部 AI，并把它返回的 JSON 放入 text。
+const result = await memory.importExternalMemory({
+  text,
+  extractor: externalMemoryJsonExtractor,
+  topK: 5,
+  decider: async ({ candidate, matches }) => {
+    // 这里通常调用你的 LLM；它只能从 matches 中选择 existingEventIds。
+    // 返回的 MERGE/SUPERSEDE 会创建新 Event，不会覆盖旧 Event。
+    return {
+      action: matches.length === 0 ? 'ADD' : 'MERGE',
+      existingEventIds: matches.slice(0, 1).map(({ event }) => event.id),
+      mergedCandidate: candidate,
+    };
+  },
+});
+```
+
+`decider` 的 `matches` 已经被限制为 `topK` 条；即使模型返回其它事件 ID，库也会丢弃这些越界引用。`IGNORE` 只留下审计记录，不会写入 Event。`CONFLICT` 会在新旧事件两侧建立对称的 `conflictsWithEventIds`。
+
+## 给外部 AI 的提示词
+
+直接使用导出的 `EXTERNAL_MEMORY_EXPORT_PROMPT_ZH_CN`。它要求外部 AI 只输出 `stratagate.external-memory.v2` JSON，并区分 `memoryKind`（instruction/preference/fact/event）与 `category`，同时特别约束时间：
+
+- `mentionedAt`（被提及时间）与 `happenedStart/happenedEnd`（实际发生/计划时间）分开；
+- 没有明确时间或可靠参照时，不填写日期，不把当前时间、导出时间或聊天顺序当作事件时间；
+- 保留 `originalText`，用 `precision` 和 `basis` 标记粒度与依据；
+- “上周”等相对时间只有在能依据已知消息时间唯一换算时才转换，否则保持 `unknown`。
+
+如果外部 AI 仍然返回 Markdown 代码块，`parseExternalMemoryExport()` 会自动去除围栏；其它非 JSON 文本会被拒绝，避免把模型解释误写进记忆。
+
+用于第二阶段裁决的系统提示词可使用 `EXTERNAL_MEMORY_DECIDER_PROMPT_ZH_CN`。它明确规定了五种写入动作的边界，并要求模型只能引用本次 Top-K 结果中的事件 ID。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stratagate-dsh",
-  "version": "0.2.60",
+  "version": "0.2.61",
   "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",
@@ -36,8 +36,8 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-ui-conversation"
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
       ],
       "platform": "web"
     }
@@ -110,8 +110,8 @@
       "dispose": "supported"
     },
     "compatibility": {
-      "dshVersions": [
-        "0.1.2-rc.1"
+      "dshVersions": [
+        "0.1.2-rc.1"
       ]
     },
     "permissions": [
@@ -143,26 +143,26 @@
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent-default-model": ">=0.1.2-rc.1 <0.2.0",
-    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.2-rc.1 <0.2.0",
-    "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1 <0.2.0",
-    "@deepseek-ai/dsh-session": ">=0.1.2-rc.1 <0.2.0",
-    "@deepseek-ai/dsh-settings": ">=0.1.2-rc.1 <0.2.0",
-    "@deepseek-ai/dsh-system-prompt": ">=0.1.2-rc.1 <0.2.0",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent-default-model": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-session": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-settings": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent-default-model": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-settings": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent-default-model": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@types/node": "^22.0.0",
     "cytoscape": "^3.34.1",

package/screenshots.json

@@ -1,4 +1,4 @@
-[
-  "docs/assets/stratagate-knowledge-graph.png",
-  "docs/assets/stratagate-short-term-memory.png"
-]
+[
+  "docs/assets/stratagate-knowledge-graph.png",
+  "docs/assets/stratagate-short-term-memory.png"
+]