dsh-engram 0.3.5 → 0.3.6

package/README.md

@@ -40,6 +40,17 @@ with one goal: **save tokens**.
   tokenization), recall runs a bounded substring scan over the newest session
   logs (zstd-decompressed, LRU-cached) and appends matched past sessions —
   deterministic `# past sessions` lines, capped files and bytes.
+- **Session-start auto-recall (`autoRecallOnStart`, default on)** — the pull-only
+  design had a gap proven in real use: recall tools relied on model initiative,
+  and in practice the model almost never calls `engram_recall` on its own (19
+  real sessions, thousands of tool calls, ~5 recall calls total). So at the FIRST
+  assembly of a new session the host runs one deterministic BM25 recall keyed on
+  the session's first user message and injects the top ≤ `autoRecallLimit` hits
+  as a `[RECALL]` block (default 700-char budget, "few and precise" — agentmemory
+  candidate ①). Relevant memory is in context even without a single recall call.
+  Pure rule, zero LLM, pure read (never bumps `hits`); superseded stale truth does
+  not occupy an injection slot (still fetchable via `engram_detail`); frozen per
+  session together with `[ENGRAM]` for prefix stability.
 - **Memory-to-memory semantics** — `engram_store` accepts optional
   `supersedes` / `contradicts` memory ids (validated against the same
   workspace). A superseded ("stale truth") memory is demoted to the tail of
@@ -128,14 +139,105 @@ LLM-distillation and vector/graph niches are already crowded. dsh-engram fills t
 three gaps that matter for token discipline:
 
 1. **No model in the write path** — capture is deterministic pattern matching.
-2. **No raw text in the prompt** — a bounded symbolic index is injected, retrieval
-   stays on demand ("retrieved ≠ injected").
+2. **No raw text in the prompt** — a bounded symbolic index is injected, plus the
+   top ≤ N memories auto-recalled for the session's first message (within budget);
+   deeper retrieval stays on demand ("retrieved ≠ full-text injected").
 3. **Honest task closure** — STABLE cannot be declared without evidence.
 
 DSH already provides cross-session FTS (`ctx.sessionQuery`), storage
 (`ctx.storageDomain`), prompt-injection hooks and settings slots; dsh-engram is a
 thin composition layer over them, not a re-implementation.
 
