dsh-engram 0.2.0 → 0.3.0

package/lib/tools.js

@@ -17,7 +17,6 @@
 import { z } from "zod";
 import { EngramError, hasCode } from "./store.js";
 import { truncate, shortId, slugId, fmtDate, escapeLt, workspaceKey as wk, uuid } from "./util.js";
-import { makeUsageTracker } from "./usage.js";
 
 const KINDS = [
   "decision",
@@ -75,115 +74,150 @@ async function requireDomain(service) {
 function memoryLine(m, verbosity = "short") {
   const tags = m.entity !== null ? ` · entity:${m.entity}` : "";
   if (verbosity === "full") {
-    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}`, ""].join("\n");
+    const access = m.lastAccessAt == null ? "never-accessed" : `lastAccess ${fmtDate(m.lastAccessAt)}`;
+    const pathLine = m.filePath ? ` · path ${m.filePath}` : "";
+    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}`, ""].join("\n");
   }
   const date = fmtDate(m.createdAt ?? m.updatedAt);
-  return `- ${m.id.slice(0, 8)} [${m.kind}] ${date} ${escapeLt(truncate(m.text, 200))}${tags}${m.hits > 0 ? ` · ×${m.hits}` : ""}`;
+  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}`;
+}
+
+/** Stable kind display order for grouped recall output (matches MEMORY_KINDS). */
+const MEMORY_KIND_ORDER = ["decision", "error", "procedure", "fact", "insight", "handoff", "task"];
+
+/**
+ * Render recall hits grouped by kind (MemoraX-style memory_type buckets):
+ *   ## decision (2)
+ *   - 08-21 …
+ * Within a group the original (relevance) order is preserved; unknown kinds
+ * (future-proof) trail the fixed order. Pure, deterministic.
+ */
+function groupKindLines(items) {
+  const buckets = new Map();
+  for (const m of items) {
+    const kind = typeof m.kind === "string" && m.kind.length > 0 ? m.kind : "unknown";
+    if (!buckets.has(kind)) buckets.set(kind, []);
+    buckets.get(kind).push(m);
+  }
+  const lines = [];
+  const emit = (kind, group) => {
+    lines.push(`## ${kind} (${group.length})`);
+    for (const m of group) lines.push(memoryLine(m));
+  };
+  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);
+  return lines;
 }
 
 export function registerTools(ctx, service) {
   return ctx.effect(() => {
-    const usage = makeUsageTracker();
-    // Wrap registration so every model-facing tool call is recorded into the
-    // per-(workspace, day) usage rollup (real ESR-proactivity / recall stats).
-    const registerTool = (tool) => {
-      const execute = tool.execute;
-      return ctx.tools.register({
-        ...tool,
-        execute: async (raw, exec) => {
-          try {
-            const out = await execute(raw, exec);
-            void usage
-              .record(service, exec, tool.name, {
-                ok: true,
-                recallOutput: tool.name === "engram_recall" ? out : void 0,
-              })
-              .catch(() => {});
-            return out;
-          } catch (error) {
-            void usage.record(service, exec, tool.name, { ok: false }).catch(() => {});
-            throw error;
-          }
-        },
-      });
-    };
+    // Assessment P3: no per-call usage writes — agent-behaviour observability
+    // is computed on demand from the session log stream (lib/usage.js), so
+    // tools register plain, without a recording wrapper.
+    const registerTool = (tool) => ctx.tools.register(tool);
     const disposers = [
       // ── engram_store ────────────────────────────────────────────────────
       registerTool({
         name: "engram_store",
-        description: "Explicitly store one memory in this workspace's long-term memory. Kinds: decision/error/procedure/fact/insight/handoff/task (D/E/P/F/I/H/T prefixes in the [ENGRAM] index). Pass an entity to anchor it (pi-esr entity_id convention). Auto-capture already records git/file/error events — use this for anything it misses. Exact-duplicate text refreshes the existing entry instead of adding.",
+        description: "Store one memory: kind=(decision|error|procedure|fact|insight|handoff|task), text, optional entity anchor. Exact-duplicate text refreshes instead of adding; auto-capture already handles git/file/error events — use this for anything it misses.",
         parameters: {
           type: "object",
           properties: {
             text: { type: "string", description: "Compact, information-dense memory text (required)" },
             ...p,
+            file_path: { type: "string", description: "Optional absolute path this memory anchors to (e.g. the failing file)" },
           },
           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() }), 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() }), raw, "engram_store");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           await domain.expireSweep(caller.cwd);
-          const { stored, duplicated } = await domain.storeMemory(
+          const { stored, duplicated, revived } = await domain.storeMemory(
             {
               workspace: caller.cwd,
               kind: args.kind ?? "fact",
               text: args.text,
               tags: args.tags ?? [],
               entity: args.entity ?? null,
+              filePath: args.file_path ?? null,
               sessionId: caller.sessionId,
               seq: caller.seq,
               signal: 0.6,
             },
             service.config,
           );
-          return `stored ${duplicated ? "(duplicate refreshed) " : ""}memory ${stored.id} [${stored.kind}] — cited to session ${stored.sessionId}#${stored.seq}`;
+          const dupNote = duplicated ? (revived === true ? "(repeat failure — previous entry revived) " : "(duplicate refreshed) ") : "";
+          await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
+          return `stored ${dupNote}memory ${stored.id} [${stored.kind}] — cited to session ${stored.sessionId}#${stored.seq}`;
         },
       }),
 
       // ── engram_recall ───────────────────────────────────────────────────
       registerTool({
         name: "engram_recall",
-        description: "Deterministic recall over this workspace's engram memories: exact tag match ranks first, case-insensitive text substring next, recency breaks ties. Literal, not semantic — query in the language the memory is likely written in. Pass query to filter, entity to restrict to an entity's memories (timeline), search_sessions:true to also full-text search PAST sessions of this workspace via the harness session index. Hit counts promote low-signal auto-captures into the [ENGRAM] index.",
+        description: "Deterministic recall of this workspace's memories (BM25: exact tag first, recency ties). Literal, not semantic — query in the memory's likely language. query=filter, entity=timeline, search_sessions=true adds past-session FTS. limit/max_per_session/group_by_kind tune output.",
         parameters: {
           type: "object",
           properties: {
             query: { type: "string", description: "Words to match against memory text and tags" },
             entity: { type: "string", description: "Return that entity's memories chronologically" },
             limit: { type: "integer", minimum: 1, maximum: 50, description: "Max memories (default 12)" },
+            max_per_session: { type: "integer", minimum: 1, maximum: 10, description: "Session-diversified cap: max memories kept per sessionId (default config.maxRecallPerSession=3; >1 sessions get to share the list)" },
+            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)" },
           },
         },
         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(), 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() }), raw, "engram_recall");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           let lines = [];
