dsh-engram 0.2.0 → 0.3.0

package/lib/index-block.js

@@ -9,7 +9,7 @@
  * cache reuse.
  */
 
-import { label, shortId, fmtDate, escapeLt, truncate } from "./util.js";
+import { label, shortId, fmtDate, escapeLt, truncate, byRecency } from "./util.js";
 
 /** Deterministic index line prefix per memory kind. */
 export function prefixFor(kind) {
@@ -37,10 +37,17 @@ function isGitPlumbingEcho(m) {
   return /(^|\s)(cd\s|\&\&|;|\|)/.test(text);
 }
 
+/** A procedure that has been used (hit) enough times to count as proven. */
+export function isProvenProcedure(m, config) {
+  return (m?.kind ?? "") === "procedure" && (m?.hits ?? 0) >= (config?.promoteHits ?? 3);
+}
+
 /**
  * Select the memories that earn an index line: knowingly stored high-signal
  * entries, auto-captures past minIndexSignal, and low-signal entries promoted
- * by repeated recall (hits >= promoteHits). Sorted newest first.
+ * by repeated recall (hits >= promoteHits). Proven procedures (a Skill-ish
+ * asset: a workflow validated by repeated use) are ranked first, stably —
+ * each group still newest-first so the block stays deterministic per session.
  */
 export function selectIndexMemories(store, workspace, config) {
   const all = store.listMemories(workspace, 200);
@@ -53,14 +60,21 @@ export function selectIndexMemories(store, workspace, config) {
             (m.hits ?? 0) >= config.promoteHits ||
             m.kind === "task"),
     )
+    .sort((a, b) => {
+      const ap = isProvenProcedure(a, config) ? 0 : 1;
+      const bp = isProvenProcedure(b, config) ? 0 : 1;
+      if (ap !== bp) return ap - bp;
+      return byRecency(a, b);
+    })
     .slice(0, config.indexMaxLines);
 }
 
