dsh-engram 0.6.0 → 0.7.1

package/lib/index.js

@@ -24,12 +24,14 @@ import { registerTools } from "./tools.js";
 import { makeCaptureHandler } from "./capture.js";
 import { installGoalCapture } from "./goal-capture.js";
 import { installPreferenceCapture } from "./preference.js";
-import { installBoundaryPrune } from "./boundary-prune.js";
+import { boundaryPruneAvailability, installBoundaryPrune } from "./boundary-prune.js";
 import { resultPackDir, archivePrunedResults, resultRecallTool, sweepExpired } from "./result-pack.js";
 import { recordBoundaryPruneFire, recordRecallInjection, readPackTelemetry, engramHome } from "./pack-telemetry.js";
 import { createLedger, estimatePrefixChars } from "./ledger.js";
 import { createJit } from "./jit.js";
-import { renderIndex, renderStartRecall, firstUserMessageText, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
+import { buildEpisode } from "./episode.js";
+import { collectStaleAnchors } from "./anchor.js";
+import { renderIndex, renderStartRecall, renderResumeBrief, firstUserMessageText, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
 import { makeTriggerRecorder } from "./trigger.js";
 import { pendingTodosFromSession, sinkPendingTodos } from "./todo-sink.js";
 import { installEngramSettings, makeEngineConfigSchema, SETTINGS_KEYS } from "./settings.js";
@@ -128,6 +130,24 @@ const DEFAULTS = {
   jitMaxLines: 3,
   jitMaxLineChars: 220,
   engramJitOrder: 40.75,
+  // Session episode (v0.7-A): one compact, zero-LLM digest at teardown; feeds
+  // the resume brief and never enters the [ENGRAM] index.
+  episodeEnabled: true,
+  episodeMaxPerWorkspace: 20,
+  // Resume brief (v0.7-D): newest recent episode injected at session start.
+  resumeBriefEnabled: true,
+  resumeBriefMaxAgeDays: 7,
+  resumeBriefMaxChars: 240,
+  // Entity pages (v0.7-B): one-line cards in the index, full page on drill.
+  entityCardsEnabled: true,
+  entityCardsMax: 2,
+  entityCardChars: 160,
+  // Anchor revalidation + layered TTL (v0.7-C): file-anchored memories are
+  // re-stat'ed at session start; changed/missing sources are tagged `stale`
+  // and dropped from index/truth (never deleted).
+  anchorRevalidate: true,
+  episodeTtlDays: 14,
+  errorTtlDays: 60,
   // decision-point triggers (P0-A): promote a session plan to an ESR task
   // when the pending-todo count is at least minTodosForPromote and exceeds
   // active ESR tasks × todoPromoteRatio (default: pending > active).
@@ -339,6 +359,27 @@ export function apply(ctx, config) {
       log,
     });
 
+  // Expose the ledger to the per-session web plane. Agent presets mount
+  // `dsh-engram/compaction` in their own isolate realm, so a closure from this
+  // apply() is unreachable there; a plain (non-isolated) service value is the
+  // bridge: the row credits compaction savings through it and `ledger` stays
+  // the single writer of the durable rollup.
+  if (ledger !== null) {
+    try {
+      // `ctx.provide` is fiber-scoped (cordis removes the service when this
+      // plugin unloads), so the returned disposer needs no bookkeeping here.
+      ctx.provide?.("engramLedger", {
+        noteCompaction: (sessionId, workspace, opts) => ledger.noteCompaction(sessionId, workspace, opts),
+        notePrune: (sessionId, workspace, opts) => ledger.notePrune(sessionId, workspace, opts),
+        noteRewrite: (sessionId, workspace, opts) => ledger.noteRewrite(sessionId, workspace, opts),
+        summary: () => ledger.summary(),
+        flush: () => ledger.flush(),
+      });
+    } catch (error) {
+      log?.warn?.(`engram ledger service unavailable: ${String(error?.message ?? error)}`);
+    }
+  }
+
   // Ledger-driven off-switch for BoundaryPrune (PROPOSAL-evolution v0.6-B):
   // per-workspace, 30s-cached, reads the same summary /stats exposes. Evidence
   // can only turn pruning OFF. No ledger → allow (repayment gate still runs).
@@ -402,7 +443,9 @@ export function apply(ctx, config) {
     /** Live Context GC status (API overview + durable status file). */
     compactionStatus: {
       host: "pending",
-      web: { action: "pending", presets: [] },
+      // `disabled` (not `pending`) when the web opt-in is off: the status file
+      // must not look like a wiring run that never finished.
+      web: resolved.autoWebCompaction === false ? { action: "disabled", presets: [] } : { action: "pending", presets: [] },
       config: { autoWebCompaction: resolved.autoWebCompaction, gcReplacesCompaction: resolved.gcReplacesCompaction, gcNarrative: resolved.gcNarrative },
     },
     /** Recompute the exact [ENGRAM] block for a workspace (GUI overview cost). */
@@ -495,7 +538,21 @@ export function apply(ctx, config) {
     let pendingRecall = false;
     try {
       const workspace = resolvePath(cwd);
+      // Anchor revalidation (v0.7-C): a bounded stat pass at session start.
+      // Stale rows are tagged (for the GUI/GC) and excluded from the render
+      // below via memoryIsStale — never deleted, still re-fetchable.
+      if (resolved.anchorRevalidate !== false) {
+        for (const row of collectStaleAnchors(opened, workspace, { limit: 40 })) {
+          void opened.tagMemory(workspace, row.id, "stale")?.catch?.(() => null);
+        }
+      }
       block = renderIndex(opened, workspace, cwd, resolved);
+      // Resume brief (v0.7-D): the newest recent episode, frozen with the
+      // [ENGRAM] block. Empty when there is no recent episode.
+      if (resolved.resumeBriefEnabled !== false) {
+        const resume = renderResumeBrief(opened, workspace, resolved);
+        if (resume.length > 0) block = `${block}\n${resume}`.trim();
+      }
       // 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
@@ -632,6 +689,16 @@ export function apply(ctx, config) {
           return null;
         }
       },
+      // Context Ledger credit: the Context GC engine measures the span it
+      // replaced with a checkpoint (`span − summary` chars) and reports it
+      // here; the ledger stops the "savings are always 0" asymmetry.
+      onCompacted: ({ session, workspace, charsSaved }) => {
+        try {
+          ledger?.noteCompaction(session?.id, workspace ?? wk(session?.header?.cwd), { charsSaved });
+        } catch (error) {
+          log?.warn?.(`engram ledger compaction credit failed: ${String(error)}`);
+        }
+      },
     });
     disposers.push(() => {
       // The engine's service registration is fiber-scoped and auto-removed on
@@ -646,6 +713,10 @@ export function apply(ctx, config) {
     let hostSettled = false;
     let webSettled = resolved.autoWebCompaction === false;
     let statusTimer = void 0;
+    // Authoritative L1 availability, captured where BoundaryPrune is actually
+    // installed (the pruner may land after the first status flush on a slow
+    // boot; the live check is only a fallback).
+    let boundaryPruneState = void 0;
     const flushStatus = () => {
       if (!hostSettled || !webSettled) return;
       if (statusTimer !== void 0) { clearTimeout(statusTimer); statusTimer = void 0; }
@@ -653,6 +724,9 @@ export function apply(ctx, config) {
         planes: resolved.autoWebCompaction === false ? ["host"] : ["host", "web"],
         host: service.compactionStatus.host,
         web: service.compactionStatus.web,
+        // L1 availability is the missing credit path behind a "节省 always 0"
+        // ledger: record whether BoundaryPrune can actually fire here.
+        boundaryPrune: boundaryPruneState ?? boundaryPruneAvailability(ctx, resolved),
         config: service.compactionStatus.config,
         configSource: {
           autoWebCompaction: resolved.autoWebCompaction,
@@ -679,12 +753,15 @@ export function apply(ctx, config) {
     // inside the agent preset's own realm, which a profile patch cannot reach.
     // When the `agentPresets` service is present, swap the stock
     // `compaction-basic` row for `dsh-engram/compaction` in every stock-layout
-    // preset — the default one plus the whole roster (shipped + user roots) —
-    // so a session composed from any preset gets Context GC. Surgical,
-    // idempotent, backed up, validated; a preset with a custom compaction
-    // layout (or none) is never touched. The row's engine config is derived
-    // from the settings knobs (`gcReplacesCompaction` / `gcNarrative`), so
-    // changing them re-provisions the web rows on the next boot. Flip
+    // preset. The row is located structurally (indentation-agnostic) inside the
+    // `compaction` group, so both preset generations are covered: legacy
+    // compositions with `preset.path` (DSH ≤ 0.1.x) and the declarative
+    // `@deepseek-ai/dsh-web-app/presets/<id>.patch.yml` files (DSH ≥ 0.2.0,
+    // where the row sits at 14 spaces and the id maps to the shipped file).
+    // Surgical, idempotent, backed up, validated; a preset with a custom
+    // compaction layout (or none) is never touched. The row's engine config is
+    // derived from the settings knobs (`gcReplacesCompaction` / `gcNarrative`),
+    // so changing them re-provisions the web rows on the next boot. Flip
     // `autoWebCompaction:false` to stop auto-wiring on later boots (it does
     // not un-wire already-wired presets — use `npm run web-compaction:revert`
     // for that). Best-effort: a failure only warns.
@@ -846,6 +923,53 @@ export function apply(ctx, config) {
     });
     disposers.push(disposeSink);
 
+    // session-end episode digest (v0.7-A): one compact, zero-LLM record of the
+    // session's files/commands/failures/decisions/open loops. Never indexed;
+    // capped per workspace; the resume brief reads the newest recent one.
+    const disposeEpisode = ctx.on("session/disposed", (session) => {
+      if (resolved.episodeEnabled === false) return;
+      const cwd = session?.header?.cwd;
+      const sessionId = session?.id;
+      if (typeof cwd !== "string" || cwd.length === 0) return;
+      if (typeof sessionId !== "string" || sessionId.length === 0) return;
+      const episode = buildEpisode(session);
+      if (episode === null) return;
+      const workspace = wk(cwd);
+      const maxEpisodes = Number.isFinite(resolved.episodeMaxPerWorkspace)
+        ? Math.max(1, Math.trunc(resolved.episodeMaxPerWorkspace))
+        : 20;
+      service
+        .getDomain()
+        .then(async (domain) => {
+          await domain.storeMemory(
+            {
+              workspace,
+              kind: "episode",
+              text: episode.text,
+              tags: episode.tags,
+              signal: episode.signal,
+              filePath: null,
+              sessionId,
+              seq: Array.isArray(session.events) ? session.events.length : 0,
+            },
+            resolved,
+          );
+          const episodes = domain
+            .listMemories(workspace, 200)
+            .filter((memory) => memory.kind === "episode");
+          for (const old of episodes.slice(maxEpisodes)) {
+            try {
+              await domain.archiveMemory(workspace, old.id);
+            } catch {
+              // best-effort retention
+            }
+          }
+          log?.info?.(`engram episode: stored ${episode.text.length} chars in ${workspace}`);
+        })
+        .catch((error) => log?.warn?.(`engram episode failed: ${String(error)}`));
+    });
+    disposers.push(disposeEpisode);
+
     // zero-LLM auto-capture
     if (resolved.autoCapture) {
       // The capture handler needs a storeMemory face, but the domain opens
@@ -929,6 +1053,9 @@ export function apply(ctx, config) {
         },
       }, { allowFire: boundaryGate });
       disposers.push(disposeBoundaryPrune);
+      // BoundaryPrune is installed here, so this is the moment L1 provably can
+      // (or cannot) fire — record it for the durable status snapshot.
+      boundaryPruneState = boundaryPruneAvailability(ctx, resolved);
 
       // ResultPack L2 tool (default ON with L1 since v0.6): `result_recall(callId,
       // offset?)` pages back an archived middle. Independent of the memory

package/lib/settings.js

@@ -70,6 +70,9 @@ export const SETTINGS_KEYS = [
   "ledgerEnabled",
   "ledgerCacheDiscount",
   "jitEnabled",
+  "episodeEnabled",
+  "resumeBriefEnabled",
+  "entityCardsEnabled",
   "trustedHosts",
 ];
 
@@ -115,6 +118,9 @@ export function makeSettingsSchema(defaults) {
     ledgerEnabled: z.boolean().default(defaults.ledgerEnabled).description("上下文账本：按会话统计注入成本、剪枝/压缩节省与前缀重写罚金，输出净 token（/stats.ledger 与概览）；关掉=不记账、零写入"),
     ledgerCacheDiscount: z.number().min(0).max(1).default(defaults.ledgerCacheDiscount).description("账本缓存折价（0..1）：被剪枝前缀的重写按 (1−该系数) 计罚金；0.1 = 缓存命中只付 10%，重写付 90%（L0 保守假设）"),
     jitEnabled: z.boolean().default(defaults.jitEnabled).description("JIT 推送：错误复发 / 文件焦点 / goal 完成时把已有记忆压成一行推进上下文（append-only、每会话最多 3 行、无命中沉默；每次推送按前缀重写计入账本）"),
+    episodeEnabled: z.boolean().default(defaults.episodeEnabled).description("会话 episode：会话结束时用零 LLM 规则生成一条紧凑纪要（文件/命令/失败→修复/决策/未闭环），不进 [ENGRAM] 索引，供 resume brief 与实体页使用"),
+    resumeBriefEnabled: z.boolean().default(defaults.resumeBriefEnabled).description("恢复简报：新会话启动时注入最近 7 天的最新 episode（≤240 字符，含 engram_detail 指针），让隔天继续的项目不用重新交代背景"),
+    entityCardsEnabled: z.boolean().default(defaults.entityCardsEnabled).description("实体卡：[ENGRAM] 索引为活跃实体（有锚定记忆或未闭环任务）渲染一行「当前真相 + 打开任务 + engram_detail(entity=…) 指针」，替代平铺记忆行；最多 2 张"),
     // 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([]),

package/lib/store.js

@@ -22,6 +22,7 @@ import path from "node:path";
 import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 import { hashText, byRecency, uuid, now, truncate as truncateText, bm25Rank, tokenize as tokenizeLocal, dedupeBySession } from "./util.js";
 import { deriveObservations } from "./obs.js";
+import { makeFileAnchor } from "./anchor.js";
 import { redactText } from "./redact.js";
 
 export const DOMAIN_VERSION = 1;
@@ -36,8 +37,21 @@ const MEMORY_KINDS = [
   "insight",
   "handoff",
   "task",
+  "episode",
 ];
 
+const AnchorSchema = z.object({
+  /** Absolute file path the claim was written against. */
+  path: z.string().min(1),
+  /** Stat identity at write time — cheap revalidation (no read). */
+  mtimeMs: z.number().nonnegative(),
+  size: z.number().int().nonnegative(),
+  /** sha256[0..32] for files under the hash cap; null for large files. */
+  hash: z.string().nullable().default(null),
+  /** When the anchor was captured (epoch ms). */
+  at: z.number().int().nonnegative(),
+});
+
 const MemorySchema = z.object({
   /** Stable id (table key). */
   id: z.string().min(1),
@@ -61,6 +75,8 @@ const MemorySchema = z.object({
   lastAccessAt: z.number().int().nonnegative().nullable().default(null),
   /** Optional file anchor (absolute path). Sharpens error revival and recall display. */
   filePath: z.string().nullable().default(null),
+  /** Revalidatable stat/hash identity of `filePath` at write time (v0.7-C). */
+  anchor: AnchorSchema.nullable().default(null),
   /** 0..1 static signal; index threshold is minIndexSignal. */
   signal: z.number().min(0).max(1).default(0.5),
   status: z.enum(["active", "archived"]).default("active"),
@@ -448,6 +464,12 @@ export async function openEngramDomain(facility) {
       if ([...text].length > config.maxMemoryChars) {
         throw new EngramError("ENGRAM_CAP_EXCEEDED", `memory text is ${[...text].length} characters, over the cap of ${config.maxMemoryChars}`);
       }
+      const kind = entry.kind ?? "fact";
+      const anchor = entry.anchor !== void 0
+        ? entry.anchor
+        : (typeof entry.filePath === "string" && entry.filePath.length > 0
+          ? makeFileAnchor(entry.filePath, { baseDir: entry.workspace, now: now() })
+          : null);
       const all = allMemories(entry.workspace);
       let supersedes = validateRelationTarget(entry.workspace, entry.supersedes ?? null, "supersedes", all);
       const contradicts = validateRelationTarget(entry.workspace, entry.contradicts ?? null, "contradicts", all);
@@ -456,7 +478,12 @@ export async function openEngramDomain(facility) {
         // Repeat of the exact same failure is itself a signal: refresh recency
         // AND climb the hit counter (errors only) so the [ENGRAM] index can
         // eventually surface it via promoteHits.
-        const next = { ...dup, updatedAt: now(), ...(dup.kind === "error" ? { hits: (dup.hits ?? 0) + 1 } : {}) };
+        const next = {
+          ...dup,
+          updatedAt: now(),
+          ...(dup.kind === "error" ? { hits: (dup.hits ?? 0) + 1 } : {}),
+          ...(anchor !== null ? { anchor, filePath: dup.filePath ?? entry.filePath ?? null } : {}),
+        };
         await memories.put(dup.id, next);
         return { stored: next, duplicated: true, id: dup.id, revived: dup.kind === "error" };
       }
@@ -472,7 +499,13 @@ export async function openEngramDomain(facility) {
             prev.filePath !== null && entry.filePath !== null && prev.filePath === entry.filePath;
           if (!samePath && ratio < REPEAT_OVERLAP) continue;
           if (samePath && ratio < SAME_PATH_OVERLAP) continue;
-          const revived = { ...prev, updatedAt: now(), hits: (prev.hits ?? 0) + 1, filePath: prev.filePath ?? entry.filePath ?? null };
+          const revived = {
+            ...prev,
+            updatedAt: now(),
+            hits: (prev.hits ?? 0) + 1,
+            filePath: prev.filePath ?? entry.filePath ?? null,
+            ...(anchor !== null ? { anchor } : {}),
+          };
           await memories.put(prev.id, revived);
           return { stored: revived, duplicated: true, id: prev.id, revived: true };
         }
@@ -487,16 +520,25 @@ export async function openEngramDomain(facility) {
         const auto = autoSupersedeCandidate(all, entry, text);
         if (auto !== null) supersedes = auto.id;
       }
+      // Layered TTL (v0.7-C): user rules and proven procedures are permanent;
+      // session episodes are short-lived; errors age out faster than facts.
+      const DAY_MS = 24 * 60 * 60 * 1000;
+      const ttlDays = (() => {
+        if (kind === "preference" || kind === "procedure") return 0;
+        if (kind === "episode") return config.episodeTtlDays ?? 14;
+        if (kind === "error") return config.errorTtlDays ?? 60;
+        return config.expireDays ?? 180;
+      })();
       const expiresAt =
         entry.expiresAt !== void 0 && entry.expiresAt !== null
           ? entry.expiresAt
-          : config.expireDays > 0
-            ? now() + config.expireDays * 24 * 60 * 60 * 1000
+          : ttlDays > 0
+            ? now() + ttlDays * DAY_MS
             : null;
       const stored = {
         id: uuid(),
         workspace: entry.workspace,
-        kind: entry.kind ?? "fact",
+        kind,
         text,
         tags: entry.tags ?? [],
         entity: entry.entity ?? null,
@@ -507,6 +549,7 @@ export async function openEngramDomain(facility) {
         hits: 0,
         lastAccessAt: null,
         filePath: entry.filePath ?? null,
+        anchor: anchor ?? null,
         signal: typeof entry.signal === "number" ? Math.max(0, Math.min(1, entry.signal)) : 0.5,
         status: "active",
         supersedes,

package/lib/tools.js

@@ -19,6 +19,7 @@ import { z } from "zod";
 import { basename } from "node:path";
 import { EngramError, hasCode } from "./store.js";
 import { buildEsrStatusView } from "./index-block.js";
+import { buildEntityPage, renderEntityPage } from "./entity-page.js";
 import { truncate, shortId, slugId, fmtDate, escapeLt, workspaceKey as wk, uuid } from "./util.js";
 import { hasCJK, searchSessionsCJK } from "./session-cjk.js";
 
@@ -285,19 +286,40 @@ export function registerTools(ctx, service) {
       // ── engram_detail ───────────────────────────────────────────────────
       registerTool({
         name: "engram_detail",
-        description: "Full record of one memory id: text, tags, entity, signal, hits, session#seq provenance.",
+        description: "Full record of one memory id, or an entity page (truth/timeline/open loops/conflicts/relations) when `entity` is given.",
         parameters: {
           type: "object",
           properties: {
             id: { type: "string", description: "Memory id (e.g. the #xxxxx marker in the [ENGRAM] index is the first 8 chars)" },
+            entity: { type: "string", description: "Entity id or name — returns the full page (truth / timeline / open loops / conflicts / relations)" },
           },
-          required: ["id"],
         },
         output: TEXT_OUTPUT,
         execute: async (raw, exec) => {
-          const args = parse(z.object({ id: z.string().min(1) }), raw, "engram_detail");
+          const args = parse(
+            z.object({ id: z.string().optional(), entity: z.string().optional() }),
+            raw,
+            "engram_detail",
+          );
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
+          if (typeof args.entity === "string" && args.entity.trim().length > 0) {
+            const page = buildEntityPage(domain, caller.cwd, args.entity);
+            const registered = (domain.listEntities?.(caller.cwd) ?? []).some(
+              (entity) => entity.id === page?.entity?.id || entity.name === page?.entity?.name,
+            );
+            if (page === null || (!registered && page.counts.memories === 0 && page.counts.openTasks === 0)) {
+              const names = (domain.listEntities?.(caller.cwd) ?? []).slice(0, 8).map((entity) => entity.name);
+              throw new EngramError(
+                "ENGRAM_NOT_FOUND",
+                `no entity "${args.entity}" in this workspace${names.length > 0 ? ` (known: ${names.join(", ")})` : ""}`,
+              );
+            }
+            return renderEntityPage(page);
+          }
+          if (typeof args.id !== "string" || args.id.length === 0) {
+            throw new EngramError("ENGRAM_INVALID_ARGS", "engram_detail requires `id` or `entity`");
+          }
           const id = resolveId(domain, caller.cwd, args.id);
           const m = domain.getMemory(caller.cwd, id);
           if (m === void 0) throw new EngramError("ENGRAM_NOT_FOUND", `no active memory "${args.id}" in this workspace`);