+          let items = [];
+          // When a query/entity returns nothing locally, the FTS fallback below
+          // 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;
           if (args.entity !== void 0 && args.entity.trim().length > 0) {
-            const items = domain.timeline(caller.cwd, args.entity, args.limit ?? 30);
-            if (items.length === 0) return `no memories for entity "${args.entity}" in this workspace`;
-            lines.push(`# timeline: ${args.entity}`);
+            items = domain.timeline(caller.cwd, args.entity, args.limit ?? 30);
+            if (items.length === 0) zeroHits = true;
+            lines.push(zeroHits ? `no memories for entity "${args.entity}" in this workspace` : `# timeline: ${args.entity}`);
             lines.push(...items.map((m) => memoryLine(m)));
             await Promise.all(items.map((m) => domain.touchMemory(caller.cwd, m.id).catch(() => null)));
           } else if (args.query !== void 0) {
-            const items = domain.recall(caller.cwd, args.query, args.limit ?? 12);
-            if (items.length === 0) return `no active memories match ${JSON.stringify(args.query)} in this workspace`;
-            lines.push(`# recall: ${JSON.stringify(args.query)} (${items.length})`);
-            lines.push(...items.map((m) => memoryLine(m)));
+            const maxPerSession = args.max_per_session ?? service.config.maxRecallPerSession ?? 3;
+            items = domain.recall(caller.cwd, args.query, args.limit ?? 12, { maxPerSession });
+            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`);
+            lines.push(...(args.group_by_kind === false ? items.map((m) => memoryLine(m)) : groupKindLines(items)));
             await Promise.all(items.map((m) => domain.touchMemory(caller.cwd, m.id).catch(() => null)));
           } else {
-            const items = domain.listMemories(caller.cwd, args.limit ?? 12);
+            items = domain.listMemories(caller.cwd, args.limit ?? 12);
             if (items.length === 0) return "no active memories in this workspace yet";
             lines.push(`# newest memories (${items.length})`);
             lines.push(...items.map((m) => memoryLine(m)));
           }