-function memoryLine(m) {
+function memoryLine(m, config) {
   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(), INDEX_LINE_CHARS);
-  return `[${px}] ${date} ${escapeLt(text)} #${shortId(m.id)}`;
+  return `[${mark}] ${date} ${escapeLt(text)} #${shortId(m.id)}`;
 }
 
 function taskStateLine(t) {
@@ -95,7 +109,7 @@ export function renderIndex(store, workspace, cwd, config) {
   lines.push(`[ENGRAM] workspace: ${label(cwd)} · ${entries.memories} memories · ${tasks.length} task(s) active · ${links} links · ${entries.nodes} node(s)`);
   const entityNames = store.listEntities(workspace).map((e) => e.name);
   if (entityNames.length > 0) lines.push(`nodes: ${truncate(entityNames.join(", "), 72)}`);
-  for (const m of memories.slice(0, config.indexMaxLines)) lines.push(memoryLine(m));
+  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)");
   return enforceCharCap(lines, config.indexMaxChars);

package/lib/index.js

@@ -39,6 +39,9 @@ const DEFAULTS = {
   autoCaptureGlobalCap: 500,
   // recall
   sessionSearch: true,
+  // session-diversified recall: max memories per session before cross-session
+  // evidence takes over (agentmemory 候选①; "few and precise")
+  maxRecallPerSession: 3,
   // [ENGRAM] index budget (token discipline)
   indexMaxLines: 12,
   indexMaxChars: 700,
@@ -56,6 +59,10 @@ const DEFAULTS = {
   // GUI access: hostnames allowed past the loopback fence for /api/dsh-engram
   // (e.g. an operator-authorized cloudflare tunnel). Empty = loopback-only.
   trustedHosts: [],
+  // ESR evidence hardening: a non-URL artifact must exist on disk (relative
+  // artifacts resolve against the workspace = the session cwd DSH provides).
+  // esr_close's force:true bypasses this existence check.
+  verifyArtifact: true,
   // prompt section order (before the persona/tools bands per DSH convention)
   engramIndexOrder: 40,
   esrOrder: 41,
@@ -142,6 +149,15 @@ export function apply(ctx, config) {
         return "";
       }
     },
+    /** Recompute the exact [ESR] block for a workspace (GUI inject preview). */
+    renderEsrBlock(workspace) {
+      if (opened === void 0) return "";
+      try {
+        return renderEsr(opened, workspace, resolved);
+      } catch {
+        return "";
+      }
+    },
   };
 
   // Mechanical, archive-only memory GC (pi-esr constraints). Runs the first

package/lib/mental.js

@@ -0,0 +1,170 @@
+/**
+ * Mental models — precomputed standing answers over a workspace.
+ *
+ * Hindsight lets you define a question once and rewrites the answer in the
+ * background as the bank learns; reading one is a DB read, no LLM call, so an
+ * agent boots with a page of settled knowledge instead of rediscovering it
+ * every session. This is the zero-LLM analogue: `compileSummary` aggregates
+ * the workspace's tasks / entity graph / observations / memory kinds into a
+ * compact markdown blob, `getModel` serves the cached copy and recomputes only
+ * when a write happened (`dirty`), the input set changed (`sources_hash`) or
+ * the cache went stale (>10 min, a safety net for missed bumps).
+ *
+ * Pure + deterministic: `now` injectable, no model calls.
+ */
+
+import { hashText } from "./util.js";
+
+const DEFAULT_MAX_AGE_MS = 10 * 60 * 1000;
+
+/** Escape a name for markdown (pipes/newlines). */
+function mdCell(value) {
+  return String(value ?? "")
+    .replace(/\|/g, "\\|")
+    .replace(/\n/g, " ")
+    .trim();
+}
+
+/**
+ * Aggregate the workspace into a standing-answer markdown blob. Purely derives
+ * from already-indexed data — safe to run on every read.
+ */
+export function compileSummary(domain, ws, { now = Date.now() } = {}) {
+  const summary = domain.summarize();
+  const scope = ws && summary.workspaces[ws] ? { ...summary.workspaces[ws] } : { ...summary.totals };
+  const label = ws ? String(ws).replace(/^.*[\\/]/, "") : "全部工作区";
+
+  let tasks = [];
+  try {
+    tasks = domain.listTasks?.(ws, { includeStable: true }) ?? [];
+  } catch {
+    tasks = [];
+  }
+  const active = tasks.filter((t) => t.state === "active" || t.state === "draft");
+  let ready = 0;
+  const risky = [];
+  for (const t of active) {
+    let gaps = [];
+    try {
+      gaps = domain.evidenceGate?.(ws, t, { verifyArtifact: false })?.gaps ?? [];
+    } catch {
+      gaps = [];
+    }
+    if (gaps.length === 0) ready += 1;
+    else {
+      const ageDays = Math.max(0, Math.floor((now - (t.createdAt ?? now)) / 86400000));
+      risky.push(`- ${mdCell(t.name)} · ${gaps.join("/")} · ${ageDays}天`);
+    }
+  }
+  const stable = tasks.filter((t) => t.state === "stable").length;
+
+  const obs = domain.listObservations?.(ws) ?? [];
+  const obsEvidence = obs.reduce((s, o) => s + (o.proof?.count ?? 0), 0);
+  const topObs = obs
+    .slice()
+    .sort((a, b) => (b.proof?.count ?? 0) - (a.proof?.count ?? 0))
+    .slice(0, 3);
+
+  let kindHist = "";
+  try {
+    const mems = domain.listMemories?.(ws, 1000) ?? [];
+    const byKind = {};
+    for (const m of mems) byKind[m.kind] = (byKind[m.kind] ?? 0) + 1;
+    const top = Object.entries(byKind).sort((a, b) => b[1] - a[1]).slice(0, 3);
+    if (top.length > 0) kindHist = top.map(([k, n]) => `${k} ${n}`).join(" · ");
+  } catch {
+    kindHist = "";
+  }
+
+  const lines = [
+    `## ${label} · 常驻摘要`,
+    `- 任务：${active.length} 进行中（${ready} 就绪）· ${stable} 已闭环`,
+    `- 实体图：${scope.nodes ?? 0} 节点 · ${scope.links ?? 0} 链接`,
+    `- 观测：${obs.length} 条信念（累计 ${obsEvidence} 证据）`,
+    `- 记忆：${scope.memories ?? 0} 条${kindHist ? `（${kindHist}）` : ""}`,
+  ];
+  if (topObs.length > 0) {
+    lines.push("", "重点信念：");
+    for (const o of topObs) lines.push(`- ${mdCell(o.text)} — ×${o.proof?.count ?? 0}`);
+  }
+  if (risky.length > 0) {
+    lines.push("", "未闭环风险：");
+    lines.push(...risky.slice(0, 5));
+  }
+  return lines.join("\n");
+}
+
+/** Hash of the aggregation inputs — detects changes even when a bump was missed. */
+export function computeSourcesHash(domain, ws) {
+  const parts = [];
+  try {
+    const summary = domain.summarize();
+    parts.push(JSON.stringify(ws ? summary.workspaces[ws] : summary.totals));
+    const tasks = domain.listTasks?.(ws, { includeStable: true }) ?? [];
+    parts.push(tasks.map((t) => `${t.id}:${t.state}:${t.updatedAt ?? 0}`).join(","));
+    const obs = domain.listObservations?.(ws) ?? [];
+    parts.push(obs.map((o) => `${o.id}:${o.proof?.count ?? 0}:${o.negations ?? 0}:${o.updated_at ?? 0}`).join(","));
+  } catch {
+    parts.push("err");
+  }
+  return hashText(parts.join("|"));
+}
+
+/** Whether the cached model needs a recompute. */
+export function modelStale(model, domain, ws, { now = Date.now(), maxAgeMs = DEFAULT_MAX_AGE_MS } = {}) {
+  if (model === void 0 || model === null) return true;
+  if (model.dirty === true) return true;
+  if (typeof model.generated_at === "number" && now - model.generated_at > maxAgeMs) return true;
+  if (model.sources_hash !== computeSourcesHash(domain, ws)) return true;
+  return false;
+}
+
+/**
+ * Read the standing answer: cached copy unless stale, then recompute + persist.
+ * Pure aggregation — cheap enough to rebuild on a cold cache.
+ *
+ * @returns {Promise<{ws: string; content: string; generated_at: number; dirty: boolean; sources_hash: string; fresh: boolean}>}
+ */
+/**
+ * Prime-style brief mode: fold the standing answer's headline rows into a
+ * one-liner (~50-token reminder). Derived from the full content — same source
+ * of truth, so the brief can never drift from what the full model says.
+ */
+export function briefify(fullContent) {
+  const bits = [];
+  for (const prefix of ["- 任务：", "- 实体图：", "- 观测："]) {
+    for (const line of fullContent.split("\n")) {
+      if (line.startsWith(prefix)) { bits.push(line.slice(2)); break; }
+    }
+  }
+  let risks = 0;
+  const lines = fullContent.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith("未闭环风险")) {
+      for (let j = i + 1; j < lines.length && lines[j].startsWith("- "); j++) risks++;
+    }
+  }
+  bits.push(risks > 0 ? `风险 ${risks}` : "无未闭环风险");
+  return bits.join(" · ").slice(0, 240);
+}
+
+export async function getModel(domain, ws, { now = Date.now(), maxAgeMs, compile = compileSummary, hash = computeSourcesHash, mode = "full" } = {}) {
+  const current = domain.getModel(ws);
+  if (!modelStale(current, domain, ws, { now, maxAgeMs })) {
+    const hit = { ...current, fresh: false };
+    if (mode === "brief") hit.content = briefify(hit.content);
+    return hit;
+  }
+  const ev = { now };
+  const content = compile(domain, ws, ev);
+  const fresh = {
+    ws,
+    content,
+    generated_at: now,
+    dirty: false,
+    sources_hash: hash(domain, ws),
+  };
+  await domain.putModel(ws, fresh);
+  if (mode === "brief") fresh.content = briefify(fresh.content);
+  return { ...fresh, fresh: true };
+}

