dsh-engram 0.3.5 → 0.3.7

package/lib/api.js

@@ -5,12 +5,14 @@
  * wears the loopback-only trust fence (copied from the SSH family): these
  * routes expose the on-disk memory store, so a LAN-exposed dsh web must not
  * serve them. All reads go straight at the opened storage-domain handle
- * (synchronous after the first open); the two mutations (archive / delete)
- * go through the same store methods the agent tools use.
+ * (synchronous after the first open); the mutations (archive / delete, and
+ * the settings card's PUT /settings) go through the same store methods the
+ * agent tools use (settings writes through the `service.settings` seam).
  */
 
 import { uuid, shortId } from "./util.js";
 import { collectToolCounts, collectUsageStats } from "./usage.js";
+import { SETTINGS_NS } from "./settings.js";
 
 /** Route family prefix (kept in sync with the client half). */
 export const API_PREFIX = "/api/dsh-engram";
@@ -18,6 +20,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 +72,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 +305,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");
@@ -488,6 +543,71 @@ export function makeEngramRoutes(service) {
     writeJson(res, 200, { items: list });
   };
 
+  /** Settings card transport — read the `dsh-engram` namespace through the
+   *  host settings service (see settings.js for the normalized `service.settings`
+   *  seam). Same-origin fetch, like every other route in this family; this is
+   *  what lets the web config card be DSH-generation-agnostic (no
+   *  connection/remote RPC), at the cost of the same loopback/trustedHosts
+   *  fence the memory viewer already wears. */
+  const getSettings = (_req, res) => {
+    const settings = service.settings;
+    if (!settings) {
+      writeError(res, 503, "settings service not available");
+      return;
+    }
+    try {
+      // dsh-settings `describe()` returns a BARE array of namespace descriptors
+      // (in registration order); older adapters may wrap it as {namespaces:[...]}.
+      // Normalize both onto the HTTP contract {namespaces:[...]} the client uses.
+      const payload = settings.describe();
+      const namespaces = Array.isArray(payload) ? payload : (payload?.namespaces ?? []);
+      const view = namespaces.find((n) => n && n.ns === SETTINGS_NS);
+      writeJson(res, 200, view ? { namespaces: [view] } : { namespaces: [] });
+    } catch (error) {
+      writeError(res, 500, String(error?.message ?? error));
+    }
+  };
+
+  /** Settings card transport — mutate the `dsh-engram` namespace. Accepts
+   *  either path ops (`ops: [{op:"set"|"unset", path:[...], value?}]`, the
+   *  exact shape the card used through the RPC) or a plain partial patch
+   *  (`patch: object`). The provider validates and persists through the same
+   *  document the GUI card always wrote to. */
+  const putSettings = async (req, res) => {
+    const settings = service.settings;
+    if (!settings) {
+      writeError(res, 503, "settings service not available");
+      return;
+    }
+    const body = await readJsonBody(req);
+    if (body.error) return writeError(res, 400, body.error);
+    const { ops, patch, expectedRevision } = body.value ?? {};
+    if (!Array.isArray(ops) && !(patch !== null && typeof patch === "object")) {
+      return writeError(res, 400, "body must provide ops (array of {op,path[,value]}) or patch (object)");
+    }
+    try {
+      if (Array.isArray(ops)) {
+        await settings.mutate(SETTINGS_NS, ops, expectedRevision);
+      } else {
+        await settings.update(SETTINGS_NS, patch, expectedRevision);
+      }
+      writeJson(res, 200, { ok: true });
+    } catch (error) {
+      if (error?.code === "SETTINGS_CONFLICT" || error?.name === "SettingsConflictError") {
+        writeJson(res, 409, {
+          error: {
+            code: "SETTINGS_CONFLICT",
+            message: String(error?.message ?? "settings moved since read"),
+            expected: error?.expected,
+            actual: error?.actual,
+          },
+        });
+        return;
+      }
+      writeError(res, 400, String(error?.message ?? error));
+    }
+  };
+
   const make = (method, path, handler) => ({
     kind: "exact",
     path: `${API_PREFIX}${path}`,
@@ -532,9 +652,12 @@ export function makeEngramRoutes(service) {
     make("GET", "/model", model),
     make("GET", "/preview", preview),
     make("GET", "/config", readConfig),
+    makeUnion("/settings", { GET: getSettings, PUT: putSettings }),
     make("POST", "/memories/archive", archive),
     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

@@ -153,6 +153,34 @@ var EngramApi = class {
       })
     );
   }
+  /** Settings card transport — read the `dsh-engram` namespace through our
+   *  own HTTP API instead of the host connection/remote RPC. */
+  async getSettings() {
+    return readJson(await fetch(`${API_PREFIX}/settings`));
+  }
+  /** Settings card transport — persist one or more path ops into the
+   *  `dsh-engram` namespace. Non-2xx surfaces the server's message. */
+  async updateSettings(ops, expectedRevision) {
+    const response = await fetch(`${API_PREFIX}/settings`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        ops,
+        ...expectedRevision !== void 0 ? { expectedRevision } : {}
+      })
+    });
+    let body = null;
+    try {
+      body = await response.json();
+    } catch {
+    }
+    if (!response.ok) {
+      const err = body;
+      const message = typeof err?.error === "string" ? err.error : typeof err?.error === "object" && err.error !== null && typeof err.error.message === "string" ? err.error.message : `HTTP ${response.status}`;
+      throw new EngramApiError(message);
+    }
+    return body ?? { ok: true };
+  }
 };
 
 // client/src/EngramTaskDock.tsx
