dsh-engram 0.6.0 → 0.7.0

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`);

package/package.json

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