package/lib/obs.js

@@ -0,0 +1,71 @@
+/**
+ * Observation VIEW — evidence-grounded beliefs, derived not persisted.
+ *
+ * Assessment P2 (2026-08-22): observations were a second persisted
+ * representation with write-path side effects (`integrateObservation` ran on
+ * every store). Demoted to a pure deterministic projection of memories: a
+ * memory with `hits >= OBSERVATION_MIN_PROOF` IS an observation — proof count
+ * is its hit count, its span is created→updated, trend is computed from
+ * recency. Nothing is written, nothing is stored; the GUI/API/tools keep the
+ * exact same shape (`o.proof.count`, `o.negations`, `o.trend`, `o.updated_at`).
+ *
+ * All functions are pure — zero LLM, zero storage.
+ */
+
+/** A memory only counts as a belief once it has been evidenced twice. */
+export const OBSERVATION_MIN_PROOF = 2;
+
+/**
+ * Trend from evidence recency (30/90-day windows, mirroring Hindsight):
+ *   - no evidence in the old window at all             -> stale
+ *   - newest evidence older than recentDays            -> weakening
+ *   - every source within recentDays                   -> new
+ *   - ≥2 sources, latest recent and history before     -> strengthening
+ *   - otherwise                                        -> stable
+ */
+export function computeTrend(span, now = Date.now(), { recentDays = 30, oldDays = 90 } = {}) {
+  const DAY = 86400000;
+  const first = span?.first_seen_at ?? null;
+  const last = span?.last_seen_at ?? first;
+  if (first === null || last === null) return "new";
+  const firstAge = Math.max(0, now - first) / DAY;
+  const lastAge = Math.max(0, now - last) / DAY;
+  if (firstAge > oldDays && lastAge > oldDays) return "stale";
+  if (lastAge > recentDays) return "weakening";
+  if (firstAge <= recentDays) return "new";
+  return "strengthening";
+}
+
+/**
+ * Derive the observations of a workspace from its active memories.
+ * Best-first by proof (hits), then newest first. Shape is stable and
+ * compatible with the old persisted records so every consumer
+ * (tools / mental / api / client) keeps working unchanged.
+ */
+export function deriveObservations(memories, { now = Date.now() } = {}) {
+  return memories
+    .filter((m) => (m.hits ?? 0) >= OBSERVATION_MIN_PROOF)
+    .map((m) => {
+      const createdAt = m.createdAt ?? now;
+      const updatedAt = m.updatedAt ?? createdAt;
+      const span = { first_seen_at: createdAt, last_seen_at: updatedAt };
+      return {
+        id: m.id,
+        workspace: m.workspace,
+        text: m.text,
+        kind: m.kind === "error" ? "pattern" : "belief",
+        proof: { count: m.hits ?? 0, sources: [m.id] },
+        span,
+        negations: 0,
+        trend: computeTrend(span, now),
+        tags: Array.isArray(m.tags) ? m.tags : [],
+        entity: m.entity ?? null,
+        updated_at: updatedAt,
+      };
+    })
+    .sort(
+      (a, b) =>
+        (b.proof?.count ?? 0) - (a.proof?.count ?? 0) ||
+        (b.updated_at ?? 0) - (a.updated_at ?? 0),
+    );
+}

