@joshuaswarren/openclaw-engram 9.0.35 → 9.0.37

package/README.md

@@ -38,6 +38,7 @@ AI agents forget everything between conversations. Engram fixes that.
 - **Trust-zone recall** — Engram can now, when `trustZoneRecallEnabled` is enabled, inject prompt-relevant `working` and `trusted` trust-zone records into recall context as a separate `Trust Zones` section while keeping `quarantine` material out of recall by default.
 - **Poisoning-defense corroboration** — Engram can now, when `memoryPoisoningDefenseEnabled` is enabled, score trust-zone provenance deterministically and require independent non-quarantine corroboration before risky `working -> trusted` promotions succeed.
 - **Red-team benchmark packs** — Engram's eval harness can now validate and count typed `memory-red-team` benchmark packs so poisoning-defense regression suites stay explicit and reviewable instead of hiding inside generic benchmark metadata.
+- **Cue-anchor index foundation** — Engram can now, when `harmonicRetrievalEnabled` and `abstractionAnchorsEnabled` are enabled, persist typed cue anchors for entities, files, tools, outcomes, constraints, and dates, inspect them with `openclaw engram cue-anchor-status`, and keep harmonic retrieval grounded in explicit abstraction-to-cue links before blending logic lands.
 - **Zero-config start** — Install, add an API key, restart. Engram works out of the box with sensible defaults and progressively unlocks advanced features as you enable them.
 
 ## Quick Start

package/dist/index.js

