dsh-engram 0.5.1 → 0.7.0

package/lib/ledger.js

@@ -0,0 +1,458 @@
+/**
+ * Context Ledger — the accounting layer of the "context portfolio"
+ * (docs/PROPOSAL-evolution.zh.md §4 v0.6-A).
+ *
+ * Every engram mechanism either spends context (injected index / recall / ESR
+ * blocks, held in the prompt prefix for the rest of the session) or saves it
+ * (pruned / compacted tool results that stop replaying). The ledger turns that
+ * into one auditable number per session, workspace and day:
+ *
+ *   net = avoided − injected − rewriteChars × (1 − cacheDiscount)
+ *
+ * where `rewriteChars` is the prefix size invalidated by a prune (KV cache
+ * break). `cacheDiscount` is the fraction a cached prefix would have cost
+ * (0.1 = 10%, the conservative L0 assumption), so the penalty is the
+ * non-discounted remainder.
+ *
+ * Zero LLM, deterministic, fail-contained. Two layers:
+ *   - live per-session accumulator, ticked by `assistant/message` events
+ *   - durable daily rollup at `~/.dsh/engram/ledger.json`, delta-flushed so a
+ *     restart loses at most `flushEvery` requests of accounting
+ *
+ * Deliberately NOT here: model-quality deltas, actual provider billing, and
+ * compaction savings whose before/after size the host does not expose yet.
+ * Those stay labelled assumptions, never invented numbers.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const FILE_NAME = "ledger.json";
+/** Matches the estimate used by the GUI (`chars / 4`). */
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_CACHE_DISCOUNT = 0.1;
+const DEFAULT_FLUSH_EVERY = 20;
+
+/** Default ledger file under the engram home. */
+export function ledgerFile(home = path.join(os.homedir(), ".dsh", "engram")) {
+  return path.join(home, FILE_NAME);
+}
+
+/** Local YYYY-MM-DD (calendar days for the user, mirrors usage.dayKey). */
+export function ledgerDayKey(now = Date.now()) {
+  const d = new Date(now);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function clampDiscount(value) {
+  if (!Number.isFinite(value)) return DEFAULT_CACHE_DISCOUNT;
+  return Math.min(1, Math.max(0, value));
+}
+
+function count(value) {
+  return Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
+}
+
+function emptyBucket() {
+  return {
+    sessions: 0,
+    requests: 0,
+    injectedChars: 0,
+    avoidedChars: 0,
+    rewriteCount: 0,
+    rewriteChars: 0,
+  };
+}
+
+function addBucket(target, delta) {
+  target.sessions += count(delta.sessions);
+  target.requests += count(delta.requests);
+  target.injectedChars += count(delta.injectedChars);
+  target.avoidedChars += count(delta.avoidedChars);
+  target.rewriteCount += count(delta.rewriteCount);
+  target.rewriteChars += count(delta.rewriteChars);
+  return target;
+}
+
+function deltaOf(session) {
+  const f = session.flushed;
+  return {
+    requests: session.requests - f.requests,
+    injectedChars: session.injectedChars - f.injectedChars,
+    avoidedChars: session.avoidedChars - f.avoidedChars,
+    rewriteCount: session.rewriteCount - f.rewriteCount,
+    rewriteChars: session.rewriteChars - f.rewriteChars,
+  };
+}
+
+function isEmptyDelta(delta) {
+  return (
+    delta.requests === 0 &&
+    delta.injectedChars === 0 &&
+    delta.avoidedChars === 0 &&
+    delta.rewriteCount === 0 &&
+    delta.rewriteChars === 0
+  );
+}
+
+/** Finalize one bucket with the net-token arithmetic (pure). */
+export function finalizeLedgerBucket(bucket, cacheDiscount = DEFAULT_CACHE_DISCOUNT) {
+  const discount = clampDiscount(cacheDiscount);
+  const injectedChars = count(bucket.injectedChars);
+  const avoidedChars = count(bucket.avoidedChars);
+  const rewriteChars = count(bucket.rewriteChars);
+  const netChars = avoidedChars - injectedChars - Math.round(rewriteChars * (1 - discount));
+  return {
+    sessions: count(bucket.sessions),
+    requests: count(bucket.requests),
+    injectedChars,
+    avoidedChars,
+    rewriteCount: count(bucket.rewriteCount),
+    rewriteChars,
+    injectedTokens: Math.ceil(injectedChars / CHARS_PER_TOKEN),
+    avoidedTokens: Math.ceil(avoidedChars / CHARS_PER_TOKEN),
+    netChars,
+    netTokens: Math.round(netChars / CHARS_PER_TOKEN),
+    rewritesCostChars: Math.round(rewriteChars * (1 - discount)),
+  };
+}
+
+function readPersisted(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (parsed === null || typeof parsed !== "object") return null;
+    if (parsed.version !== 1) return null;
+    if (parsed.workspaces === null || typeof parsed.workspaces !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Atomic-ish write: tmp + rename, so a crash never leaves a torn file. */
+function writeJsonAtomic(file, payload) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(payload)}\n`, "utf8");
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    // best-effort accounting — never throw into the session pipeline
+    return false;
+  }
+}
+
+function contentChars(content) {
+  if (!Array.isArray(content)) return 0;
+  let chars = 0;
+  for (const block of content) {
+    if (block === null || typeof block !== "object") continue;
+    if (typeof block.text === "string") chars += [...block.text].length;
+  }
+  return chars;
+}
+
+/**
+ * Estimate the live prefix size a prune invalidates (in Unicode code points).
+ *
+ * Walks the session surface through the same accessors the host pruner uses
+ * (`surface.nodes` → `eventAt` → `deriveEventMessage`). Fail-contained: an
+ * unknown session shape yields 0, which makes the ledger conservative about
+ * claiming savings.
+ */
+export function estimatePrefixChars(session) {
+  try {
+    const seqs = session?.surface?.nodes;
+    if (seqs === void 0 || seqs === null) return 0;
+    if (typeof session.eventAt !== "function" || typeof session.deriveEventMessage !== "function") return 0;
+    let chars = 0;
+    for (const seq of [...seqs]) {
+      const event = session.eventAt(seq);
+      if (event === void 0 || event === null) continue;
+      const message = session.deriveEventMessage(event);
+      chars += contentChars(message?.content);
+    }
+    return chars;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Create the in-memory ledger + durable rollup writer.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home] engram home (defaults to ~/.dsh/engram)
+ * @param {number} [opts.cacheDiscount] cached-prefix price share (0..1)
+ * @param {number} [opts.flushEvery] requests between durable flushes
+ * @param {boolean} [opts.persist] false = pure in-memory (tests, dry runs)
+ * @param {() => number} [opts.now] clock injection for tests
+ * @param {object} [opts.log] optional logger (warn only)
+ */
+export function createLedger({
+  home = path.join(os.homedir(), ".dsh", "engram"),
+  cacheDiscount = DEFAULT_CACHE_DISCOUNT,
+  flushEvery = DEFAULT_FLUSH_EVERY,
+  persist = true,
+  now = Date.now,
+  log = void 0,
+} = {}) {
+  const file = ledgerFile(home);
+  const discount = clampDiscount(cacheDiscount);
+  const every = Number.isFinite(flushEvery) && flushEvery > 0 ? Math.trunc(flushEvery) : 0;
+  const stored = persist ? readPersisted(file) : null;
+  const state = stored ?? { version: 1, updatedAt: 0, workspaces: {} };
+  const sessions = new Map();
+
+  function ensure(sessionId, workspace) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) return null;
+    let session = sessions.get(sessionId);
+    if (session === void 0) {
+      session = {
+        sessionId,
+        workspace: typeof workspace === "string" ? workspace : "",
+        indexChars: 0,
+        esrChars: 0,
+        jitChars: 0,
+        requests: 0,
+        injectedChars: 0,
+        avoidedChars: 0,
+        prunedChars: 0,
+        compactedChars: 0,
+        rewriteCount: 0,
+        rewriteChars: 0,
+        flushed: { requests: 0, injectedChars: 0, avoidedChars: 0, rewriteCount: 0, rewriteChars: 0 },
+        firstFlush: false,
+      };
+      sessions.set(sessionId, session);
+    } else if (typeof workspace === "string" && workspace.length > 0) {
+      session.workspace = workspace;
+    }
+    return session;
+  }
+
+  function bucketFor(workspace, day) {
+    const ws = typeof workspace === "string" && workspace.length > 0 ? workspace : "(unknown)";
+    const workspaces = state.workspaces;
+    if (workspaces[ws] === void 0 || workspaces[ws] === null || typeof workspaces[ws] !== "object") {
+      workspaces[ws] = {};
+    }
+    const days = workspaces[ws];
+    if (days[day] === void 0 || days[day] === null || typeof days[day] !== "object") {
+      days[day] = emptyBucket();
+    } else {
+      days[day] = { ...emptyBucket(), ...days[day] };
+    }
+    return days[day];
+  }
+
+  function flushSession(session) {
+    if (session === null || session === void 0) return false;
+    const delta = deltaOf(session);
+    if (isEmptyDelta(delta)) return false;
+    try {
+      const day = ledgerDayKey(now());
+      const bucket = bucketFor(session.workspace, day);
+      if (session.firstFlush === false) {
+        bucket.sessions += 1;
+        session.firstFlush = true;
+      }
+      addBucket(bucket, delta);
+      session.flushed = {
+        requests: session.requests,
+        injectedChars: session.injectedChars,
+        avoidedChars: session.avoidedChars,
+        rewriteCount: session.rewriteCount,
+        rewriteChars: session.rewriteChars,
+      };
+      state.updatedAt = now();
+      if (persist) writeJsonAtomic(file, state);
+      return true;
+    } catch (error) {
+      log?.warn?.(`engram ledger flush failed: ${String(error)}`);
+      return false;
+    }
+  }
+
+  function flush() {
+    for (const session of sessions.values()) flushSession(session);
+  }
+
+  return {
+    /** Record the latest injected block size for one component. */
+    noteInjection(sessionId, workspace, component, chars) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        const size = count(chars);
+        if (component === "esr") session.esrChars = size;
+        else if (component === "jit") session.jitChars = size;
+        else session.indexChars = size;
+      } catch (error) {
+        log?.warn?.(`engram ledger noteInjection failed: ${String(error)}`);
+      }
+    },
+
+    /** One model request completed: charge injected chars, credit savings. */
+    tick(sessionId, workspace) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.requests += 1;
+        session.injectedChars += session.indexChars + session.esrChars + session.jitChars;
+        session.avoidedChars += session.prunedChars + session.compactedChars;
+        if (every > 0 && session.requests % every === 0) flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger tick failed: ${String(error)}`);
+      }
+    },
+
+    /** A prune fired: its removed chars stop replaying from the next request. */
+    notePrune(sessionId, workspace, { charsRemoved = 0, rewriteChars = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.prunedChars += count(charsRemoved);
+        session.rewriteCount += 1;
+        session.rewriteChars += count(rewriteChars);
+        flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger notePrune failed: ${String(error)}`);
+      }
+    },
+
+    /** A compaction replaced history: the saved chars stop replaying too. */
+    noteCompaction(sessionId, workspace, { charsSaved = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.compactedChars += count(charsSaved);
+      } catch (error) {
+        log?.warn?.(`engram ledger noteCompaction failed: ${String(error)}`);
+      }
+    },
+
+    /**
+     * A prefix rewrite that is not a prune (e.g. a JIT push appended to the
+     * prompt): charge the full prefix invalidation, credit nothing.
+     */
+    noteRewrite(sessionId, workspace, { chars = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.rewriteCount += 1;
+        session.rewriteChars += count(chars);
+        flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger noteRewrite failed: ${String(error)}`);
+      }
+    },
+
+    /** Session ended: fold the tail into the durable rollup and forget it. */
+    dispose(sessionId) {
+      try {
+        const session = sessions.get(sessionId);
+        if (session === void 0) return;
+        flushSession(session);
+        sessions.delete(sessionId);
+      } catch (error) {
+        log?.warn?.(`engram ledger dispose failed: ${String(error)}`);
+      }
+    },
+
+    flush,
+
+    /**
+     * Read the ledger: persisted rollup + unflushed live deltas. Pure (never
+     * mutates state), so /stats can call it on every request.
+     */
+    summary() {
+      const byWorkspace = {};
+      const byDay = {};
+
+      // persisted floor
+      for (const [ws, days] of Object.entries(state.workspaces ?? {})) {
+        if (days === null || typeof days !== "object") continue;
+        const wsBucket = (byWorkspace[ws] ??= emptyBucket());
+        for (const [day, bucket] of Object.entries(days)) {
+          if (bucket === null || typeof bucket !== "object") continue;
+          addBucket(wsBucket, bucket);
+          const dayBucket = (byDay[day] ??= emptyBucket());
+          addBucket(dayBucket, bucket);
+        }
+      }
+
+      // live, not-yet-flushed tail
+      const today = ledgerDayKey(now());
+      for (const session of sessions.values()) {
+        const delta = deltaOf(session);
+        if (isEmptyDelta(delta)) continue;
+        const ws = session.workspace.length > 0 ? session.workspace : "(unknown)";
+        const wsBucket = (byWorkspace[ws] ??= emptyBucket());
+        if (session.firstFlush === false) wsBucket.sessions += 1;
+        addBucket(wsBucket, delta);
+        const dayBucket = (byDay[today] ??= emptyBucket());
+        if (session.firstFlush === false) dayBucket.sessions += 1;
+        addBucket(dayBucket, delta);
+      }
+
+      const totals = emptyBucket();
+      for (const bucket of Object.values(byWorkspace)) addBucket(totals, bucket);
+
+      const finalizedWorkspaces = {};
+      for (const [ws, bucket] of Object.entries(byWorkspace)) {
+        finalizedWorkspaces[ws] = finalizeLedgerBucket(bucket, discount);
+      }
+      const finalizedDays = Object.entries(byDay)
+        .map(([day, bucket]) => ({ day, ...finalizeLedgerBucket(bucket, discount) }))
+        .sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : 0));
+
+      return {
+        version: 1,
+        updatedAt: state.updatedAt ?? 0,
+        charsPerToken: CHARS_PER_TOKEN,
+        cacheDiscount: discount,
+        openSessions: sessions.size,
+        totals: finalizeLedgerBucket(totals, discount),
+        byWorkspace: finalizedWorkspaces,
+        byDay: finalizedDays,
+      };
+    },
+  };
+}
+
+/** Read the durable ledger without creating a live instance (GUI / tests). */
+export function readLedger({ home, cacheDiscount = DEFAULT_CACHE_DISCOUNT } = {}) {
+  const stored = readPersisted(ledgerFile(home));
+  const workspaces = {};
+  const days = {};
+  if (stored !== null) {
+    for (const [ws, wsDays] of Object.entries(stored.workspaces)) {
+      if (wsDays === null || typeof wsDays !== "object") continue;
+      const wsBucket = (workspaces[ws] ??= emptyBucket());
+      for (const [day, bucket] of Object.entries(wsDays)) {
+        if (bucket === null || typeof bucket !== "object") continue;
+        addBucket(wsBucket, bucket);
+        addBucket((days[day] ??= emptyBucket()), bucket);
+      }
+    }
+  }
+  const totals = emptyBucket();
+  for (const bucket of Object.values(workspaces)) addBucket(totals, bucket);
+  return {
+    version: 1,
+    updatedAt: stored?.updatedAt ?? 0,
+    charsPerToken: CHARS_PER_TOKEN,
+    cacheDiscount: clampDiscount(cacheDiscount),
+    totals: finalizeLedgerBucket(totals, cacheDiscount),
+    byWorkspace: Object.fromEntries(
+      Object.entries(workspaces).map(([ws, bucket]) => [ws, finalizeLedgerBucket(bucket, cacheDiscount)]),
+    ),
+    byDay: Object.entries(days)
+      .map(([day, bucket]) => ({ day, ...finalizeLedgerBucket(bucket, cacheDiscount) }))
+      .sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : 0)),
+  };
+}