package/lib/rerank.js

@@ -0,0 +1,50 @@
+/**
+ * Evidence-aware reranking signals for deterministic recall.
+ *
+ * Hindsight's reranking folds proof strength into the relevance score as a
+ * multiplicative boost (conservative, ±5% at weight 0.1). Here the analogue
+ * of "proof count" is a memory's cumulative recall hits — which our D2
+ * failure-revival path already increments on repeat failures, so high-hits
+ * memories are exactly the ones we want to stay findable. All functions are
+ * pure and dependency-free: `now` and weights are injectable for deterministic
+ * tests, matching the injectability of `util.bm25Rank`.
+ */
+
+/**
+ * Multiplicative evidence strength boost: 1 + alpha·min(max(0, hits), cap).
+ * Flat beyond `cap` so one runaway popular memory can't dominate ranking.
+ */
+export function evidenceBoost(hits, { alpha = 0.1, cap = 5 } = {}) {
+  const h = Math.max(0, Number.isFinite(hits) ? hits : 0);
+  return 1 + alpha * Math.min(h, cap);
+}
+
+/** Combine a base match score with the evidence boost. */
+export function scoreCandidate(matchScore, hits, { alpha = 0.1, cap = 5 } = {}) {
+  return (Number.isFinite(matchScore) ? matchScore : 0) * evidenceBoost(hits, { alpha, cap });
+}
+
+/**
+ * Stable sort of candidates by (score desc, tiebreak). Returns a new array;
+ * equal scores keep their input order.
+ *
+ * @param {Array} list
+ * @param {object} opts
+ * @param {(r:any)=>number} [opts.getScore] base score per candidate (default 0)
+ * @param {(r:any)=>number} [opts.getHits] evidence count per candidate
+ * @param {number} [opts.alpha] boost weight
+ * @param {number} [opts.cap] boost saturation point
+ * @param {(a:any,b:any)=>number} [opts.tiebreak] secondary comparator
+ */
+export function sortByEvidence(list, { getScore = () => 0, getHits = (r) => r.hits ?? 0, alpha = 0.1, cap = 5, tiebreak = null } = {}) {
+  const scored = list.map((r, i) => ({ r, i, s: scoreCandidate(getScore(r), getHits(r), { alpha, cap }) }));
+  scored.sort((a, b) => {
+    if (b.s !== a.s) return b.s - a.s;
+    if (tiebreak) {
+      const t = tiebreak(a.r, b.r);
+      if (t !== 0) return t;
+    }
+    return a.i - b.i; // stable
+  });
+  return scored.map((e) => e.r);
+}