@@ -302,6 +302,9 @@ function parseConfig(raw) {
     trustZoneRecallEnabled: cfg.trustZoneRecallEnabled === true,
     memoryPoisoningDefenseEnabled: cfg.memoryPoisoningDefenseEnabled === true,
     memoryRedTeamBenchEnabled: cfg.memoryRedTeamBenchEnabled === true,
+    harmonicRetrievalEnabled: cfg.harmonicRetrievalEnabled === true,
+    abstractionAnchorsEnabled: cfg.abstractionAnchorsEnabled === true,
+    abstractionNodeStoreDir: typeof cfg.abstractionNodeStoreDir === "string" && cfg.abstractionNodeStoreDir.trim().length > 0 ? cfg.abstractionNodeStoreDir.trim() : path.join(memoryDir, "state", "abstraction-nodes"),
     // Local LLM Provider (v2.1)
     localLlmEnabled: cfg.localLlmEnabled === true || cfg.localLlmEnabled === "true",
     // default: false
@@ -24220,7 +24223,7 @@ promotionCandidates: ${res.promotionCandidateCount}`
 }
 
 // src/cli.ts
-import path54 from "path";
+import path56 from "path";
 import { access as access3, readFile as readFile37, readdir as readdir24, unlink as unlink7 } from "fs/promises";
 import { createHash as createHash10 } from "crypto";
 
@@ -25101,8 +25104,8 @@ function gatherCandidates(input, warnings) {
       const record = rec;
       const content = typeof record.content === "string" ? record.content : null;
       if (!content) continue;
-      const path56 = typeof record.path === "string" ? record.path : "";
-      if (!path56.startsWith("transcripts/") && !path56.includes("/transcripts/")) continue;
+      const path58 = typeof record.path === "string" ? record.path : "";
+      if (!path58.startsWith("transcripts/") && !path58.includes("/transcripts/")) continue;
       rows.push(...parseJsonl(content, warnings));
     }
     return rows;
@@ -26736,6 +26739,171 @@ async function runCompatChecks(options) {
   };
 }
 
+// src/abstraction-nodes.ts
+import path54 from "path";
+import { mkdir as mkdir36, writeFile as writeFile33 } from "fs/promises";
+function validateKind2(raw) {
+  const value = assertString2(raw, "kind");
+  if (!["episode", "topic", "project", "workflow", "constraint"].includes(value)) {
+    throw new Error("kind must be one of episode|topic|project|workflow|constraint");
+  }
+  return value;
+}
+function validateLevel(raw) {
+  const value = assertString2(raw, "abstractionLevel");
+  if (!["micro", "meso", "macro"].includes(value)) {
+    throw new Error("abstractionLevel must be one of micro|meso|macro");
+  }
+  return value;
+}
+function resolveAbstractionNodeStoreDir(memoryDir, overrideDir) {
+  if (typeof overrideDir === "string" && overrideDir.trim().length > 0) {
+    return overrideDir.trim();
+  }
+  return path54.join(memoryDir, "state", "abstraction-nodes");
+}
+function validateAbstractionNode(raw) {
+  if (!isRecord2(raw)) throw new Error("abstraction node must be an object");
+  if (raw.schemaVersion !== 1) throw new Error("schemaVersion must be 1");
+  return {
+    schemaVersion: 1,
+    nodeId: assertSafePathSegment(assertString2(raw.nodeId, "nodeId"), "nodeId"),
+    recordedAt: assertIsoRecordedAt(assertString2(raw.recordedAt, "recordedAt")),
+    sessionKey: assertString2(raw.sessionKey, "sessionKey"),
+    kind: validateKind2(raw.kind),
+    abstractionLevel: validateLevel(raw.abstractionLevel),
+    title: assertString2(raw.title, "title"),
+    summary: assertString2(raw.summary, "summary"),
+    sourceMemoryIds: optionalStringArray2(raw.sourceMemoryIds, "sourceMemoryIds"),
+    entityRefs: optionalStringArray2(raw.entityRefs, "entityRefs"),
+    tags: optionalStringArray2(raw.tags, "tags"),
+    metadata: validateStringRecord(raw.metadata, "metadata")
+  };
+}
+async function getAbstractionNodeStoreStatus(options) {
+  const rootDir = resolveAbstractionNodeStoreDir(options.memoryDir, options.abstractionNodeStoreDir);
+  const nodesDir = path54.join(rootDir, "nodes");
+  const files = await listJsonFiles(nodesDir);
+  const nodes = [];
+  const invalidNodes = [];
+  for (const filePath of files) {
+    try {
+      nodes.push(validateAbstractionNode(await readJsonFile(filePath)));
+    } catch (error) {
+      invalidNodes.push({
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  nodes.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
+  const byKind = {};
+  const byLevel = {};
+  for (const node of nodes) {
+    byKind[node.kind] = (byKind[node.kind] ?? 0) + 1;
+    byLevel[node.abstractionLevel] = (byLevel[node.abstractionLevel] ?? 0) + 1;
+  }
+  return {
+    enabled: options.enabled,
+    anchorsEnabled: options.anchorsEnabled,
+    rootDir,
+    nodesDir,
+    nodes: {
+      total: files.length,
+      valid: nodes.length,
+      invalid: invalidNodes.length,
+      byKind,
+      byLevel,
+      latestNodeId: nodes[0]?.nodeId,
+      latestRecordedAt: nodes[0]?.recordedAt,
+      latestSessionKey: nodes[0]?.sessionKey
+    },
+    latestNode: nodes[0],
+    invalidNodes
+  };
+}
+
+// src/cue-anchors.ts
+import path55 from "path";
+import { mkdir as mkdir37, writeFile as writeFile34 } from "fs/promises";
+function validateAnchorType(raw) {
+  const value = assertString2(raw, "anchorType");
+  if (!["entity", "file", "tool", "outcome", "constraint", "date"].includes(value)) {
+    throw new Error("anchorType must be one of entity|file|tool|outcome|constraint|date");
+  }
+  return value;
+}
+function validateNodeRefs(raw) {
+  const nodeRefs = optionalStringArray2(raw, "nodeRefs");
+  if (!nodeRefs || nodeRefs.length === 0) {
+    throw new Error("nodeRefs must contain at least one node reference");
+  }
+  return nodeRefs.map((nodeRef, index) => assertSafePathSegment(nodeRef, `nodeRefs[${index}]`));
+}
+function resolveCueAnchorStoreDir(abstractionNodeStoreDir, overrideDir) {
+  if (typeof overrideDir === "string" && overrideDir.trim().length > 0) {
+    return overrideDir.trim();
+  }
+  return path55.join(abstractionNodeStoreDir, "anchors");
+}
+function validateCueAnchor(raw) {
+  if (!isRecord2(raw)) throw new Error("cue anchor must be an object");
+  if (raw.schemaVersion !== 1) throw new Error("schemaVersion must be 1");
+  return {
+    schemaVersion: 1,
+    anchorId: assertSafePathSegment(assertString2(raw.anchorId, "anchorId"), "anchorId"),
+    anchorType: validateAnchorType(raw.anchorType),
+    anchorValue: assertString2(raw.anchorValue, "anchorValue"),
+    normalizedCue: assertString2(raw.normalizedCue, "normalizedCue"),
+    recordedAt: assertIsoRecordedAt(assertString2(raw.recordedAt, "recordedAt")),
+    sessionKey: assertString2(raw.sessionKey, "sessionKey"),
+    nodeRefs: validateNodeRefs(raw.nodeRefs),
+    tags: optionalStringArray2(raw.tags, "tags"),
+    metadata: validateStringRecord(raw.metadata, "metadata")
+  };
+}
+async function getCueAnchorStoreStatus(options) {
+  const abstractionNodeStoreDir = options.abstractionNodeStoreDir?.trim().length ? options.abstractionNodeStoreDir.trim() : path55.join(options.memoryDir, "state", "abstraction-nodes");
+  const rootDir = resolveCueAnchorStoreDir(abstractionNodeStoreDir, options.cueAnchorStoreDir);
+  const files = await listJsonFiles(rootDir);
+  const anchors = [];
+  const invalidAnchors = [];
+  for (const filePath of files) {
+    try {
+      anchors.push(validateCueAnchor(await readJsonFile(filePath)));
+    } catch (error) {
+      invalidAnchors.push({
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  anchors.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
+  const byType = {};
+  let totalNodeRefs = 0;
+  for (const anchor of anchors) {
+    byType[anchor.anchorType] = (byType[anchor.anchorType] ?? 0) + 1;
+    totalNodeRefs += anchor.nodeRefs.length;
+  }
+  return {
+    enabled: options.enabled,
+    anchorsEnabled: options.anchorsEnabled,
+    rootDir,
+    anchors: {
+      total: files.length,
+      valid: anchors.length,
+      invalid: invalidAnchors.length,
+      byType,
+      totalNodeRefs,
+      latestAnchorId: anchors[0]?.anchorId,
+      latestRecordedAt: anchors[0]?.recordedAt,
+      latestSessionKey: anchors[0]?.sessionKey
+    },
+    latestAnchor: anchors[0],
+    invalidAnchors
+  };
+}
+
 // src/cli.ts
 function rankCandidateForKeep(a, b) {
   const aConfidence = typeof a.frontmatter.confidence === "number" ? a.frontmatter.confidence : 0;
@@ -26945,6 +27113,22 @@ async function runTrustZoneStatusCliCommand(options) {
     poisoningDefenseEnabled: options.memoryPoisoningDefenseEnabled
   });
 }
+async function runAbstractionNodeStatusCliCommand(options) {
+  return getAbstractionNodeStoreStatus({
+    memoryDir: options.memoryDir,
+    abstractionNodeStoreDir: options.abstractionNodeStoreDir,
+    enabled: options.harmonicRetrievalEnabled,
+    anchorsEnabled: options.abstractionAnchorsEnabled
+  });
+}
+async function runCueAnchorStatusCliCommand(options) {
+  return getCueAnchorStoreStatus({
+    memoryDir: options.memoryDir,
+    abstractionNodeStoreDir: options.abstractionNodeStoreDir,
+    enabled: options.harmonicRetrievalEnabled,
+    anchorsEnabled: options.abstractionAnchorsEnabled
+  });
+}
 async function runTrustZonePromoteCliCommand(options) {
   const result = await promoteTrustZoneRecord({
     memoryDir: options.memoryDir,
@@ -27191,7 +27375,7 @@ function policyVersionForValues(values, config) {
   return createHash10("sha256").update(JSON.stringify(normalized)).digest("hex").slice(0, 12);
 }
 async function readRuntimePolicySnapshot2(config, fileName) {
-  const filePath = path54.join(config.memoryDir, "state", fileName);
+  const filePath = path56.join(config.memoryDir, "state", fileName);
   const snapshot = await readRuntimePolicySnapshot(filePath, {
     maxStaleDecayThreshold: config.lifecycleArchiveDecayThreshold
   });
@@ -27775,14 +27959,14 @@ async function resolveMemoryDirForNamespace(orchestrator, namespace) {
   const ns = (namespace ?? "").trim();
   if (!ns) return orchestrator.config.memoryDir;
   if (!orchestrator.config.namespacesEnabled) return orchestrator.config.memoryDir;
-  const candidate = path54.join(orchestrator.config.memoryDir, "namespaces", ns);
+  const candidate = path56.join(orchestrator.config.memoryDir, "namespaces", ns);
   if (ns === orchestrator.config.defaultNamespace) {
     return await exists2(candidate) ? candidate : orchestrator.config.memoryDir;
   }
   return candidate;
 }
 async function readAllMemoryFiles(memoryDir) {
-  const roots = [path54.join(memoryDir, "facts"), path54.join(memoryDir, "corrections")];
+  const roots = [path56.join(memoryDir, "facts"), path56.join(memoryDir, "corrections")];
   const out = [];
   const walk = async (dir) => {
     let entries;
@@ -27793,7 +27977,7 @@ async function readAllMemoryFiles(memoryDir) {
     }
     for (const entry of entries) {
       const entryName = typeof entry.name === "string" ? entry.name : entry.name.toString("utf-8");
-      const fullPath = path54.join(dir, entryName);
+      const fullPath = path56.join(dir, entryName);
       if (entry.isDirectory()) {
         await walk(fullPath);
         continue;
@@ -28136,6 +28320,26 @@ function registerCli(api, orchestrator) {
         console.log(JSON.stringify(status, null, 2));
         console.log("OK");
       });
+      cmd.command("abstraction-node-status").description("Show abstraction-node store status, abstraction counts, and latest stored node").action(async () => {
+        const status = await runAbstractionNodeStatusCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          abstractionNodeStoreDir: orchestrator.config.abstractionNodeStoreDir,
+          harmonicRetrievalEnabled: orchestrator.config.harmonicRetrievalEnabled,
+          abstractionAnchorsEnabled: orchestrator.config.abstractionAnchorsEnabled
+        });
+        console.log(JSON.stringify(status, null, 2));
+        console.log("OK");
+      });
+      cmd.command("cue-anchor-status").description("Show cue-anchor index status, anchor counts, and the latest stored cue anchor").action(async () => {
+        const status = await runCueAnchorStatusCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          abstractionNodeStoreDir: orchestrator.config.abstractionNodeStoreDir,
+          harmonicRetrievalEnabled: orchestrator.config.harmonicRetrievalEnabled,
+          abstractionAnchorsEnabled: orchestrator.config.abstractionAnchorsEnabled
+        });
+        console.log(JSON.stringify(status, null, 2));
+        console.log("OK");
+      });
       cmd.command("trust-zone-promote").description("Dry-run or apply a trust-zone promotion with provenance enforcement").requiredOption("--record-id <recordId>", "Source trust-zone record id").requiredOption("--target-zone <targetZone>", "Promotion target zone (working|trusted)").requiredOption("--reason <reason>", "Human-readable promotion reason").option("--recorded-at <isoTimestamp>", "Promotion timestamp (defaults to now)").option("--summary <summary>", "Optional replacement summary for the promoted record").option("--dry-run", "Show the promotion plan without writing the promoted record").action(async (...args) => {
         const options = args[0] ?? {};
         const result = await runTrustZonePromoteCliCommand({
@@ -28803,7 +29007,7 @@ function registerCli(api, orchestrator) {
         }
       });
       cmd.command("identity").description("Show agent identity reflections").action(async () => {
-        const workspaceDir = path54.join(process.env.HOME ?? "~", ".openclaw", "workspace");
+        const workspaceDir = path56.join(process.env.HOME ?? "~", ".openclaw", "workspace");
         const identity = await orchestrator.storage.readIdentity(workspaceDir);
         if (!identity) {
           console.log("No identity file found.");
@@ -29026,8 +29230,8 @@ function registerCli(api, orchestrator) {
         const options = args[0] ?? {};
         const threadId = options.thread;
         const top = parseInt(options.top ?? "10", 10);
-        const memoryDir = path54.join(process.env.HOME ?? "~", ".openclaw", "workspace", "memory", "local");
-        const threading = new ThreadingManager(path54.join(memoryDir, "threads"));
+        const memoryDir = path56.join(process.env.HOME ?? "~", ".openclaw", "workspace", "memory", "local");
+        const threading = new ThreadingManager(path56.join(memoryDir, "threads"));
         if (threadId) {
           const thread = await threading.loadThread(threadId);
           if (!thread) {
@@ -29503,9 +29707,9 @@ async function recordObjectiveStateSnapshotsFromAgentMessages(options) {
 }
 
 // src/index.ts
-import { readFile as readFile38, writeFile as writeFile33 } from "fs/promises";
+import { readFile as readFile38, writeFile as writeFile35 } from "fs/promises";
 import { readFileSync as readFileSync4 } from "fs";
-import path55 from "path";
+import path57 from "path";
 import os6 from "os";
 var ENGRAM_REGISTERED_GUARD = "__openclawEngramRegistered";
 var ENGRAM_HOOK_APIS = "__openclawEngramHookApis";
@@ -29513,7 +29717,7 @@ function loadPluginConfigFromFile() {
   try {
     const explicitConfigPath = process.env.OPENCLAW_ENGRAM_CONFIG_PATH || process.env.OPENCLAW_CONFIG_PATH;
     const homeDir = process.env.HOME ?? os6.homedir();
-    const configPath = explicitConfigPath && explicitConfigPath.length > 0 ? explicitConfigPath : path55.join(homeDir, ".openclaw", "openclaw.json");
+    const configPath = explicitConfigPath && explicitConfigPath.length > 0 ? explicitConfigPath : path57.join(homeDir, ".openclaw", "openclaw.json");
     const content = readFileSync4(configPath, "utf-8");
     const config = JSON.parse(content);
     const pluginEntry = config?.plugins?.entries?.["openclaw-engram"];
@@ -29763,11 +29967,11 @@ Use this context naturally when relevant. Never quote or expose this memory cont
                 `session reset via API for ${sessionKey}, new sessionId=${result.sessionId}`
               );
               const safeSessionKey = sanitizeSessionKeyForFilename(sessionKey);
-              const signalPath = path55.join(
+              const signalPath = path57.join(
                 workspaceDir,
                 `.compaction-reset-signal-${safeSessionKey}`
               );
-              await writeFile33(
+              await writeFile35(
                 signalPath,
                 JSON.stringify({
                   sessionKey,
@@ -29794,7 +29998,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
     );
     async function ensureHourlySummaryCron(api2) {
       const jobId = "engram-hourly-summary";
-      const cronFilePath = path55.join(os6.homedir(), ".openclaw", "cron", "jobs.json");
+      const cronFilePath = path57.join(os6.homedir(), ".openclaw", "cron", "jobs.json");
       try {
         let jobsData = { version: 1, jobs: [] };
         try {
@@ -29835,7 +30039,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
           state: {}
         };
         jobsData.jobs.push(newJob);
-        await writeFile33(cronFilePath, JSON.stringify(jobsData, null, 2), "utf-8");
+        await writeFile35(cronFilePath, JSON.stringify(jobsData, null, 2), "utf-8");
         log.info("auto-registered hourly summary cron job");
       } catch (err) {
         log.error("failed to auto-register hourly summary cron job:", err);