@@ -3341,6 +3369,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 +3381,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 +3682,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",
           {
@@ -3812,14 +3852,7 @@ var EngramScopeImpl = class {
     this.snapshot = LOADING;
     this.notify();
     try {
-      const response = await this.api.settings.describe({});
-      const result = response?.result;
-      if (!result || result.ok !== true) {
-        const err = result && "error" in result ? result.error : { code: "settings.describe", message: "unreachable" };
-        this.fail(`settings.describe failed: ${String(err?.code ?? err)}: ${String(err?.message ?? "")}`);
-        return;
-      }
-      const payload = result.value;
+      const payload = await this.api.getSettings();
       const view = payload.namespaces?.find((n) => n.ns === this.ns);
       if (!view) {
         this.fail(`the '${this.ns}' settings namespace is not served by this host.`);
@@ -3833,27 +3866,16 @@ var EngramScopeImpl = class {
         base: view.base ?? view.value,
         user: view.user,
         revision: view.revision ?? 0,
-        writable: this.opts.writable !== false && payload.writable !== false && applied
+        writable: this.opts.writable !== false && applied
       };
       this.notify();
     } catch (error) {
-      this.fail(`settings.describe threw: ${String(error instanceof Error ? error.message : error)}`);
+      this.fail(`settings fetch failed: ${String(error instanceof Error ? error.message : error)}`);
     }
   }
   async mutate(op) {
     const revision = this.snapshot.revision;
-    const response = await this.api.settings.mutate({
-      ns: this.ns,
-      ops: [op],
-      ...revision ? { expectedRevision: revision } : {}
-    });
-    const result = response?.result;
-    if (!result || result.ok !== true) {
-      const err = result && "error" in result ? result.error : { code: "settings.mutate", message: "unreachable" };
-      throw new Error(`settings.mutate failed: ${String(err?.code ?? err)}: ${String(err?.message ?? "")}`);
-    }
-    const view = result.value;
-    if (view) this.snapshot = { ...this.snapshot, revision: view.revision ?? revision };
+    await this.api.updateSettings([op], revision > 0 ? revision : void 0);
   }
   async set(key, value) {
     await this.mutate({ op: "set", path: [String(key)], value });
@@ -4912,7 +4934,7 @@ var en = {
   refresh: "Refresh",
   error: "Load failed"
 };
-var inject = ["slots", "locale", "connection", "sessions", "workspaces"];
+var inject = ["slots", "locale", "sessions", "workspaces"];
 function apply(ctx) {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-engram: dictionaries");
   const api = new EngramApi();
@@ -4953,8 +4975,7 @@ function apply(ctx) {
   } catch (error) {
     console.warn("[dsh-engram] settings.section registration failed:", error);
   }
-  const connection = ctx.get("connection");
-  const scope = new EngramScopeImpl(connection.api, "dsh-engram");
+  const scope = new EngramScopeImpl(api, "dsh-engram");
   const cardInjected = () => ({ scope });
   try {
     ctx.slots.inject(

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,
@@ -242,7 +258,7 @@ export function apply(ctx, config) {
 
   // User settings (web GUI card): merges stored values onto the live config.
   // Non-blocking — when the settings service is absent this never runs.
-  installEngramSettings(ctx, resolved, resolved);
+  installEngramSettings(ctx, resolved, resolved, service);
 
   // Web API for the GUI: deferred on the webServer service, so headless
   // profiles keep running the plugin without it. `register` returns the
@@ -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

@@ -12,16 +12,20 @@
  */
 
 import z from "@deepseek-ai/schemastery";
-import { settingsNamespace, installSettingsSection } from "@deepseek-ai/dsh-settings";
 
 /** Namespace join key — must match the client card's `key`. */
 export const SETTINGS_NS_NAME = "dsh-engram";
-export const SETTINGS_NS = settingsNamespace(SETTINGS_NS_NAME);
+// dsh-settings 0.1.5 exposes the namespace as a validated string at the
+// provider boundary; the legacy branding helper was removed.
+export const SETTINGS_NS = SETTINGS_NS_NAME;
 
 /** Fields the GUI exposes (a curated subset of the plugin DEFAULTS). */
 export const SETTINGS_KEYS = [
   "autoCapture",
   "sessionSearch",
+  "recallScope",
+  "autoRecallOnStart",
+  "autoRecallLimit",
   "maxRecallPerSession",
   "autoCapturePerSession",
   "indexMaxLines",
@@ -55,6 +59,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),
@@ -80,30 +87,49 @@ export function makeSettingsSchema(defaults) {
 /**
  * Wire the settings section into `ctx` and keep `live` (the plugin's mutable
  * config object) merged with what the user stored. Called from `apply()`.
+ *
+ * When a `service` object is supplied, a normalized `service.settings` seam
+ * ({ describe, mutate, update }) is exposed for the web API — this is the
+ * single host-side adapter point: both the current and the legacy DSH
+ * settings APIs reduce onto the same three calls, so `/api/dsh-engram/settings`
+ * never needs to know which generation it is talking to.
  */
-export function installEngramSettings(ctx, defaults, live) {
+export function installEngramSettings(ctx, defaults, live, service) {
   const base = settingsBaseFrom(defaults);
   const schema = makeSettingsSchema(defaults);
   let source = () => base;
-  installSettingsSection(ctx, SETTINGS_NS, schema, base, {
-    setSource(current) {
-      source = current;
-    },
-    onChange() {
-      let value;
-      try {
-        value = source();
-      } catch {
-        return;
-      }
-      if (value === null || typeof value !== "object") return;
-      for (const key of SETTINGS_KEYS) {
-        if (value[key] !== void 0 && live[key] !== value[key]) live[key] = value[key];
-      }
-    },
-    validate(value) {
-      // The schema already constrains every exposed field; refuse nothing here.
-      void value;
-    },
+  ctx.inject(["settings"], (settingsCtx) => {
+    // dsh-settings 0.1.5 moved the optional-consumer wiring onto the provider
+    // instance. Keeping the registration on the scoped context preserves the
+    // provider attach/detach lifecycle while avoiding a removed helper export.
+    const provider = settingsCtx.settings;
+    if (service) {
+      service.settings = {
+        describe: () => provider.describe({ redactSecrets: true }),
+        mutate: (ns, ops, expectedRevision) => provider.mutate(ns, ops, expectedRevision),
+        update: (ns, patch, expectedRevision) => provider.update(ns, patch, expectedRevision),
+      };
+    }
+    provider.installSection(ctx, SETTINGS_NS, schema, base, {
+      setSource(current) {
+        source = current;
+      },
+      onChange() {
+        let value;
+        try {
+          value = source();
+        } catch {
+          return;
+        }
+        if (value === null || typeof value !== "object") return;
+        for (const key of SETTINGS_KEYS) {
+          if (value[key] !== void 0 && live[key] !== value[key]) live[key] = value[key];
+        }
+      },
+      validate(value) {
+        // The schema already constrains every exposed field; refuse nothing here.
+        void value;
+      },
+    });
   });
 }