dsh-engram 0.3.5 → 0.3.6

package/lib/store.js

@@ -69,6 +69,10 @@ const MemorySchema = z.object({
   supersedes: z.string().nullable().default(null),
   /** Memory id this row directly contradicts (conflicting claim, keep both). */
   contradicts: z.string().nullable().default(null),
+  /** Optional provenance source class: manual | session | report | upstream | handoff. */
+  source: z.string().nullable().default(null),
+  /** Optional trigger/condition under which this memory should be recalled. */
+  conditions: z.string().nullable().default(null),
 });
 
 const TaskSchema = z.object({
@@ -506,6 +510,8 @@ export async function openEngramDomain(facility) {
         status: "active",
         supersedes,
         contradicts,
+        source: entry.source ?? null,
+        conditions: entry.conditions ?? null,
         expiresAt,
       };
       await memories.put(stored.id, stored);
@@ -545,6 +551,58 @@ export async function openEngramDomain(facility) {
       }
       return active.sort(byRecency).slice(0, bounded);
     },
+    /**
+     * Optional cross-workspace recall (issue #5, recallScope: "global").
+     * Ranks across EVERY workspace's active pool with the same deterministic
+     * BM25 scorer, then applies a small origin penalty so an out-of-workspace
+     * hit needs meaningfully stronger lexical relevance to displace an
+     * in-workspace one. Results are annotated with `_origin` (the workspace key)
+     * so the tools layer can surface a [W:<workspace>] marker — the model then
+     * knows the context a cross-workspace entry came from. Default strictly
+     * preserves per-workspace isolation; this is only invoked when the caller
+     * opts in (config recallScope="global" or an explicit scope="global" call).
+     */
+    recallGlobal(query, limit = 20, { maxPerSession, excludeWorkspace } = {}) {
+      const bounded = Math.max(1, Math.min(50, Math.trunc(limit) || 20));
+      let pool = [...memories.entries()].map(([, m]) => m).filter((m) => m.status === "active").filter(notExpiredNow);
+      if (excludeWorkspace !== void 0 && excludeWorkspace !== null) {
+        pool = pool.filter((m) => m.workspace !== excludeWorkspace);
+      }
+      if (pool.length === 0) return [];
+      // Tag every row with its origin workspace for the display layer.
+      const tagged = pool.map((m) => ({ ...m, _origin: m.workspace }));
+      const trimmed = String(query ?? "").trim();
+      const half = Math.max(1, bounded * 3);
+      let ranked;
+      if (trimmed.length === 0) {
+        ranked = tagged.sort(byRecency).slice(0, bounded);
+      } else {
+        ranked = bm25Rank(tagged, trimmed, half);
+      }
+      // Origin penalty: an out-of-workspace hit is discounted by 20% (a
+      // same-workspace entry with comparable relevance wins ties). bm25Rank
+      // drops its internal score, but the returned order is monotonic in it;
+      // we only re-stabilize near-equal neighbours so cross-workspace hits
+      // never displace an equally-relevant in-workspace one.
+      if (excludeWorkspace !== void 0 && excludeWorkspace !== null && ranked.length > 1) {
+        ranked = ranked.slice().sort((a, b) => {
+          const crossA = (a._origin ?? a.workspace) !== excludeWorkspace;
+          const crossB = (b._origin ?? b.workspace) !== excludeWorkspace;
+          if (crossA === crossB) return 0;
+          return crossA ? 1 : -1; // same-workspace first within ties
+        });
+      }
+      const out = [];
+      const seen = new Set();
+      for (const m of ranked) {
+        if (seen.has(m.id)) continue;
+        seen.add(m.id);
+        out.push(m);
+        if (out.length >= bounded) break;
+      }
+      if (maxPerSession !== void 0 && maxPerSession !== null) return dedupeBySession(out, maxPerSession);
+      return out;
+    },
     /**
      * Memory-to-memory relation lookup maps for a workspace (deterministic):
      *   supersededBy: id -> { newer } (a row marked m.supersedes === id)
@@ -971,6 +1029,235 @@ export async function openEngramDomain(facility) {
       await entities.delete(id);
       return true;
     },
+    // ── export / import (data contract, format "dsh-engram/export" v1) ─
+    /**
+     * Dump every row of the four memory tables — including archived memories /
+     * tasks — so a backup or migration never loses provenance. `workspace`
+     * restricts to one workspace; falsy dumps every workspace. The dump is the
+     * plain contract a consumer (or a future dsh release) can round-trip back
+     * through `importAll` — it carries `meta.format` + `meta.version` so
+     * forwards-incompatible formats can be rejected by the importer.
+     */
+    exportAll(workspace) {
+      const pick = (table) => [...table.entries()].map(([, v]) => v).filter((v) => v.workspace === workspace);
+      const all = workspace
+        ? { memories: pick(memories), tasks: pick(tasks), links: pick(links), entities: pick(entities) }
+        : {
+            memories: [...memories.entries()].map(([, v]) => v),
+            tasks: [...tasks.entries()].map(([, v]) => v),
+            links: [...links.entries()].map(([, v]) => v),
+            entities: [...entities.entries()].map(([, v]) => v),
+          };
+      return {
+        meta: { format: "dsh-engram/export", version: 1, exportedAt: now(), workspace: workspace ?? null },
+        ...all,
+      };
+    },
+    /**
+     * Restore a dump produced by `exportAll` (same format/version), honoring
+     * the same write-path invariants as `storeMemory`: memory text is run
+     * through the deterministic secret redactor before it can land on disk.
+     *
+     * Modes:
+     *   - `merge` (default) — idempotent: writes only rows whose id is absent,
+     *     kept per-row (each row keeps its own `workspace`).
+     *   - `replace` — wipes the given `workspace` from all four tables first,
+     *     then writes only rows belonging to it (a full restore; the caller
+     *     owns the destructive step).
+     *
+     * Bad rows never abort the whole import: structural/validation failures
+     * (missing id/workspace, empty text, text over the char cap, id already
+     * present in merge, workspace memory cap in merge) are skipped and listed
+     * in the report. `dryRun: true` computes the identical plan without
+     * writing a single row.
+     *
+     * @param payload - the dump (`{ meta?, memories?, tasks?, links?, entities? }`).
+     * @param opts - `{ mode, dryRun, workspace, config }` (workspace mandatory for replace).
+     * @returns { mode, dryRun, written: {table: n}, skipped: [{table,id,reason}] }
+     */
+    async importAll(payload, { mode = "merge", dryRun = false, workspace, config } = {}) {
+      if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new EngramError("ENGRAM_INVALID_ARGS", "import payload must be an object (a dsh-engram/export dump)");
+      }
+      if (mode !== "merge" && mode !== "replace") {
+        throw new EngramError("ENGRAM_INVALID_ARGS", "import mode must be 'merge' or 'replace'");
+      }
+      if (mode === "replace" && (typeof workspace !== "string" || workspace.length === 0)) {
+        throw new EngramError("ENGRAM_INVALID_ARGS", "replace mode requires the workspace to restore into");
+      }
+      const maxMemoryChars = config?.maxMemoryChars ?? 1600;
+      const maxPerWs = config?.maxMemoriesPerWorkspace ?? 2000;
+      const tables = {
+        memories: Array.isArray(payload.memories) ? payload.memories : [],
+        tasks: Array.isArray(payload.tasks) ? payload.tasks : [],
+        links: Array.isArray(payload.links) ? payload.links : [],
+        entities: Array.isArray(payload.entities) ? payload.entities : [],
+      };
+      const written = { memories: 0, tasks: 0, links: 0, entities: 0 };
+      const skipped = [];
+      const rowTable = (name) => ({ memories, tasks, links, entities })[name];
+      const rowsOf = (table, ws) => [...table.entries()].map(([, v]) => v).filter((v) => v.workspace === ws);
+
+      // Destructive mode: drop every row of the target workspace up front
+      // (planned under dryRun, executed otherwise).
+      if (mode === "replace") {
+        for (const [name, table] of Object.entries({ memories, tasks, links, entities })) {
+          for (const row of rowsOf(table, workspace)) {
+            if (!dryRun) await table.delete(row.id);
+          }
+        }
+      }
+
+      // Per-workspace running count of ACTIVE memories — the invariant the
+      // workspace cap protects (index-block size); archived rows never count,
+      // and the cap is per workspace, not global.
+      const activeByWs = new Map();
+      for (const [, m] of memories.entries()) {
+        if (m.status === "active") activeByWs.set(m.workspace, (activeByWs.get(m.workspace) ?? 0) + 1);
+      }
+
+      const putRow = async (name, key, row) => {
+        if (!dryRun) await rowTable(name).put(key, row);
+      };
+
+      // Schema defaults, mirroring storeMemory / the zod schemas: an imported
+      // row must behave exactly like one that went through the live write path
+      // (listMemories/recall only see status==="active", tasks need a state,
+      // etc.) — so absent optional fields get their canonical default, never
+      // `undefined`.
+      const normalizeMemory = (row, key, ws, text) => ({
+        kind: row.kind ?? "fact",
+        tags: Array.isArray(row.tags) ? row.tags.slice() : [],
+        entity: row.entity ?? null,
+        seq: Number.isFinite(row.seq) ? row.seq : 0,
+        ...row,
+        id: key,
+        workspace: ws,
+        text,
+        status: row.status ?? "active",
+        hits: Number.isFinite(row.hits) ? row.hits : 0,
+        lastAccessAt: row.lastAccessAt ?? null,
+        filePath: row.filePath ?? null,
+        signal: typeof row.signal === "number" ? row.signal : 0.5,
+        supersedes: row.supersedes ?? null,
+        contradicts: row.contradicts ?? null,
+        source: row.source ?? null,
+        conditions: row.conditions ?? null,
+        expiresAt: row.expiresAt ?? null,
+        sessionId: row.sessionId ?? "import",
+        createdAt: Number.isFinite(row.createdAt) ? row.createdAt : now(),
+        updatedAt: Number.isFinite(row.updatedAt) ? row.updatedAt : now(),
+      });
+      const normalizeTask = (row, key, ws) => ({
+        ...row,
+        id: key,
+        workspace: ws,
+        state: row.state ?? "draft",
+        artifact: row.artifact ?? null,
+        evaluation: row.evaluation ?? null,
+        memoryRefs: Array.isArray(row.memoryRefs) ? row.memoryRefs.slice() : [],
+        deps: Array.isArray(row.deps) ? row.deps.slice() : [],
+        assignee: row.assignee ?? null,
+        claimedAt: row.claimedAt ?? null,
+        stateChangedAt: Number.isFinite(row.stateChangedAt) ? row.stateChangedAt : 0,
+        archivedAt: row.archivedAt ?? null,
+        sessionId: row.sessionId ?? "import",
+        createdAt: Number.isFinite(row.createdAt) ? row.createdAt : now(),
+        updatedAt: Number.isFinite(row.updatedAt) ? row.updatedAt : now(),
+      });
+      const normalizeLink = (row, key, ws) => ({
+        ...row,
+        id: key,
+        workspace: ws,
+        relation: row.relation ?? "relates-to",
+        confidence: typeof row.confidence === "number" ? row.confidence : 1,
+        sessionId: row.sessionId ?? "import",
+        createdAt: Number.isFinite(row.createdAt) ? row.createdAt : now(),
+      });
+      const normalizeEntity = (row, key, ws) => ({
+        ...row,
+        id: key,
+        workspace: ws,
+        description: row.description ?? "",
+        kind: row.kind ?? "",
+        sessionId: row.sessionId ?? "import",
+        createdAt: Number.isFinite(row.createdAt) ? row.createdAt : now(),
+        updatedAt: Number.isFinite(row.updatedAt) ? row.updatedAt : now(),
+      });
+
+      for (const row of tables.memories) {
+        const key = typeof row?.id === "string" && row.id.length > 0 ? row.id : "";
+        const ws = typeof row?.workspace === "string" && row.workspace.length > 0 ? row.workspace : workspace;
+        if (key === "") {
+          skipped.push({ table: "memories", id: null, reason: "missing id" });
+          continue;
+        }
+        if (mode === "merge" && memories.get(key) !== void 0) {
+          skipped.push({ table: "memories", id: key, reason: "exists" });
+          continue;
+        }
+        if (typeof ws !== "string" || ws.length === 0) {
+          skipped.push({ table: "memories", id: key, reason: "missing workspace" });
+          continue;
+        }
+        if (mode === "replace" && ws !== workspace) {
+          skipped.push({ table: "memories", id: key, reason: "outside restored workspace" });
+          continue;
+        }
+        const text = redactText(String(row.text ?? "")).trim();
+        if (text.length === 0) {
+          skipped.push({ table: "memories", id: key, reason: "empty text" });
+          continue;
+        }
+        if ([...text].length > maxMemoryChars) {
+          skipped.push({ table: "memories", id: key, reason: "over maxMemoryChars" });
+          continue;
+        }
+        if (mode === "merge" && (row.status ?? "active") === "active" && (activeByWs.get(ws) ?? 0) >= maxPerWs) {
+          skipped.push({ table: "memories", id: key, reason: "workspace memory cap" });
+          continue;
+        }
+        if ((row.status ?? "active") === "active") activeByWs.set(ws, (activeByWs.get(ws) ?? 0) + 1);
+        try {
+          await putRow("memories", key, normalizeMemory(row, key, ws, text));
+          written.memories += 1;
+        } catch (error) {
+          skipped.push({ table: "memories", id: key, reason: `invalid row: ${String(error?.message ?? error)}` });
+        }
+      }
+
+      for (const [name, rows] of Object.entries({ tasks: tables.tasks, links: tables.links, entities: tables.entities })) {
+        for (const row of rows) {
+          const key = typeof row?.id === "string" && row.id.length > 0 ? row.id : "";
+          if (key === "") {
+            skipped.push({ table: name, id: null, reason: "missing id" });
+            continue;
+          }
+          if (mode === "merge" && rowTable(name).get(key) !== void 0) {
+            skipped.push({ table: name, id: key, reason: "exists" });
+            continue;
+          }
+          const ws = typeof row?.workspace === "string" && row.workspace.length > 0 ? row.workspace : workspace;
+          if (typeof ws !== "string" || ws.length === 0) {
+            skipped.push({ table: name, id: key, reason: "missing workspace" });
+            continue;
+          }
+          if (mode === "replace" && ws !== workspace) {
+            skipped.push({ table: name, id: key, reason: "outside restored workspace" });
+            continue;
+          }
+          const normalize = { tasks: normalizeTask, links: normalizeLink, entities: normalizeEntity }[name];
+          try {
+            await putRow(name, key, normalize(row, key, ws));
+            written[name] += 1;
+          } catch (error) {
+            skipped.push({ table: name, id: key, reason: `invalid row: ${String(error?.message ?? error)}` });
+          }
+        }
+      }
+
+      return { mode, dryRun, written, skipped };
+    },
     // ── usage / observability ────────────────────────────────────────
     /** Merge one tool-call event into the (workspace, day) rollup row. */
     async bumpUsage(workspace, day, { counts = {}, failures = 0, recall = {} }) {

package/lib/tools.js

@@ -16,6 +16,7 @@
  */
 
 import { z } from "zod";
+import { basename } from "node:path";
 import { EngramError, hasCode } from "./store.js";
 import { buildEsrStatusView } from "./index-block.js";
 import { truncate, shortId, slugId, fmtDate, escapeLt, workspaceKey as wk, uuid } from "./util.js";
@@ -74,7 +75,12 @@ async function requireDomain(service) {
   }
 }
 