package/lib/settings.js

@@ -22,6 +22,7 @@ export const SETTINGS_NS = settingsNamespace(SETTINGS_NS_NAME);
 export const SETTINGS_KEYS = [
   "autoCapture",
   "sessionSearch",
+  "maxRecallPerSession",
   "autoCapturePerSession",
   "indexMaxLines",
   "indexMaxChars",
@@ -48,6 +49,7 @@ export function makeSettingsSchema(defaults) {
   return z.object({
     autoCapture: z.boolean().default(defaults.autoCapture),
     sessionSearch: z.boolean().default(defaults.sessionSearch),
+    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),
     indexMaxChars: z.natural().max(4000).default(defaults.indexMaxChars),
@@ -57,6 +59,7 @@ export function makeSettingsSchema(defaults) {
     maxMemoriesPerWorkspace: z.natural().max(10000).default(defaults.maxMemoriesPerWorkspace),
     gcEnabled: z.boolean().default(defaults.gcEnabled),
     gcStableRetentionDays: z.natural().max(3650).default(defaults.gcStableRetentionDays),
+    verifyArtifact: z.boolean().default(defaults.verifyArtifact).description("ESR 闭环时校验 artifact 路径真实存在"),
     // Security knob, not rendered in the card: hostnames allowed past the
     // loopback fence for /api/dsh-engram (operator-authorized tunnel hosts).
     trustedHosts: z.array(z.string()).default([]),