-          if (args.search_sessions === true) {
+          // Entity neighborhood: items anchored to entities get a compact
+          // graph-retrieval pass over the existing ESR relation table (the
+          // lightweight knowledge-graph end of the spectrum — no graph DB).
+          const neighbors = collectNeighborhood(domain, caller.cwd, items);
+          if (neighbors.length > 0) lines.push("", "# entity neighborhood", ...neighbors);
+          // Evidence-grounded beliefs: repeated signals (proof >= 2) surface as
+          // high-confidence observations alongside the raw recall hits.
+          const strongObs = (domain.listObservations?.(caller.cwd) ?? []).filter((o) => (o.proof?.count ?? 0) >= 2);
+          if (strongObs.length > 0) {
+            lines.push("", "# observations (evidence ≥ 2)", ...strongObs.map((o) => `• ${o.text} — ×${o.proof.count} ${o.trend}${o.negations > 0 ? ` · 反证${o.negations}` : ""}`));
+          }
+          const wantSessions = args.search_sessions === true || (zeroHits && service.config.sessionSearch !== false);
+          if (wantSessions) {
             const extra = await searchSessions(service, caller, args.query ?? args.entity ?? "", exec.signal);
-            if (extra.length > 0) lines.push("", "# past sessions (FTS)", ...extra);
+            if (extra.length > 0) lines.push("", "# past sessions (FTS fallback)", ...extra);
+            else if (zeroHits && lines.length === 1) lines[0] += " (no past-session hits either)";
           }
           return lines.join("\n");
         },