-function memoryLine(m, verbosity = "short", rel) {
+function memoryLine(m, verbosity = "short", rel, homeWs) {
+  // origin marker for cross-workspace hits: [W:<ws>] tells the model the memory
+  // came from a different workspace pool (issue #5).
+  const origin = homeWs !== void 0 && homeWs !== null && (m._origin ?? m.workspace) !== homeWs
+    ? ` [W:${basename(m._origin ?? m.workspace) || String(m._origin ?? m.workspace)}]`
+    : "";
   const tags = m.entity !== null ? ` · entity:${m.entity}` : "";
   const relTail = rel
     ? `${rel.supersededBy.has(m.id) ? ` · superseded by ${rel.supersededBy.get(m.id).id.slice(0, 8)}` : ""}${rel.contradictedBy.has(m.id) ? ` · contradicted by ${rel.contradictedBy.get(m.id).map((c) => c.id.slice(0, 8)).join(",")}` : ""}`
@@ -83,11 +89,13 @@ function memoryLine(m, verbosity = "short", rel) {
     const access = m.lastAccessAt == null ? "never-accessed" : `lastAccess ${fmtDate(m.lastAccessAt)}`;
     const pathLine = m.filePath ? ` · path ${m.filePath}` : "";
     const relLine = relTail.length > 0 ? relTail.trim() : "";
-    return [`# ${m.id} [${m.kind}]`, escapeLt(m.text), `tags: ${(m.tags ?? []).join(", ")}${tags}`, `signal ${m.signal} · hits ${m.hits ?? 0} · ${fmtDate(m.createdAt)} · session ${m.sessionId}#${m.seq} · ${access}${pathLine}${relLine ? ` · ${relLine}` : ""}`, ""].join("\n");
+    const sourceLine = m.source ? ` · source ${m.source}` : "";
+    const condLine = m.conditions ? ` · conditions ${m.conditions}` : "";
+    return [`# ${m.id} [${m.kind}]${origin}`, escapeLt(m.text), `tags: ${(m.tags ?? []).join(", ")}${tags}`, `signal ${m.signal} · hits ${m.hits ?? 0} · ${fmtDate(m.createdAt)} · session ${m.sessionId}#${m.seq} · ${access}${pathLine}${relLine ? ` · ${relLine}` : ""}${sourceLine}${condLine}`, ""].join("\n");
   }
   const date = fmtDate(m.createdAt ?? m.updatedAt);
   const path = m.filePath ? ` · ${truncate(m.filePath, 48)}` : "";
-  return `- ${m.id.slice(0, 8)} [${m.kind}] ${date} ${escapeLt(truncate(m.text, 200))}${tags}${m.hits > 0 ? ` · ×${m.hits}` : ""}${path}${relTail}`;
+  return `- ${m.id.slice(0, 8)} [${m.kind}]${origin} ${date} ${escapeLt(truncate(m.text, 200))}${tags}${m.hits > 0 ? ` · ×${m.hits}` : ""}${path}${relTail}`;
 }
 
 /** Stable kind display order for grouped recall output (matches MEMORY_KINDS). */
@@ -100,7 +108,7 @@ const MEMORY_KIND_ORDER = ["decision", "error", "procedure", "fact", "insight",
  * Within a group the original (relevance) order is preserved; unknown kinds
  * (future-proof) trail the fixed order. Pure, deterministic.
  */
-function groupKindLines(items, rel) {
+function groupKindLines(items, rel, homeWs) {
   const buckets = new Map();
   for (const m of items) {
     const kind = typeof m.kind === "string" && m.kind.length > 0 ? m.kind : "unknown";
@@ -110,7 +118,7 @@ function groupKindLines(items, rel) {
   const lines = [];
   const emit = (kind, group) => {
     lines.push(`## ${kind} (${group.length})`);
-    for (const m of group) lines.push(memoryLine(m, "short", rel));
+    for (const m of group) lines.push(memoryLine(m, "short", rel, homeWs));
   };
   for (const kind of MEMORY_KIND_ORDER) if (buckets.has(kind)) emit(kind, buckets.get(kind));
   for (const [kind, group] of buckets) if (!MEMORY_KIND_ORDER.includes(kind)) emit(kind, group);
@@ -136,12 +144,14 @@ export function registerTools(ctx, service) {
             file_path: { type: "string", description: "Optional absolute path this memory anchors to (e.g. the failing file)" },
             supersedes: { type: "string", description: "Optional memory id this new statement replaces (old row stays, demoted in recall)" },
             contradicts: { type: "string", description: "Optional memory id this new statement directly contradicts (both stay, flagged)" },
+            source: { type: "string", description: "Optional provenance source class: manual | session | report | upstream | handoff" },
+            conditions: { type: "string", description: "Optional trigger/condition under which this memory should be recalled" },
           },
           required: ["text"],
         },
         output: TEXT_OUTPUT,
         execute: async (raw, exec) => {
-          const args = parse(z.object({ text: z.string().min(1).max(2000), kind: z.enum(KINDS).optional(), tags: z.array(z.string()).optional(), entity: z.string().optional(), file_path: z.string().optional(), supersedes: z.string().optional(), contradicts: z.string().optional() }), raw, "engram_store");
+          const args = parse(z.object({ text: z.string().min(1).max(2000), kind: z.enum(KINDS).optional(), tags: z.array(z.string()).optional(), entity: z.string().optional(), file_path: z.string().optional(), supersedes: z.string().optional(), contradicts: z.string().optional(), source: z.string().optional(), conditions: z.string().optional() }), raw, "engram_store");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           await domain.expireSweep(caller.cwd);
@@ -155,6 +165,8 @@ export function registerTools(ctx, service) {
               filePath: args.file_path ?? null,
               supersedes: args.supersedes ?? null,
               contradicts: args.contradicts ?? null,
+              source: args.source ?? null,
+              conditions: args.conditions ?? null,
               sessionId: caller.sessionId,
               seq: caller.seq,
               signal: 0.6,
@@ -180,12 +192,13 @@ export function registerTools(ctx, service) {
             max_per_session: { type: "integer", minimum: 1, maximum: 10, description: "Max memories kept per sessionId (default 3; sessions share the cap)" },
             group_by_kind: { type: "boolean", description: "Group recall hits by kind into sections (default true); false = one flat list" },
             search_sessions: { type: "boolean", description: "Also FTS search past sessions (requires the session-query index)" },
+            scope: { type: "string", enum: ["workspace", "global", "auto"], description: "Recall scope override: workspace=strict current-workspace only (default); global=include other workspaces' pools when the local pool is weak/empty (marks [W:<ws>] origin); auto=follow the recallScope config (recommended)" },
           },
         },
         output: TEXT_OUTPUT,
         timeoutMs: 30000,
         execute: async (raw, exec) => {
-          const args = parse(z.object({ query: z.string().optional(), entity: z.string().optional(), limit: z.number().int().min(1).max(50).optional(), max_per_session: z.number().int().min(1).max(10).optional(), group_by_kind: z.boolean().optional(), search_sessions: z.boolean().optional() }), raw, "engram_recall");
+          const args = parse(z.object({ query: z.string().optional(), entity: z.string().optional(), limit: z.number().int().min(1).max(50).optional(), max_per_session: z.number().int().min(1).max(10).optional(), group_by_kind: z.boolean().optional(), search_sessions: z.boolean().optional(), scope: z.enum(["workspace", "global", "auto"]).optional() }), raw, "engram_recall");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           let lines = [];
@@ -194,6 +207,11 @@ export function registerTools(ctx, service) {
           // reuses DSH's own cross-session index (ctx.sessionQuery) instead of
           // a self-built index — this keeps proactive coverage without new infra.
           let zeroHits = false;
+          // recallScope resolution: explicit scope wins; else the config knob;
+          // default "workspace" preserves the strict per-workspace isolation.
+          const cfgScope = service.config.recallScope ?? "workspace";
+          const effectiveScope = args.scope === void 0 ? cfgScope : args.scope === "auto" ? cfgScope : args.scope;
+          const globalEnabled = effectiveScope === "global";
           if (args.entity !== void 0 && args.entity.trim().length > 0) {
             items = domain.timeline(caller.cwd, args.entity, args.limit ?? 30);
             if (items.length === 0) zeroHits = true;
@@ -202,11 +220,25 @@ export function registerTools(ctx, service) {
             await Promise.all(items.map((m) => domain.touchMemory(caller.cwd, m.id).catch(() => null)));
           } else if (args.query !== void 0) {
             const maxPerSession = args.max_per_session ?? service.config.maxRecallPerSession ?? 3;
-            items = domain.recall(caller.cwd, args.query, args.limit ?? 12, { maxPerSession });
+            const limit = args.limit ?? 12;
+            items = domain.recall(caller.cwd, args.query, limit, { maxPerSession });
+            let cross = false;
+            // Opt-in global fallback (issue #5): only when the local pool is
+            // weak/no-hit AND the user enabled recallScope=global or passed
+            // scope=global. Cross-workspace hits carry a [W:<ws>] origin marker.
+            if (globalEnabled && items.length === 0) {
+              const extra = domain.recallGlobal(args.query, limit, { maxPerSession, excludeWorkspace: caller.cwd });
+              if (extra.length > 0) {
+                items = extra;
+                cross = true;
+              }
+            }
             if (items.length === 0) zeroHits = true;
-            lines.push(zeroHits ? `no active memories match ${JSON.stringify(args.query)} in this workspace` : `# recall: ${JSON.stringify(args.query)} (${items.length}) · ≤${maxPerSession}/session`);
+            const scopeTag = cross ? " · cross-workspace" : "";
+            lines.push(zeroHits ? `no active memories match ${JSON.stringify(args.query)} in this workspace` + (globalEnabled ? " (global fallback also empty)" : "") : `# recall: ${JSON.stringify(args.query)} (${items.length}) · ≤${maxPerSession}/session${scopeTag}`);
             const rel = domain.memoryRelations(caller.cwd);
-            lines.push(...(args.group_by_kind === false ? items.map((m) => memoryLine(m, "short", rel)) : groupKindLines(items, rel)));
+            const homeWs = caller.cwd;
+            lines.push(...(args.group_by_kind === false ? items.map((m) => memoryLine(m, "short", rel, homeWs)) : groupKindLines(items, rel, homeWs)));
             await Promise.all(items.map((m) => domain.touchMemory(caller.cwd, m.id).catch(() => null)));
           } else {
             items = domain.listMemories(caller.cwd, args.limit ?? 12);
@@ -228,7 +260,7 @@ export function registerTools(ctx, service) {
           const wantSessions = args.search_sessions === true || (zeroHits && service.config.sessionSearch !== false);
           if (wantSessions) {
             const q = args.query ?? args.entity ?? "";
-            const extra = await searchSessions(service, caller, q, exec.signal);
+            const extra = await searchSessions(service, caller, q, exec.signal, globalEnabled);
             if (extra.length > 0) {
               lines.push("", "# past sessions (FTS fallback)", ...extra);
             } else if (hasCJK(q)) {
@@ -750,15 +782,17 @@ function collectNeighborhood(domain, workspace, items) {
   return lines;
 }
 
-/** FTS over past sessions via ctx.sessionQuery (mounted by the web profile). */
-async function searchSessions(service, caller, query, signal) {
+/** FTS over past sessions via ctx.sessionQuery (mounted by the web profile).
+ *  `global` (recallScope=global) drops the cwd filter so past-session hits from
+ *  other workspaces are reachable too — matching the cross-workspace scope. */
+async function searchSessions(service, caller, query, signal, global) {
   const sq = service.sessionQuery;
   if (sq === void 0 || query.trim().length === 0) return [];
   try {
     const { items = [] } = await sq.searchSessions(
       {
         query: query.trim(),
-        sessionFilters: [{ kind: "cwd", values: [caller.cwd] }],
+        sessionFilters: global ? [] : [{ kind: "cwd", values: [caller.cwd] }],
         limit: 5,
       },
       signal !== void 0 ? { signal } : undefined,

package/lib/usage.js

@@ -11,13 +11,19 @@
  * with a short TTL cache. No tool call pays a write anymore (pure GUI-side
  * observability), and the log stream is the single source of truth.
  *
- * Zero-dependency: the host already carries the `zstd` CLI.
+ * Zero external dependency: Node >=22.19 provides the zstd codec in
+ * `node:zlib`. Session logs are concatenated zstd frames (each append is an
+ * independent frame), so we scan frame boundaries and reuse one decoder
+ * handle across all frames instead of relying on a system `zstd` CLI (which
+ * Windows hosts commonly lack) or the one-shot `zstdDecompressSync`, which
+ * only decodes the FIRST frame of a multi-frame container.
  */
 
-import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { constants as bufferConstants } from "node:buffer";
+import { createZstdDecompress, zstdDecompressSync } from "node:zlib";
 
 import { workspaceKey as wk } from "./util.js";
 
@@ -28,8 +34,6 @@ export function dayKey(now = Date.now()) {
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
 }
 
-/** A big session log far exceeds Node's 1MB default exec buffer. */
-const MAX_BYTES = 300 * 1024 * 1024;
 const CACHE_TTL_MS = 60_000;
 const DAY_MS = 86_400_000;
 
@@ -40,9 +44,146 @@ export function sessionsRoot() {
   return path.join(os.homedir(), ".dsh", "sessions");
 }
 
+/** Byte range of one structurally complete zstd frame in a concatenated stream. */
+function frameRanges(buffer) {
+  const frames = [];
+  let offset = 0;
+  while (offset < buffer.length) {
+    const start = offset;
+    if (buffer.length - offset < 4) break;
+    if (buffer.readUInt32LE(offset) !== 0xfd2fb528) break; // ZSTD_MAGIC
+    offset += 4;
+    if (offset === buffer.length) break;
+    const descriptor = buffer.readUInt8(offset);
+    offset += 1;
+    if ((descriptor & 0x18) !== 0) break; // reserved frame-header bit
+    const contentSizeFlag = descriptor >>> 6;
+    const singleSegment = (descriptor & 0x20) !== 0;
+    const checksum = (descriptor & 0x04) !== 0;
+    const dictionaryFlag = descriptor & 0x03;
+    const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+    const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag;
+    const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+    if (buffer.length - offset < remainingHeaderBytes) break;
+    offset += remainingHeaderBytes;
+    for (;;) {
+      if (buffer.length - offset < 3) return frames;
+      const blockHeader = buffer.readUIntLE(offset, 3);
+      offset += 3;
+      const lastBlock = (blockHeader & 1) !== 0;
+      const blockType = (blockHeader >>> 1) & 0x03;
+      const blockSize = blockHeader >>> 3;
+      if (blockType === 0x03) return frames; // reserved block type
+      const payloadBytes = blockType === 0x01 ? 1 : blockSize;
+      if (buffer.length - offset < payloadBytes) return frames;
+      offset += payloadBytes;
+      if (lastBlock) break;
+    }
+    if (checksum) {
+      if (buffer.length - offset < 4) return frames;
+      offset += 4;
+    }
+    frames.push({ start, end: offset });
+  }
+  return frames;
+}
+
+/**
+ * Node-private synchronous multi-frame zstd decoder. Node exposes synchronous
+ * decoding only as a one-shot API that stops at the first frame of a
+ * concatenated container (session logs append a fresh frame per batch).
+ * Reusing one stream's `_handle.writeSync` across frames is the same
+ * optimization the harness's own `NodePrivateZstdFrameDecoder` uses; when the
+ * running Node release lacks that private shape we fall back to per-frame
+ * `zstdDecompressSync` (correct, slower — fine for the occasional /stats poll).
+ */
+function createFrameDecoder() {
+  const stream = createZstdDecompress({ chunkSize: 1024 * 1024 });
+  const handle = stream._handle;
+  const errorKey = Reflect.ownKeys(stream).find(
+    (key) => typeof key === "symbol" && key.description === "kError",
+  );
+  if (
+    typeof handle !== "object" || handle === null ||
+    typeof handle?.writeSync !== "function" ||
+    !(stream._writeState instanceof Uint32Array) ||
+    stream._writeState.length < 2 ||
+    typeof stream._defaultFlushFlag !== "number" ||
+    errorKey === void 0 ||
+    stream[errorKey] !== null
+  ) {
+    stream.close();
+    return null;
+  }
+  const output = Buffer.allocUnsafe(1024 * 1024);
+  let decoderError;
+  stream.on("error", (error) => { decoderError ??= error; });
+  return {
+    decode(frame) {
+      if (decoderError !== void 0) throw decoderError;
+      let inputOffset = 0;
+      let inputRemaining = frame.length;
+      let outputBytes = 0;
+      const fullChunks = [];
+      for (;;) {
+        handle.writeSync(
+          stream._defaultFlushFlag,
+          frame,
+          inputOffset,
+          inputRemaining,
+          output,
+          0,
+          output.length,
+        );
+        if (decoderError !== void 0) throw decoderError;
+        const internalError = stream[errorKey];
+        if (internalError !== null) throw internalError;
+        const outputAfter = stream._writeState[0];
+        const inputAfter = stream._writeState[1];
+        const consumed = inputRemaining - inputAfter;
+        const produced = output.length - outputAfter;
+        if (produced > 0) {
+          outputBytes += produced;
+          if (outputBytes > bufferConstants.MAX_LENGTH) throw new Error("frame output too large");
+        }
+        if (outputAfter !== 0) {
+          if (inputAfter !== 0) throw new Error("decoder left trailing input");
+          const finalChunk = output.subarray(0, produced);
+          if (fullChunks.length === 0) return Buffer.from(finalChunk);
+          if (produced > 0) fullChunks.push(Buffer.from(finalChunk));
+          const onlyChunk = fullChunks[0];
+          return fullChunks.length === 1 ? onlyChunk : Buffer.concat(fullChunks, outputBytes);
+        }
+        fullChunks.push(Buffer.from(output));
+        inputOffset += consumed;
+        inputRemaining = inputAfter;
+      }
+    },
+    close() {
+      stream.close();
+    },
+  };
+}
+
 function decodeZstd(file) {
   try {
-    return execFileSync("zstd", ["-dc", file], { maxBuffer: MAX_BYTES }).toString("utf8");
+    const buffer = fs.readFileSync(file);
+    const frames = frameRanges(buffer);
+    if (frames.length === 0) return "";
+    const decoder = createFrameDecoder();
+    if (decoder !== null) {
+      try {
+        let out = "";
+        for (const frame of frames) out += decoder.decode(buffer.subarray(frame.start, frame.end)).toString("utf8");
+        return out;
+      } finally {
+        decoder.close();
+      }
+    }
+    // Public fallback: one zstdDecompressSync per frame (correct, slower).
+    let out = "";
+    for (const frame of frames) out += zstdDecompressSync(buffer.subarray(frame.start, frame.end)).toString("utf8");
+    return out;
   } catch {
     return "";
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-engram",
   "description": "Minimalist long-term memory for DeepSeek Harness, distilling symbolic-index + pi-esr ideas: zero-LLM auto-capture, a symbolic [ENGRAM] index with progressive disclosure, and an ESR-lite evidence-closure protocol (esr_task / esr_node / esr_close / esr_link). Real agent-behaviour telemetry (usage rollup + /stats) and a deterministic offline recall benchmark (npm run eval). Hot path is model-free; storage on ctx.storageDomain; web memory viewer, observability panel and config card through DSH's native settings slots.",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "license": "MIT",
   "repository": {
     "type": "git",