package/lib/settings.js

@@ -43,6 +43,7 @@ export const SETTINGS_KEYS = [
   "autoCapture",
   "autoCapturePreferences",
   "boundaryPrune",
+  "boundaryPruneAdaptive",
   "boundaryPruneThresholdChars",
   "boundaryPruneIdleCadence",
   "resultPack",
@@ -66,6 +67,12 @@ export const SETTINGS_KEYS = [
   "autoSupersede",
   "autoSinkTodosOnEnd",
   "autoWebCompaction",
+  "ledgerEnabled",
+  "ledgerCacheDiscount",
+  "jitEnabled",
+  "episodeEnabled",
+  "resumeBriefEnabled",
+  "entityCardsEnabled",
   "trustedHosts",
 ];
 
@@ -83,10 +90,11 @@ export function makeSettingsSchema(defaults) {
   return z.object({
     autoCapture: z.boolean().default(defaults.autoCapture),
     autoCapturePreferences: z.boolean().default(defaults.autoCapturePreferences).description("用户纠正/偏好学习（零 LLM）：检测用户消息里的显式 prefer/avoid/switch-to 句式，自动沉淀为 preference 记忆并置顶 [ENGRAM] 索引（correx/PAHF 式偏好提取；关掉=只靠手动 engram_store）"),
-    boundaryPrune: z.boolean().default(defaults.boundaryPrune).description("ResultPack L1（BoundaryPrune 边界剪枝）：在 todo 完成推进 / goal 终态这些子任务边界，主动调用 DSH 的确定性 toolResultPruner 剪掉超阈值旧工具结果（SoL-Pi Online Context Compact；默认关）"),
+    boundaryPrune: z.boolean().default(defaults.boundaryPrune).description("ResultPack L1（BoundaryPrune 边界剪枝）：在 todo 完成推进 / goal 终态这些子任务边界，主动调用 DSH 的确定性 toolResultPruner 剪掉超阈值旧工具结果（SoL-Pi Online Context Compact；默认开，false=关）"),
+    boundaryPruneAdaptive: z.boolean().default(defaults.boundaryPruneAdaptive).description("剪枝自适应（账本否决）：当 Context Ledger 显示该 workspace 在真实剪枝后净收益为负（≥3 次剪枝）时自动停止继续剪；证据只能关、不会自行开；关掉=只受偿还门约束"),
     boundaryPruneThresholdChars: z.natural().default(0).description("边界剪枝阈值覆盖（字符）：宿主 pruner 固定 8192；设更低（如 2048）可更早开剪——L0 仿真显示 T2048 净收益最高（+61.6Mc），前提是 L2 归档已开启可找回被剪中段；0=用宿主 8192"),
     boundaryPruneIdleCadence: z.natural().default(0).description("空闲步数边界（请求计数）：最多每 N 个请求触发一次剪枝，覆盖无 todo/goal 的会话（约 62% 会话永不触发事件边界）；仍受偿还门约束；0=仅事件边界"),
-    resultPack: z.boolean().default(defaults.resultPack).description("ResultPack L2（结果归档召回）：BoundaryPrune 剪掉的中段脱敏归档到本地，剪枝节点尾部追加 handle，模型可用 result_recall(callId) 按页召回（完整 ObservationPack；需与 boundaryPrune 一起开，L2 本身默认关）"),
+    resultPack: z.boolean().default(defaults.resultPack).description("ResultPack L2（结果归档召回）：BoundaryPrune 剪掉的中段脱敏归档到本地，剪枝节点尾部追加 handle，模型可用 result_recall(callId) 按页召回（完整 ObservationPack；默认开，保证默认剪枝无损；需与 boundaryPrune 一起开）"),
     sessionSearch: z.boolean().default(defaults.sessionSearch),
     recallScope: z.union(["workspace", "global"]).default(defaults.recallScope ?? "workspace").description("召回范围：workspace=严格按当前工作区隔离（默认、token 纪律）；global=本工作区命中弱/空时，从其它工作区池按 recency/origin 加权召回并标 [W:<workspace>] 来源。开启会打破跨工作区隔离，请按需选用"),
     autoRecallOnStart: z.boolean().default(defaults.autoRecallOnStart).description("新会话开始时，宿主按首条消息对工作区做确定性召回，把命中记忆直接注入 [RECALL] 块（无需模型自己想起调 engram_recall；关掉=回到纯拉取）"),
@@ -101,12 +109,18 @@ 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),
-    gcReplacesCompaction: z.boolean().default(defaults.gcReplacesCompaction),
+    gcReplacesCompaction: z.boolean().default(defaults.gcReplacesCompaction).description("Context GC 接管 DSH 自动 compact（指针摘要替代有损 LLM 摘要）；默认关=保留宿主 summarizer。改写宿主预设是最高维护风险，需显式开启"),
     gcNarrative: z.boolean().default(defaults.gcNarrative),
     verifyArtifact: z.boolean().default(defaults.verifyArtifact).description("ESR 闭环时校验 artifact 路径真实存在"),
     autoSupersede: z.boolean().default(defaults.autoSupersede).description("实体锚定 + 替换式更新（改用/不再…）自动把旧记忆标为 superseded（默认关）"),
     autoSinkTodosOnEnd: z.boolean().default(defaults.autoSinkTodosOnEnd).description("会话结束时把仍 pending 的 todo 自动沉淀为 ESR draft 任务（去重、受容量上限约束；关掉=会话结束即弃）"),
-    autoWebCompaction: z.boolean().default(defaults.autoWebCompaction).description("web 面启动时把全部 stock 布局的 agent 预设（shipped + 用户根）的 compaction 组自动换成 dsh-engram/compaction（带备份、幂等、不碰自定义/无 compaction 预设；关掉=不再自动接管，已接管的预设保持 Context GC、需 npm run web-compaction:revert 还原，host 面不受影响）"),
+    autoWebCompaction: z.boolean().default(defaults.autoWebCompaction).description("web 面启动时把全部 stock 布局的 agent 预设（shipped + 用户根）的 compaction 组自动换成 dsh-engram/compaction（带备份、幂等、不碰自定义/无 compaction 预设）。默认关（opt-in）：不主动改写任何预设；已接管的预设保持 Context GC、需 npm run web-compaction:revert 还原，host 面不受影响"),
+    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`);