+## Security model
+
+The DSH plugin ecosystem is young and unvetted — there is no official directory,
+no signature check, and the harness's read/write permission tiers do **not**
+constrain what a plugin's own code can do. So the trust bar for a memory plugin
+is higher than for a tool: a memory plugin sits on your prompt prefix and writes
+to disk on your behalf. dsh-engram's model, stated plainly:
+
+- **No network, ever.** The plugin has no outbound socket, no telemetry, no
+  update pinger. Nothing here can leak your sessions off the machine.
+- **No shell, no filesystem access beyond one storage file.** It never executes
+  commands and never touches arbitrary paths. All data lives in the single
+  storage-domain unit `~/.dsh/storages/dsh_engram.json` (plus the session-log
+  reads it makes through DSH's own `ctx.sessionQuery`).
+- **Secrets are redacted before they can land on disk.** Every write path —
+  `engram_store`, auto-capture, and the import/restore route — runs text through
+  the deterministic `redactText` rule engine (API keys, JWTs, `Bearer` tokens,
+  private keys, `key=value` secret shapes) *before* the dedup hash, the char
+  cap, and storage. Nothing sensitive is ever persisted, so nothing sensitive
+  can be recalled later.
+- **Doing harm requires your harness's own permissions.** The plugin only *asks*
+  the host to do things via the same seams the tools you already trust use. It
+  does not widen sandbox policy or escalate to `danger-full-access` — if you
+  keep your profile's defaults, engram inherits exactly those bounds.
+- **Read-mostly web API, loopback-fenced.** The GUI routes under
+  `/api/dsh-engram` reject any non-loopback caller unless you explicitly
+  whitelist a hostname via `trustedHosts`; even then the same-origin fence holds.
+- **Verifiable.** `npm run dsh-engram -- doctor` (`/scripts/dsh-engram.mjs
+  doctor`) reports what the plugin is configured to touch; the whole store is
+  inspectable, nothing is opaque. If you ever doubt a claim in this section, the
+  code to check is `lib/redact.js`, `lib/store.js` and this plugin's
+  `cordis.patch.yml`.
+
+What this deliberately does **not** claim: it is not an air-gap. If your profile
+grants the agent `danger-full-access` or a shell, the agent can use those —
+engram is a memory layer, not a sandbox. The point above is that *dsh-engram
+itself* adds no surface of its own.
+
+## Data contract: export / import
+
+Memory should not be a hostage. The four tables (memories / tasks / links /
+entities) can be dumped and restored through a stable, versioned, machine-readable
+shape — so the corpus survives a reinstall, a machine move, or (when a thin
+adapter is written) a move to another harness, MCP end-point or Claude Code
+skill. The contract is plain JSON with a self-describing header:
+
+```http
+GET  /api/dsh-engram/export?workspace=/path/to/project   # one workspace
+GET  /api/dsh-engram/export                              # every workspace
+```
+
+```jsonc
+{
+  "meta": { "format": "dsh-engram/export", "version": 1, "exportedAt": 1724…, "workspace": "/path/to/project" },
+  "memories": [ /* all rows, archived included — a backup never loses provenance */ ],
+  "tasks":    [ /* draft/active/stable + archived */ ],
+  "links":    [ /* typed edges */ ],
+  "entities": [ /* graph nodes */ ]
+}
+```
+
+Restore is idempotent by default and gated when destructive:
+
+```http
+POST /api/dsh-engram/import          # body: { payload, mode, dryRun?, workspace?, confirm? }
+```
+
+- **`mode: "merge"`** (default) — writes only rows whose `id` is absent, so a
+  backup can be re-applied any number of times without duplicating anything. Each
+  row keeps its own `workspace`.
+- **`mode: "replace"`** — wipes the target `workspace` from all four tables, then
+  restores only its rows. Destructive, so it additionally requires
+  `confirm: "restore"` in the body.
+- **`dryRun: true`** — computes the identical plan (what would be written /
+  skipped) without writing a single row.
+- **Import honors the same invariants as `storeMemory`**: memory text passes the
+  secret redactor before touching disk, and rows that would break the contract
+  (missing id/workspace, empty text, over `maxMemoryChars`, id already present
+  in merge, over the workspace memory cap) are skipped and listed in the
+  response report instead of aborting the batch.
+
+A restore round-trip for one workspace is then:
+
+```sh
+curl -s "http://127.0.0.1:3080/api/dsh-engram/export?workspace=$PWD" -o engram-backup.json
+curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
+  -H "content-type: application/json" \
+  -d "{\"payload\": $(cat engram-backup.json), \"mode\": \"merge\"}"
+```
+
 ## Install
 
 ```sh
@@ -317,8 +419,8 @@ npm run build:client
 
 | Tool | Purpose | Kind |
 |---|---|---|
-| `engram_store` | Explicitly store one memory (kind, tags, optional entity anchor, optional supersedes/contradicts memory ids) | write |
-| `engram_recall` | Deterministic keyword recall over workspace memories; optional `search_sessions` FTS over past sessions | read |
+| `engram_store` | Explicitly store one memory (kind, tags, optional entity anchor, optional supersedes/contradicts ids, optional `source`/`conditions`) | write |
+| `engram_recall` | Deterministic keyword recall over workspace memories; optional `search_sessions` FTS over past sessions; opt-in `scope=global`/`recallScope` cross-workspace recall with `[W:<ws>]` origin markers | read |
 | `engram_detail` | Full record of one memory id (provenance, tags, hits) | read |
 | `esr_task` | Create a task entity (draft → active) | write |
 | `esr_close` | Close a task via the evidence protocol (artifact + evaluation + memory_ref) | write |
@@ -542,7 +644,11 @@ ESR operating protocol (static, byte-identical every turn)
 [ENGRAM] workspace: symbolic-index · 2 memories · 1 task(s) active · 0 links
 [D] 06-18 Decided: use sqlite-vec for retrieval #a2331d87
 [T] 06-18 Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref #tsk_8b26
-drill: engram_store (user asks to remember) | engram_recall <query> | engram_detail <id> | esr_task / esr_close / esr_link
+drill: use [RECALL] below · engram_detail <id> (full record) · engram_recall <query> (more) · esr_task/esr_node/esr_link (work)
+
+[RECALL] recall · 1 hit(s) · first msg: retrieval
+- [D] 06-18 Decided: use sqlite-vec for retrieval upgrade #a2331d87 ×2
+context: use above · engram_detail <id> · engram_recall <query>
 
 [ESR] tasks: 1 active / 1 stable
 - tsk_0d: Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref
@@ -564,6 +670,14 @@ records via `engram_detail`. When a workspace has no tasks, `[ESR]` still render
 one line naming `esr_task`/`esr_close` so the mechanism stays visible to the
 model instead of vanishing.
 
+`[RECALL]` (session-start auto recall, `autoRecallOnStart`) runs one deterministic
+BM25 pass over the workspace keyed on the session's first user message and injects
+the top `autoRecallLimit` hits, bounded by the `autoRecallMaxChars` character
+budget; nothing renders on zero hits or an empty workspace. It is a *pointer* — the
+model should treat it as "this is relevant; `engram_detail` for the full record" —
+rather than full-text dumping. It is a pure read (never bumps `hits`), superseded
+stale truth never occupies a slot, and it freezes per session with `[ENGRAM]`.
+
 ## Config
 
 Defaults are token-conscious; override any key via the profile patch
@@ -574,6 +688,10 @@ Defaults are token-conscious; override any key via the profile patch
   config:
     autoCapture: true        # zero-LLM tool-result capture
     sessionSearch: true      # engram_recall may also FTS past sessions
+    recallScope: workspace   # recall scope: "workspace" (strict isolation, default) | "global" (opt-in cross-workspace recall with [W:<ws>] origin markers)
+    autoRecallOnStart: true  # session-start auto recall (false = back to pure pull)
+    autoRecallLimit: 3       # [RECALL] max injected hits (few and precise)
+    autoRecallMaxChars: 700  # [RECALL] char budget
     autoCapturePerSession: 40
     indexMaxLines: 12        # [ENGRAM] line cap
     indexMaxChars: 700       # [ENGRAM] char cap (token budget)
@@ -616,7 +734,11 @@ dedup 1.0.
 **/api/dsh-engram/stats + the observability panel** is the real-session layer —
 it answers how the model actually uses the memory in production (ESR
 proactivity ratio, recall hit rate, detail conversion), while the eval
-answers how good the retrieval layer itself is.
+answers how good the retrieval layer itself is. The stats read the
+concatenated multi-frame `session.jsonl.zstd` logs with Node's built-in
+`node:zlib` (frame scan + one reused decoder handle) — **no system `zstd` CLI
+is required**, so the telemetry works out-of-the-box on Windows and other
+hosts without an external codec.
 
 Repo layout: `lib/` (host half: store / capture / index-block / tools / api /
 settings), `client/` (browser half, TSX + `build.mjs`), `test/` (node:test).

package/README.zh.md

@@ -28,6 +28,13 @@
   且查询含 **CJK 中文**（FTS5 中文分词整段只算一个 token）时，召回会对最近若干会话日志做
   有界的**子串扫描**（zstd 解压 + LRU 缓存，限文件数与字节），追加命中会话的确定性
   `# past sessions` 行。
+- **会话启动自动召回（`autoRecallOnStart`，默认开）** — 纯拉取式设计有个被实证戳穿的盲区：
+  召回工具只交模型自觉，而真实会话里模型几乎从不主动调 `engram_recall`（实测 19 个会话数千次
+  工具调用只出现 ~5 次召回）。因此宿主在新会话**首次组装**时，用会话**首条用户消息**对工作区做
+  一次确定性 BM25 召回，把命中前 ≤3 条直接注入 `[RECALL]` 块（默认 700 字符预算，"少而准"，
+  agentmemory 候选①）——相关记忆不依赖模型想起来就已在上下文里。纯规则、零 LLM、
+  纯读不 bump 命中；superseded 过期真相不占注入槽（仍可 `engram_detail` 重取）；
+  与 `[ENGRAM]` 一起按会话冻结保持前缀稳定。
 - **记忆间语义（supersede/contradict）** — `engram_store` 可选收 `supersedes` / `contradicts`
   记忆 id（同工作区校验）。被 supersede 的「过期真相」在召回里**降级到尾部**、并从 `[ENGRAM]`
   块中**剔除**（新陈述占行）；被 contradicts 的记忆保留排序但标注 `· contradicted by <id>`。
@@ -83,12 +90,65 @@ MIT   ·   node >= 22.19   ·   host 半边 + 浏览器半边合在一包
 dsh-engram 补的是对 token 纪律真正重要的三个空白：
 
 1. **写入路径没有模型** — 捕获是确定性的模式匹配。
-2. **提示词里不灌原文** — 只注入有界的符号索引，检索按需进行（"检索到 ≠ 注入"）。
+2. **提示词里不灌全文** — 只注入有界的符号索引 + 会话启动时自动召回的最相关 ≤3 条（预算内），
+   更深的检索按需进行（"检索到≠灌全文"）。
 3. **诚实的任务闭环** — 没有证据就不能宣布 STABLE。
 
 DSH 已经提供跨会话 FTS（`ctx.sessionQuery`）、存储（`ctx.storageDomain`）、提示词注入钩子和设置槽位；
 dsh-engram 只是这些能力之上的一层薄组合层，而非重新实现。
 
+## 安全模型
+
+DSH 插件生态还很年轻、缺乏背书：没有官方目录、没有签名校验，且 harness 的读写权限三档**约束不了插件自身代码**。因此记忆插件面对的信任何题比工具更高——它趴在你的提示词前缀上，还替你在磁盘上写东西。dsh-engram 的模型，直说如下：
+
+- **永远不联网。** 本插件没有出口 socket、没有遥测、没有更新探针。任何东西都不可能把会话带出本机。
+- **无 shell、除一个存储文件外不碰文件系统。** 不执行命令、不碰任意路径。全部数据只落在一个 storage-domain 单元 `~/.dsh/storages/dsh_engram.json`（外加经 DSH 自身 `ctx.sessionQuery` 做的会话日志读取）。
+- **密钥在落盘之前就被脱敏。** 每条写入路径——`engram_store`、自动捕获，以及本节的**导入/恢复**——都先把文本过一遍确定性的 `redactText` 规则引擎（API Key、JWT、`Bearer` token、私钥、`key=value` 密钥形态），*之后*才做去重哈希、字符上限与落盘。敏感文本永不落盘，召回时自然也不会有。
+- **要做什么坏事，必须借你 harness 自己的权限。** 插件只通过你已信任的工具同款的 seam 向宿主"请求"做事；不扩沙箱策略、不拉高到 `danger-full-access`——你保持 profile 默认，engram 就只继承那些边界。
+- **Web API 只读为主、loopback 栅栏。** `/api/dsh-engram` 下的 GUI 路由拒绝任何非回环调用方，除非你用 `trustedHosts` 显式放行某个主机名；即便放行，同源栅栏依然生效。
+- **可核验。** `npm run dsh-engram -- doctor`（`scripts/dsh-engram.mjs doctor`）报告插件被配置去碰什么；整个 store 可检视、不透明的东西为零。如果对这一段有怀疑，要查的代码就是 `lib/redact.js`、`lib/store.js` 和本插件的 `cordis.patch.yml`。
+
+这**不是**说它是个气闸：如果你的 profile 给了 agent `danger-full-access` 或 shell，agent 可以用——engram 是记忆层而不是沙箱。上面这句话的意思是：*dsh-engram 自己*不新增任何攻击面。
+
+## 数据契约：导出 / 导入
+
+记忆不该当人质。四张表（memories / tasks / links / entities）可以用一个稳定、带版本号的机器可读格式整体倒出再恢复——重装、换机，或者（写一层薄适配器之后）搬到别的 harness / MCP 端点 / Claude Code skill，语料都跟得走。契约是带自描述头的纯 JSON：
+
+```http
+GET  /api/dsh-engram/export?workspace=/path/to/project   # 单个工作区
+GET  /api/dsh-engram/export                              # 全部工作区
+```
+
+```jsonc
+{
+  "meta": { "format": "dsh-engram/export", "version": 1, "exportedAt": 1724…, "workspace": "/path/to/project" },
+  "memories": [ /* 全部行，含归档——备份不丢溯源 */ ],
+  "tasks":    [ /* draft/active/stable + 归档 */ ],
+  "links":    [ /* 类型化边 */ ],
+  "entities": [ /* 图节点 */ ]
+}
+```
+
+恢复默认幂等、破坏性操作有门禁：
+
+```http
+POST /api/dsh-engram/import          # body: { payload, mode, dryRun?, workspace?, confirm? }
+```
+
+- **`mode: "merge"`**（默认）— 只写 `id` 尚不存在的行，备份可以随便重复套用而不会重复；每行保留自己的 `workspace`。
+- **`mode: "replace"`** — 先把目标 `workspace` 的四张表清空，再只恢复属于它的行。破坏性操作，因此 body 里还要求 `confirm: "restore"`。
+- **`dryRun: true`** — 只算出完全相同的执行计划（会写什么 / 跳过什么），不写任何一行。
+- **导入遵守与 `storeMemory` 相同的不可变约定**：记忆文本落盘前先过密钥脱敏；会破坏契约的行（缺 id/workspace、空文本、超 `maxMemoryChars`、merge 时 id 已存在、超工作区记忆上限）会被跳过并写进响应报告，而不是中止整批。
+
+单工作区的恢复往返：
+
+```sh
+curl -s "http://127.0.0.1:3080/api/dsh-engram/export?workspace=$PWD" -o engram-backup.json
+curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
+  -H "content-type: application/json" \
+  -d "{\"payload\": $(cat engram-backup.json), \"mode\": \"merge\"}"
+```
+
 ## 安装
 
 ```sh
@@ -224,8 +284,8 @@ npm run eval  # 离线召回 + 结构基准（确定性语料，跑真实 store/
 
 | 工具 | 用途 | 类型 |
 |---|---|---|
-| `engram_store` | 显式存入一条记忆（kind、tags、可选实体锚点、可选 supersedes/contradicts 记忆 id） | 写 |
-| `engram_recall` | 工作区记忆的确定性关键词召回；可选 `search_sessions` 跨会话 FTS | 读 |
+| `engram_store` | 显式存入一条记忆（kind、tags、可选实体锚点、可选 supersedes/contradicts id，可选 `source`/`conditions`） | 写 |
+| `engram_recall` | 工作区记忆的确定性关键词召回；可选 `search_sessions` 跨会话 FTS；可选 `scope=global`/`recallScope` 跨工作区召回（带 `[W:<ws>]` 来源标记） | 读 |
 | `engram_detail` | 一条记忆 id 的完整记录（来源、标签、命中数） | 读 |
 | `esr_task` | 创建任务实体（draft → active） | 写 |
 | `esr_close` | 按证据协议关闭任务（artifact + evaluation + memory_ref） | 写 |
@@ -402,7 +462,11 @@ ESR 操作协议（静态，每轮逐字节相同）
 [ENGRAM] workspace: symbolic-index · 2 memories · 1 task(s) active · 0 links
 [D] 06-18 Decided: use sqlite-vec for retrieval #a2331d87
 [T] 06-18 Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref #tsk_8b26
-drill: engram_store (user asks to remember) | engram_recall <query> | engram_detail <id> | esr_task / esr_close / esr_link
+drill: use [RECALL] below · engram_detail <id> (full record) · engram_recall <query> (more) · esr_task/esr_node/esr_link (work)
+
+[RECALL] recall · 1 hit(s) · first msg: retrieval
+- [D] 06-18 Decided: use sqlite-vec for retrieval upgrade #a2331d87 ×2
+context: use above · engram_detail <id> · engram_recall <query>
 
 [ESR] tasks: 1 active / 1 stable
 - tsk_0d: Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref
@@ -420,6 +484,11 @@ promote: 2 pending todo(s) vs 1 ESR task(s) — esr_task(name="…") #suggest-pr
 `#` id 通过 `engram_detail` 取完整记录。工作区没有任务时，`[ESR]` 仍会渲染一行点名 `esr_task`/`esr_close`，
 让机制对模型保持可见，而不是整体消失。
 
+`[RECALL]`（会话启动自动召回，`autoRecallOnStart`）按会话首条消息对工作区做确定性 BM25 召回，
+把命中前 `autoRecallLimit` 条注入，受 `autoRecallMaxChars` 字符预算约束；无命中或空工作区时不渲染。
+它是一条**提示**而不是全文灌入——模型该把它当成"这条相关，可能需要用 `engram_detail` 看细节"。
+纯读、不 bump 命中、superseded 过期真相不占槽位；随 `[ENGRAM]` 一起按会话冻结。
+
 ## 配置
 
 默认值以 token 为优先；可通过 profile 补丁（`~/.dsh/profiles/web/cordis.patch.yml`）或 Web 配置卡片覆盖任意键：
@@ -429,6 +498,10 @@ promote: 2 pending todo(s) vs 1 ESR task(s) — esr_task(name="…") #suggest-pr
   config:
     autoCapture: true        # 零 LLM 工具结果捕获
     sessionSearch: true      # engram_recall 也可对历史会话 FTS
+    recallScope: workspace   # 召回范围：workspace（严格工作区隔离，默认）| global（可选跨工作区召回，带 [W:<ws>] 来源标记）
+    autoRecallOnStart: true  # 会话启动自动召回：按首条消息注入 [RECALL] 块（false=回到纯拉取）
+    autoRecallLimit: 3       # [RECALL] 最多注入条数（少而准）
+    autoRecallMaxChars: 700  # [RECALL] 字符预算
     autoCapturePerSession: 40
     indexMaxLines: 12        # [ENGRAM] 行数上限
     indexMaxChars: 700       # [ENGRAM] 字符上限（token 预算）

package/lib/api.js

@@ -18,6 +18,9 @@ export const API_PREFIX = "/api/dsh-engram";
 /** Cap on JSON request bodies (archives/deletes are tiny). */
 const MAX_JSON_BODY_BYTES = 32 * 1024;
 
+/** Import dumps carry whole workspaces of memories/tasks — allow up to 32 MiB. */
+const MAX_IMPORT_BODY_BYTES = 32 * 1024 * 1024;
+
 /** Loopback literal check plus browser same-origin markers. */
 function isLoopbackRequest(request, trustedHosts = []) {
   const address = request.socket?.remoteAddress;
@@ -67,13 +70,13 @@ function readQuery(req) {
   return url.searchParams;
 }
 
-function readJsonBody(req) {
+function readJsonBody(req, maxBytes = MAX_JSON_BODY_BYTES) {
   return new Promise((resolve) => {
     let size = 0;
     const chunks = [];
     req.on("data", (chunk) => {
       size += chunk.length;
-      if (size > MAX_JSON_BODY_BYTES) {
+      if (size > maxBytes) {
         resolve({ error: "body too large" });
         req.destroy();
         return;
@@ -300,6 +303,56 @@ export function makeEngramRoutes(service) {
     }
   };
 
+  /**
+   * Data contract — dump every row (memories/tasks/links/entities, archived
+   * included) of one workspace (`?workspace=`) or of every workspace, in the
+   * machine-readable `dsh-engram/export` v1 format that `POST /import`
+   * round-trips. Export is the stable, format-versioned exit door: the memory
+   * corpus never depends on engram's internal tables, and a thin adapter
+   * (another harness, MCP, a plain backup script) only needs this shape.
+   */
+  const exportData = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const workspace = readQuery(req).get("workspace") || void 0;
+    try {
+      writeJson(res, 200, domain.exportAll(workspace));
+    } catch (error) {
+      writeError(res, 500, String(error?.message ?? error));
+    }
+  };
+
+  /** Data contract — restore a `dsh-engram/export` dump (see store.importAll:
+   *  merge = idempotent add-missing, replace = wipe workspace then restore;
+   *  `dryRun` plans without writing; `confirm: "restore"` is required for the
+   *  destructive replace mode). Memory text passes the same secret redactor as
+   *  every other write path. */
+  const importData = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const body = await readJsonBody(req, MAX_IMPORT_BODY_BYTES);
+    if (body.error) return writeError(res, 400, body.error);
+    const { payload, mode, dryRun, workspace, confirm } = body.value ?? {};
+    if (mode !== "merge" && mode !== "replace") {
+      return writeError(res, 400, "mode must be 'merge' or 'replace'");
+    }
+    if (mode === "replace" && confirm !== "restore") {
+      return writeError(res, 400, "replace mode is destructive — pass confirm: \"restore\" to proceed");
+    }
+    try {
+      const report = await domain.importAll(payload, {
+        mode: mode ?? "merge",
+        dryRun: dryRun === true,
+        workspace: typeof workspace === "string" && workspace.length > 0 ? workspace : void 0,
+        config: service.config ?? {},
+      });
+      writeJson(res, 200, report);
+    } catch (error) {
+      const status = error instanceof Error && error.code === "ENGRAM_INVALID_ARGS" ? 400 : 500;
+      writeError(res, status, String(error?.message ?? error));
+    }
+  };
+
   const guard = (req, res, method, handler) => {
     if ((req.method ?? "GET").toUpperCase() !== method) {
       writeError(res, 405, "method not allowed");
@@ -536,5 +589,7 @@ export function makeEngramRoutes(service) {
     make("POST", "/memories/delete", remove),
     make("POST", "/tasks/close", closeTask),
     make("POST", "/gc", gcRun),
+    make("GET", "/export", exportData),
+    make("POST", "/import", importData),
   ];
 }

package/lib/client.js

@@ -3341,6 +3341,7 @@ var import_react8 = require("react");
 var import_jsx_runtime8 = require("react/jsx-runtime");
 var COMMON_FIELDS = [
   { key: "autoCapture", label: "\u81EA\u52A8\u6355\u83B7", hint: "\u96F6 LLM \u4ECE\u5DE5\u5177\u7ED3\u679C\u63D0\u53D6\u8BB0\u5FC6\uFF08git/\u5173\u952E\u6587\u4EF6/\u9519\u8BEF\uFF09", kind: "bool" },
+  { key: "autoRecallOnStart", label: "\u4F1A\u8BDD\u542F\u52A8\u81EA\u52A8\u53EC\u56DE", hint: "\u65B0\u4F1A\u8BDD\u6309\u9996\u6761\u6D88\u606F\u81EA\u52A8\u628A\u6700\u76F8\u5173\u8BB0\u5FC6\u6CE8\u5165 [RECALL] \u5757\uFF08\u65E0\u9700\u6A21\u578B\u60F3\u8D77\u8C03 engram_recall\uFF09\uFF1B\u5173\u6389=\u56DE\u5230\u7EAF\u62C9\u53D6", kind: "bool" },
   { key: "maxRecallPerSession", label: "\u6BCF\u4F1A\u8BDD\u53BB\u91CD\u4E0A\u9650", hint: "recall \u6BCF\u4F1A\u8BDD\u6700\u591A\u4FDD\u7559 N \u6761\uFF08\u8DE8\u4F1A\u8BDD\u53BB\u91CD\uFF09", kind: "num", min: 1, max: 10 },
   { key: "expireDays", label: "TTL\uFF08\u5929\uFF09", hint: "0 = \u4E0D\u8FC7\u671F", kind: "num", min: 0, max: 3650 },
   { key: "indexMaxChars", label: "\u7D22\u5F15\u5B57\u7B26\u4E0A\u9650", hint: "[ENGRAM] \u5757 token \u9884\u7B97", kind: "num", min: 0, max: 4e3 }
@@ -3352,7 +3353,9 @@ var ADVANCED_GROUPS = [
     description: "\u5176\u4F59\u6355\u83B7/\u641C\u7D22\u65CB\u94AE",
     fields: [
       { key: "autoCapturePerSession", label: "\u6BCF\u4F1A\u8BDD\u6355\u83B7\u4E0A\u9650", hint: "\u5355\u4F1A\u8BDD\u81EA\u52A8\u6355\u83B7\u6761\u6570\u4E0A\u9650", kind: "num", min: 0, max: 1e3 },
-      { key: "sessionSearch", label: "\u4F1A\u8BDD\u5386\u53F2\u641C\u7D22", hint: "engram_recall \u652F\u6301\u8DE8\u4F1A\u8BDD FTS \u515C\u5E95", kind: "bool" }
+      { key: "autoRecallLimit", label: "\u81EA\u52A8\u53EC\u56DE\u6761\u6570", hint: "[RECALL] \u5757\u6700\u591A\u6CE8\u5165\u7684\u8BB0\u5FC6\u6761\u6570\uFF08\u5C11\u800C\u51C6\uFF09", kind: "num", min: 1, max: 8 },
+      { key: "sessionSearch", label: "\u4F1A\u8BDD\u5386\u53F2\u641C\u7D22", hint: "engram_recall \u652F\u6301\u8DE8\u4F1A\u8BDD FTS \u515C\u5E95", kind: "bool" },
+      { key: "recallScope", label: "\u53EC\u56DE\u8303\u56F4", hint: "workspace=\u4E25\u683C\u5F53\u524D\u5DE5\u4F5C\u533A\u9694\u79BB\uFF08\u9ED8\u8BA4\uFF0Ctoken \u7EAA\u5F8B\uFF09\uFF1Bglobal=\u672C\u5DE5\u4F5C\u533A\u547D\u4E2D\u5F31/\u7A7A\u65F6\u4ECE\u5176\u5B83\u5DE5\u4F5C\u533A\u6C60\u53EC\u56DE\u5E76\u6807 [W:<workspace>] \u6765\u6E90\uFF08\u4F1A\u6253\u7834\u9694\u79BB\uFF09", kind: "select", options: ["workspace", "global"] }
     ]
   },
   {
@@ -3651,6 +3654,15 @@ function EngramConfigCard({ scope }) {
             disabled: !writable,
             onChange: (e) => setField(field.key, e.target.checked)
           }
+        ) : field.kind === "select" ? /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
+          "select",
+          {
+            style: { ...s3.input, width: field.width ?? 160 },
+            value: raw === void 0 ? "" : String(raw),
+            disabled: !writable,
+            onChange: (e) => setField(field.key, e.target.value),
+            children: (field.options ?? []).map((opt) => /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("option", { value: opt, children: opt }, opt))
+          }
         ) : field.kind === "text" ? /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
           "input",
           {

package/lib/index-block.js

@@ -115,7 +115,7 @@ export function renderIndex(store, workspace, cwd, config) {
   if (entityNames.length > 0) lines.push(`nodes: ${truncate(entityNames.join(", "), 72)}`);
   for (const m of memories.slice(0, config.indexMaxLines)) lines.push(memoryLine(m, config));
   for (const t of tasks.slice(0, 4)) lines.push(taskStateLine(t));
-  lines.push("drill: engram_recall <query> | engram_detail <id> | esr_task (multi-step work → create now) | esr_node (recurring domain object → create now) | esr_link (relate nodes/tasks)");
+  lines.push("drill: use [RECALL] below · engram_detail <id> (full record) · engram_recall <query> (more) · esr_task/esr_node/esr_link (work)");
   return enforceCharCap(lines, config.indexMaxChars);
 }
 
@@ -133,6 +133,97 @@ function enforceCharCap(lines, maxChars) {
   return joined;
 }
 
+/** Text of the session's first user message (the opening instruction of the
+ *  conversation). Walk `session.events` for the first `user/message` event and
+ *  join its `data.content` text blocks; fall back to the first text-bearing
+ *  event ("goal"/reminder start) guardedly. Returns "" when there is none.
+ *  Pure, deterministic — the auto-recall (B) keys its query off this. */
+export function firstUserMessageText(session) {
+  if (session === null || typeof session !== "object") return "";
+  const events = Array.isArray(session.events) ? session.events : [];
+  if (events.length === 0) return "";
+  const textOf = (data) => {
+    if (data === null || typeof data !== "object") return "";
+    const blocks = Array.isArray(data.content) ? data.content : [];
+    if (blocks.length > 0) {
+      return blocks
+        .map((b) => (b !== null && typeof b === "object" && typeof b.text === "string" ? b.text : ""))
+        .join(" ")
+        .trim();
+    }
+    return typeof data.text === "string" ? data.text.trim() : "";
+  };
+  for (const event of events) {
+    if (event === null || typeof event !== "object") continue;
+    if (event.type !== "user/message") continue;
+    const text = textOf(event.data);
+    if (text.length > 0) return text;
+  }
+  // Fallback: no user/message yet — first event carrying text (goal-driven,
+  // headless or reminder-seeded starts) still gives the recall a key.
+  for (const event of events) {
+    if (event === null || typeof event !== "object" || event.type === "user/message") continue;
+    const text = textOf(event.data);
+    if (text.length > 0) return text;
+  }
+  return "";
+}
+
+/**
+ * Host-side session-start auto-recall (方案 B): at the first assembly of a new
+ * session, deterministically key a bounded BM25 recall off the session's first
+ * user message and inject the top hits as a `[RECALL]` block — so relevant
+ * memory reaches the model even when it never calls `engram_recall` on its own
+ * (the observed real-world gap). Pure rule, zero LLM, no `hits` bumps (a pure
+ * read). Falls back to the newest high-signal memories when the query is empty
+ * and `allowRecencyFallback` is on. Returns "" when nothing useful to show.
+ */
+export function renderStartRecall(store, workspace, config = {}, opts = {}) {
+  if (store === null || typeof store?.recall !== "function") return "";
+  const limit = Math.max(1, Math.min(8, Number.isFinite(config.autoRecallLimit) ? Math.trunc(config.autoRecallLimit) : 3));
+  const maxChars = Number.isFinite(config.autoRecallMaxChars) && config.autoRecallMaxChars > 0 ? Math.trunc(config.autoRecallMaxChars) : 700;
+  const rawQuery = String(opts.query ?? "").trim().slice(0, 300);
+  const query = rawQuery.length > 0 ? rawQuery : (opts.allowRecencyFallback ?? true) ? null : "";
+  const items = query === null
+    ? (store.listMemories?.(workspace, limit) ?? []).slice(0, limit)
+    : store.recall(workspace, query, limit, { maxPerSession: limit });
+  const hits = Array.isArray(items) ? items.filter((m) => m !== null && m !== void 0) : [];
+  // "Few and precise" (agentmemory 候选①): never let a superseded stale row —
+  // which `recall` demotes to the tail of an unbounded list — occupy one of the
+  // ≤ N auto-injected slots. Same policy as the [ENGRAM] index. The stale row
+  // stays re-fetchable via engram_detail, just not auto-pushed.
+  const { supersededBy } = store.memoryRelations?.(workspace) ?? { supersededBy: new Map() };
+  const fresh = hits.filter((m) => !supersededBy.has(m.id));
+  if (fresh.length === 0) return "";
+
+  const lines = [];
+  const source = query === null ? "newest memory" : "recall";
+  lines.push(`[RECALL] ${source} · ${fresh.length} hit(s)${query ? ` · first msg: ${escapeLt(truncate(query, 40))}` : " · no user text yet"}`);
+  for (const m of fresh) {
+    const px = prefixFor(m.kind);
+    const mark = isProvenProcedure(m, config) ? `${px}✓` : px;
+    const date = fmtDate(m.createdAt ?? m.updatedAt);
+    const text = truncate(String(m.text).replace(/\s*\n+\s*/g, " ").trim(), 140);
+    lines.push(`- [${mark}] ${date} ${escapeLt(text)} #${shortId(m.id)}${(m.hits ?? 0) > 0 ? ` ×${m.hits}` : ""}`);
+  }
+  lines.push("context: use above · engram_detail <id> · engram_recall <query>");
+  return enforceStartRecallCap(lines, maxChars);
+}
+
+/** Keep the [RECALL] header + context tail, drop hits until under budget;
+ *  hard-truncate with an ellipsis when even the shell exceeds the cap. */
+function enforceStartRecallCap(lines, maxChars) {
+  let joined = lines.join("\n");
+  while (joined.length > maxChars && lines.length > 2) {
+    lines.splice(lines.length - 2, 1);
+    joined = lines.join("\n");
+  }
+  if (joined.length > maxChars) {
+    joined = `${joined.slice(0, Math.max(1, maxChars - 1))}…`;
+  }
+  return joined;
+}
+
 /**
  * One-line escalation reminder from an arbitrary balance view
  * ({ memCalls, esrCalls, days }). Surfaces the workspace real recent

package/lib/index.js

@@ -23,7 +23,7 @@ import { openEngramDomain } from "./store.js";
 import { registerTools } from "./tools.js";
 import { makeCaptureHandler } from "./capture.js";
 import { installGoalCapture } from "./goal-capture.js";
-import { renderIndex, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
+import { renderIndex, renderStartRecall, firstUserMessageText, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
 import { makeTriggerRecorder } from "./trigger.js";
 import { pendingTodosFromSession, sinkPendingTodos } from "./todo-sink.js";
 import { installEngramSettings } from "./settings.js";
@@ -48,9 +48,25 @@ const DEFAULTS = {
   autoCaptureGlobalCap: 500,
   // recall
   sessionSearch: true,
+  // opt-in cross-workspace recall ("workspace" = current default, strict
+  // per-workspace isolation; "global" = when the local pool has weak/no hits,
+  // also rank entries from other workspaces' pools with a recency/origin-aware
+  // penalty and surface a [W:<workspace>] origin marker). Token-discipline
+  // default is preserved; this is strictly an enable knob.
+  recallScope: "workspace",
   // session-diversified recall: max memories per session before cross-session
   // evidence takes over (agentmemory 候选①; "few and precise")
   maxRecallPerSession: 3,
+  // Host-side session-start auto-recall (方案 B): at the FIRST assembly of a
+  // new session, key a bounded BM25 recall off the session's first user message
+  // and inject the top hits as a [RECALL] block — relevant memory reaches the
+  // model even when it never calls engram_recall on its own (the observed gap:
+  // pull-only recall left everything to model initiative and almost never
+  // fired). Pure rule, zero LLM, per-session frozen with the [ENGRAM] block.
+  // "few and precise" — agentmemory 候选①'s lesson from the coding leaderboard.
+  autoRecallOnStart: true,
+  autoRecallLimit: 3,
+  autoRecallMaxChars: 700,
   // [ENGRAM] index budget (token discipline)
   indexMaxLines: 12,
   indexMaxChars: 700,
@@ -282,12 +298,32 @@ export function apply(ctx, config) {
       return "";
     }
     let block = "";
+    let pendingRecall = false;
     try {
       const workspace = resolvePath(cwd);
       block = renderIndex(opened, workspace, cwd, resolved);
+      // Host-side session-start auto-recall (方案 B): append the [RECALL]
+      // block keyed on the session's FIRST user message. The cache only freezes
+      // once there is a query to key on — if the user text isn't in the events
+      // yet (exotic pre-message assemblies), return the index alone and let the
+      // next assembly retry, so a new conversation never permanently misses its
+      // recalled memory.
+      if (resolved.autoRecallOnStart !== false) {
+        const query = firstUserMessageText(session);
+        if (query.length === 0) {
+          pendingRecall = true;
+        } else {
+          const recall = renderStartRecall(opened, workspace, resolved, { query, allowRecencyFallback: false });
+          block = recall.length > 0 ? `${block}\n${recall}`.trim() : block;
+        }
+      }
     } catch (error) {
       log?.warn?.(`engram index render failed: ${String(error)}`);
     }
+    // Never cache a render that skipped auto-recall for lack of an opening
+    // message — the next assembly will have it and can still materialize the
+    // [RECALL] block.
+    if (pendingRecall) return block;
     sessionCache.set(session, block);
     return block;
   };

package/lib/settings.js

@@ -22,6 +22,9 @@ export const SETTINGS_NS = settingsNamespace(SETTINGS_NS_NAME);
 export const SETTINGS_KEYS = [
   "autoCapture",
   "sessionSearch",
+  "recallScope",
+  "autoRecallOnStart",
+  "autoRecallLimit",
   "maxRecallPerSession",
   "autoCapturePerSession",
   "indexMaxLines",
@@ -55,6 +58,9 @@ export function makeSettingsSchema(defaults) {
   return z.object({
     autoCapture: z.boolean().default(defaults.autoCapture),
     sessionSearch: z.boolean().default(defaults.sessionSearch),
+    recallScope: z.union(["workspace", "global"]).default(defaults.recallScope ?? "workspace").description("召回范围：workspace=严格按当前工作区隔离（默认、token 纪律）；global=本工作区命中弱/空时，从其它工作区池按 recency/origin 加权召回并标 [W:<workspace>] 来源。开启会打破跨工作区隔离，请按需选用"),
+    autoRecallOnStart: z.boolean().default(defaults.autoRecallOnStart).description("新会话开始时，宿主按首条消息对工作区做确定性召回，把命中记忆直接注入 [RECALL] 块（无需模型自己想起调 engram_recall；关掉=回到纯拉取）"),
+    autoRecallLimit: z.natural().min(1).max(8).default(defaults.autoRecallLimit).description("[RECALL] 块最多注入的记忆条数（agentmemory 候选①：少而准）"),
     maxRecallPerSession: z.natural().min(1).max(10).default(defaults.maxRecallPerSession),
     autoCapturePerSession: z.natural().max(1000).default(defaults.autoCapturePerSession),
     indexMaxLines: z.natural().max(50).default(defaults.indexMaxLines),