@@ -192,7 +226,7 @@ export function registerTools(ctx, service) {
       // ── engram_detail ───────────────────────────────────────────────────
       registerTool({
         name: "engram_detail",
-        description: "Full record of one memory id from the [ENGRAM] index (run engram_recall to find ids): text, tags, entity, signal, hits, provenance session#seq.",
+        description: "Full record of one memory id (from engram_recall): text, tags, entity, signal, hits, provenance session#seq.",
         parameters: {
           type: "object",
           properties: {
@@ -216,7 +250,7 @@ export function registerTools(ctx, service) {
       // ── esr_task ──────────────────────────────────────────────────────
       registerTool({
         name: "esr_task",
-        description: "Create or update an engineering task entity (draft→active). ESR: a task is only 'done' when it has real evidence — close it with esr_close (artifact + evaluation + memory_ref). Set id to update an existing task.",
+        description: "Create/update an engineering task (draft→active). A task is only 'done' with evidence — finish via esr_close (artifact + evaluation + memory_ref). Set id to update an existing task.",
         parameters: {
           type: "object",
           properties: {
@@ -250,29 +284,36 @@ export function registerTools(ctx, service) {
             createdAt: existing?.createdAt ?? now,
             updatedAt: now,
             stateChangedAt: existing?.stateChangedAt ?? 0,
+            deps: existing?.deps ?? [],
+            assignee: existing?.assignee ?? null,
+            claimedAt: existing?.claimedAt ?? null,
           };
           await domain.putTask(task);
-          return `task ${task.id} [${task.state}] — ${task.name}`;
+          await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
+          const hint = esrModelingHint(domain, caller.cwd);
+          return `task ${task.id} [${task.state}] — ${task.name}${hint ? `
+${hint}` : ""}`;
         },
       }),
 
       // ── esr_close ─────────────────────────────────────────────────────
       registerTool({
         name: "esr_close",
-        description: "Close a task via the ESR evidence protocol. 'stable' requires ALL THREE gates: artifact (path/url of the produced artifact), evaluation (how it was verified — test run, review, benchmark score), and memory_ref (list of engram memory ids capturing decisions made). Missing gates are reported as gaps and the task stays active. On success a 'task closed' memory is auto-stored with the evidence.",
+        description: "Close a task via the ESR evidence protocol: requires artifact (path/url), evaluation (how verified) and memory_ref (memory ids) — missing gates keep it active; force:true skips the on-disk artifact check. Auto-stores a closing memory.",
         parameters: {
           type: "object",
           properties: {
             task_id: { type: "string", description: "Task id from [ESR] or esr_task" },
-            artifact: { type: "string", description: "Produced artifact (path/url)" },
+            artifact: { type: "string", description: "Produced artifact (path/url). Paths are resolved against the workspace and must exist on disk unless force:true" },
             evaluation: { type: "string", description: "Verification evidence (test/review/benchmark)" },
             memory_refs: { type: "array", items: { type: "string" }, description: "Memory ids that record the decisions made" },
+            force: { type: "boolean", description: "Skip the on-disk artifact existence check (gates are still required)" },
           },
           required: ["task_id"],
         },
         output: TEXT_OUTPUT,
         execute: async (raw, exec) => {
-          const args = parse(z.object({ task_id: z.string().min(1), artifact: z.string().optional(), evaluation: z.string().optional(), memory_refs: z.array(z.string()).optional() }), raw, "esr_close");
+          const args = parse(z.object({ task_id: z.string().min(1), artifact: z.string().optional(), evaluation: z.string().optional(), memory_refs: z.array(z.string()).optional(), force: z.boolean().optional() }), raw, "esr_close");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           const task = domain.getTask(caller.cwd, resolveTaskId(domain, caller.cwd, args.task_id));
@@ -284,16 +325,20 @@ export function registerTools(ctx, service) {
             memoryRefs: args.memory_refs ?? task.memoryRefs,
             updatedAt: Date.now(),
           };
-          const gaps = [];
-          if (next.artifact === null || next.artifact === "") gaps.push("artifact");
-          if (next.evaluation === null || next.evaluation === "") gaps.push("evaluation");
-          if (next.memoryRefs.length === 0) gaps.push("memory_ref");
+          // force only skips the on-disk existence check — the three gates
+          // (artifact/evaluation/memory_ref) are always required.
+          const gateCfg = args.force === true ? { ...service.config, verifyArtifact: false } : service.config;
+          const gate = domain.evidenceGate(caller.cwd, next, gateCfg);
+          const gaps = gate.gaps;
           if (gaps.length > 0) {
             await domain.putTask(next);
-            return `task ${task.id} still ACTIVE — evidence gaps: ${gaps.join(", ")}. Provide them and call esr_close again (the [ESR] block shows current gaps).`;
+            await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
+            const reason = gate.artifactReason !== void 0 ? ` (${gate.artifactReason})` : "";
+            return `task ${task.id} still ACTIVE — evidence gaps: ${gaps.join(", ")}${reason}. Provide them (and ensure the artifact path exists on disk unless force:true) and call esr_close again (the [ESR] block shows current gaps).`;
           }
-          const closed = { ...next, state: "stable", stateChangedAt: Date.now() };
+          const closed = domain.compactOnClose?.({ ...next, state: "stable", stateChangedAt: Date.now() }) ?? { ...next, state: "stable", stateChangedAt: Date.now() };
           await domain.putTask(closed);
+          await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
           const mem = await domain.storeMemory(
             {
               workspace: caller.cwd,
@@ -307,14 +352,16 @@ export function registerTools(ctx, service) {
             },
             service.config,
           );
-          return `task ${task.id} → STABLE ✓ (artifact, evaluation, ${next.memoryRefs.length} memory ref(s))\nclosure memory: ${mem.id}`;
+          const hint = esrModelingHint(domain, caller.cwd);
+          return `task ${task.id} → STABLE ✓ (artifact, evaluation, ${next.memoryRefs.length} memory ref(s))\nclosure memory: ${mem.id}${hint ? `
+${hint}` : ""}`;
         },
       }),
 
       // ── esr_link ──────────────────────────────────────────────────────
       registerTool({
         name: "esr_link",
-        description: "Add a typed relation between two entities (mini graph, pi-esr flavor), e.g. depends_on / implements / refines / contradicts. Relations surface in engram_timeline-style queries via entity and in the workspace's link count.",
+        description: "Add a typed relation between two entities (depends_on/implements/refines/contradicts…). Feeds entity queries and the workspace link count.",
         parameters: {
           type: "object",
           properties: {
@@ -341,14 +388,109 @@ export function registerTools(ctx, service) {
             sessionId: caller.sessionId,
             createdAt: Date.now(),
           });
+          await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
           return `link ${id} — ${args.source} --${args.relation}--> ${args.target}`;
         },
       }),
 
-      // ── esr_node ──────────────────────────────────────────────────────
+      registerTool({
+        name: "esr_dep",
+        description: "Add a dependency edge between tasks: blocks (waits until dep closes), parent-of (child), relates-to (no blocking). Refuses self-deps and cycles.",
+        parameters: {
+          type: "object",
+          properties: {
+            task_id: { type: "string", description: "The task gaining the dependency" },
+            dep_id: { type: "string", description: "The task it depends on / relates to" },
+            kind: { type: "string", enum: ["blocks", "relates-to", "parent-of"], description: "Edge kind (default blocks)" },
+          },
+          required: ["task_id", "dep_id"],
+        },
+        output: TEXT_OUTPUT,
+        execute: async (raw, exec) => {
+          const args = parse(z.object({ task_id: z.string().min(1), dep_id: z.string().min(1), kind: z.enum(["blocks", "relates-to", "parent-of"]).optional() }), raw, "esr_dep");
+          const caller = callerOf(exec);
+          const domain = await requireDomain(service);
+          const t = await domain.addDep(caller.cwd, resolveTaskId(domain, caller.cwd, args.task_id), resolveTaskId(domain, caller.cwd, args.dep_id), args.kind ?? "blocks");
+          await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
+          return `dep added: ${t.id} --${args.kind ?? "blocks"}--> ${args.dep_id} (total ${(t.deps ?? []).length} edges)`;
+        },
+      }),
+
+      // ── esr_claim / esr_unclaim ─────────────────────────────────────
+      registerTool({
+        name: "esr_claim",
+        description: "Atomically claim a task (assignee+claimedAt, draft→active). Refuses when another agent holds it unless force:true. Find work with esr_ready.",
+        parameters: {
+          type: "object",
+          properties: {
+            task_id: { type: "string", description: "Task id from [ESR] or esr_task" },
+            agent: { type: "string", description: "Claimer id (default: current session agent)" },
+            force: { type: "boolean", description: "Steal the claim from its current holder (default false)" },
+          },
+          required: ["task_id"],
+        },
+        output: TEXT_OUTPUT,
+        execute: async (raw, exec) => {
+          const args = parse(z.object({ task_id: z.string().min(1), agent: z.string().optional(), force: z.boolean().optional() }), raw, "esr_claim");
+          const caller = callerOf(exec);
+          const domain = await requireDomain(service);
+          const agent = args.agent ?? caller.agentId ?? "agent";
+          const t = await domain.claimTask(caller.cwd, resolveTaskId(domain, caller.cwd, args.task_id), agent, { force: args.force === true });
+          await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
+          return `claimed ${t.id} by ${agent} [${t.state}] — ${t.name}`;
+        },
+      }),
+      registerTool({
+        name: "esr_unclaim",
+        description: "Release a claimed task's assignee back to null. Non-holder needs force:true. Inverse of esr_claim.",
+        parameters: {
+          type: "object",
+          properties: {
+            task_id: { type: "string", description: "Task id from [ESR] or esr_task" },
+            force: { type: "boolean", description: "Release even when someone else holds it (default false)" },
+          },
+          required: ["task_id"],
+        },
+        output: TEXT_OUTPUT,
+        execute: async (raw, exec) => {
+          const args = parse(z.object({ task_id: z.string().min(1), force: z.boolean().optional() }), raw, "esr_unclaim");
+          const caller = callerOf(exec);
+          const domain = await requireDomain(service);
+          const agent = caller.agentId ?? "agent";
+          const t = await domain.unclaimTask(caller.cwd, resolveTaskId(domain, caller.cwd, args.task_id), agent, { force: args.force === true });
+          await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
+          return `released ${t.id} — ${t.name} (unclaimed)`;
+        },
+      }),
+
+      // ── esr_ready ────────────────────────────────────────────────────
+      registerTool({
+        name: "esr_ready",
+        description: "List claimable tasks: no open blocker and nobody claimed. One line per task.",
+        parameters: {
+          type: "object",
+          properties: {
+            workspace: { type: "string", description: "Override the workspace key (default: current session cwd)" },
+            limit: { type: "integer", minimum: 1, maximum: 50, description: "Max tasks (default 10)" },
+          },
+        },
+        output: TEXT_OUTPUT,
+        timeoutMs: 20000,
+        execute: async (raw, exec) => {
+          const args = parse(z.object({ workspace: z.string().optional(), limit: z.number().int().min(1).max(50).optional() }), raw, "esr_ready");
+          const caller = callerOf(exec);
+          const domain = await requireDomain(service);
+          const ws = args.workspace ?? caller.cwd;
+          const ready = domain.readyTasks(ws, args.limit ?? 10);
+          if (ready.length === 0) return `no claimable work right now in ${ws} — tasks with open blockers stay blocked until their deps close`;
+          return `# ready (claimable): ${ready.length}\n` + ready.map((t) => `- ${t.id} [${t.state}] ${t.name}${(t.deps ?? []).length > 0 ? ` (deps ${t.deps.length})` : ""}`).join("\n");
+        },
+      }),
+
+      // ── esr_node ─────────────────────────────────────
       registerTool({
         name: "esr_node",
-        description: "Create or update an entity node — a stable symbol for a thing this workspace keeps referring to (a package, service, document, repository, person, bug, concept). Nodes anchor esr_link relations and the `entity` field of memories. The id is derived from the name (`ent_<slug>`), so calling esr_node with the same name updates the same node and esr_link can target it without a prior id lookup. Be proactive: create a node when a domain object recurs across your work, and link related nodes/tasks with esr_link.",
+        description: "Create/update an entity node — stable symbol for a recurring thing (package/service/doc/repo/person/bug/concept). Nodes anchor esr_link relations and memory entity. Same name updates; id = ent_<slug>.",
         parameters: {
           type: "object",
           properties: {
@@ -377,16 +519,20 @@ export function registerTools(ctx, service) {
             updatedAt: now,
           };
           await domain.putEntity(node);
-          return existing
+          await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
+          const hint = esrModelingHint(domain, caller.cwd);
+          const base = existing
             ? `node ${id} updated — ${node.name}${node.kind ? ` (${node.kind})` : ""}`
             : `node ${id} created — ${node.name}${node.kind ? ` (${node.kind})` : ""}`;
+          return `${base}${hint ? `
+${hint}` : ""}`;
         },
       }),
 
       // ── esr_gc ────────────────────────────────────────────────────────
       registerTool({
         name: "esr_gc",
-        description: "Run the pi-esr-style memory GC for this workspace. Archives TTL-expired memories, evicts over-cap low-value memories, archives stable tasks past their retention window, and removes dangling link edges. The WORKING SET is never touched (memories referenced by active tasks, task memories, already-indexed hits). Archive-only — nothing is hard-deleted, every entry stays re-fetchable by id. dry_run:true previews without writing.",
+        description: "Run memory GC: archives TTL-expired, over-cap low-retention memories, stable tasks past retention, dangling links. Working set protected; archive-only (nothing hard-deleted). dry_run:true previews.",
         parameters: {
           type: "object",
           properties: {
@@ -403,6 +549,36 @@ export function registerTools(ctx, service) {
           return gcReportText(report);
         },
       }),
+
+      // ── esr_model ─────────────────────────────────────────────────────
+      registerTool({
+        name: "esr_model",
+        description: "Precomputed mental model of the workspace (task counts, entity graph, top evidence-grounded beliefs, risks). Zero LLM. mode=brief → ~50-token one-liner; max_chars trims. Read before scattering recall.",
+        parameters: {
+          type: "object",
+          properties: {
+            ws: { type: "string", description: "Workspace to summarize (default: current session cwd)" },
+            mode: { type: "string", enum: ["full", "brief"], description: "brief = one-line headline (session-start injection); full = complete markdown (default)" },
+            max_chars: { type: "integer", minimum: 1, maximum: 4000, description: "Cap output length (default: no cap)" },
+          },
+        },
+        output: TEXT_OUTPUT,
+        timeoutMs: 20000,
+        execute: async (raw, exec) => {
+          const args = parse(z.object({ ws: z.string().optional(), mode: z.enum(["full", "brief"]).optional(), max_chars: z.number().int().min(1).max(4000).optional() }), raw, "esr_model");
+          const caller = callerOf(exec);
+          const domain = await requireDomain(service);
+          const ws = args.ws ?? caller.cwd;
+          const { getModel } = await import("./mental.js");
+          const model = await getModel(domain, ws, { mode: args.mode ?? "full" });
+          const mins = Math.max(0, Math.floor((Date.now() - model.generated_at) / 60000));
+          let content = model.content;
+          if (typeof args.max_chars === "number" && content.length > args.max_chars) {
+            content = `${content.slice(0, Math.max(1, args.max_chars - 1))}…`;
+          }
+          return `${content}\n\n(生成于 ${mins} 分钟前 · ${model.fresh ? "本次重算" : "缓存命中"} · mode=${args.mode ?? "full"} · ws=${ws})`;
+        },
+      }),
     ];
     return () => {
       for (const dispose of disposers) dispose();
@@ -410,6 +586,56 @@ export function registerTools(ctx, service) {
   });
 }
 
+/**
+ * Compact graph-retrieval pass for engram_recall: entities the returned
+ * memories are anchored to, and the ESR relation lines touching them
+ * (`node --rel--> node · conf%`). This is the lightweight end of the
+ * graph-memory spectrum — it reuses the existing `links`/`entities` tables,
+ * no graph database. Deterministic, capped (≤ 8 lines), deduped by link id.
+ */
+/**
+ * Model-facing nudge for the near-empty entity graph: after a task/node
+ * change, tell the model how the workspace's entity/relation graph looks so
+ * esr_node / esr_link stay in its decision space. Returns "" when the domain
+ * is unavailable so callers can skip the extra line silently.
+ */
+export function esrModelingHint(domain, workspace) {
+  try {
+    const entities = domain.listEntities(workspace);
+    const links = domain.allLinks(workspace);
+    if (entities.length === 0) {
+      return "modeling: no entity graph in this workspace yet — create esr_node entries for recurring domain objects, then esr_link to connect them (graph: GUI Settings → Engram).";
+    }
+    const names = entities.slice(0, 3).map((e) => e.name).join(", ");
+    return `modeling: entities ${names}${entities.length > 3 ? ` +${entities.length - 3}` : ""} / links ${links.length} — esr_link can wire new tasks & nodes into this graph.`;
+  } catch {
+    return "";
+  }
+}
+
+function collectNeighborhood(domain, workspace, items) {
+  const involved = new Set();
+  for (const m of items ?? []) {
+    if (m?.entity !== null && m?.entity !== void 0 && m.entity !== "") involved.add(m.entity);
+  }
+  if (involved.size === 0) return [];
+  const label = (id) => {
+    const e = domain.getEntity(workspace, id);
+    return e !== void 0 ? e.name || id : id;
+  };
+  const seen = new Set();
+  const lines = [];
+  for (const ent of involved) {
+    for (const l of domain.linksFor(workspace, ent)) {
+      if (seen.has(l.id)) continue;
+      seen.add(l.id);
+      lines.push(`- ${label(l.source)} --${l.relation}--> ${label(l.target)} (${Math.round((l.confidence ?? 1) * 100)}%)`);
+      if (lines.length >= 8) return lines;
+    }
+  }
+  return lines;
+}
+
 /** FTS over past sessions via ctx.sessionQuery (mounted by the web profile). */
 async function searchSessions(service, caller, query, signal) {
   const sq = service.sessionQuery;