@joshuaswarren/openclaw-engram 9.0.28 → 9.0.29

package/README.md

@@ -34,6 +34,7 @@ AI agents forget everything between conversations. Engram fixes that.
 - **Objective-state recall** — Engram can now store normalized file, process, and tool outcomes and, when `objectiveStateRecallEnabled` is enabled, inject the most relevant objective-state snapshots back into recall context as a separate `Objective State` section.
 - **Causal trajectory graph foundation** — Engram can now persist typed `goal -> action -> observation -> outcome -> follow-up` chains when `causalTrajectoryMemoryEnabled` is enabled and, with `actionGraphRecallEnabled`, emit deterministic action-conditioned edges into the causal graph for later trajectory-aware retrieval.
 - **Causal trajectory recall** — Engram can now, when `causalTrajectoryRecallEnabled` is enabled, inject prompt-relevant causal chains back into recall context as a separate `Causal Trajectories` section with lightweight match explainability.
+- **Trust-zone store foundation** — Engram can now, when `trustZonesEnabled` is enabled, persist typed quarantine, working, and trusted records with provenance metadata into a dedicated trust-zone store for later promotion and defense slices.
 - **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
@@ -189,6 +190,9 @@ Key settings:
 | `causalTrajectoryStoreDir` | `{memoryDir}/state/causal-trajectories` | Root directory for causal-trajectory records |
 | `causalTrajectoryRecallEnabled` | `false` | Inject prompt-relevant causal trajectories into recall context |
 | `actionGraphRecallEnabled` | `false` | Write action-conditioned causal-stage edges from typed trajectory records into the causal graph |
+| `trustZonesEnabled` | `false` | Enable the trust-zone memory foundation for quarantine, working, and trusted records |
+| `quarantinePromotionEnabled` | `false` | Reserve future promotion flows from quarantine into higher-trust zones |
+| `trustZoneStoreDir` | `{memoryDir}/state/trust-zones` | Root directory for trust-zone records |
 
 Full reference: [Config Reference](docs/config-reference.md)
 

package/dist/index.js

@@ -296,6 +296,9 @@ function parseConfig(raw) {
     causalTrajectoryStoreDir: typeof cfg.causalTrajectoryStoreDir === "string" && cfg.causalTrajectoryStoreDir.trim().length > 0 ? cfg.causalTrajectoryStoreDir.trim() : path.join(memoryDir, "state", "causal-trajectories"),
     causalTrajectoryRecallEnabled: cfg.causalTrajectoryRecallEnabled === true,
     actionGraphRecallEnabled: cfg.actionGraphRecallEnabled === true,
+    trustZonesEnabled: cfg.trustZonesEnabled === true,
+    quarantinePromotionEnabled: cfg.quarantinePromotionEnabled === true,
+    trustZoneStoreDir: typeof cfg.trustZoneStoreDir === "string" && cfg.trustZoneStoreDir.trim().length > 0 ? cfg.trustZoneStoreDir.trim() : path.join(memoryDir, "state", "trust-zones"),
     // Local LLM Provider (v2.1)
     localLlmEnabled: cfg.localLlmEnabled === true || cfg.localLlmEnabled === "true",
     // default: false
@@ -14213,9 +14216,9 @@ function assertSafePathSegment(value, field) {
   }
   return value;
 }
-function assertIsoRecordedAt(value) {
+function assertIsoRecordedAt(value, field = "recordedAt") {
   if (!/^\d{4}-\d{2}-\d{2}T/.test(value)) {
-    throw new Error("recordedAt must be an ISO timestamp");
+    throw new Error(`${field} must be an ISO timestamp`);
   }
   return value;
 }
@@ -23718,7 +23721,7 @@ promotionCandidates: ${res.promotionCandidateCount}`
 }
 
 // src/cli.ts
-import path53 from "path";
+import path54 from "path";
 import { access as access3, readFile as readFile37, readdir as readdir24, unlink as unlink7 } from "fs/promises";
 import { createHash as createHash10 } from "crypto";
 
@@ -24599,8 +24602,8 @@ function gatherCandidates(input, warnings) {
       const record = rec;
       const content = typeof record.content === "string" ? record.content : null;
       if (!content) continue;
-      const path55 = typeof record.path === "string" ? record.path : "";
-      if (!path55.startsWith("transcripts/") && !path55.includes("/transcripts/")) continue;
+      const path56 = typeof record.path === "string" ? record.path : "";
+      if (!path56.startsWith("transcripts/") && !path56.includes("/transcripts/")) continue;
       rows.push(...parseJsonl(content, warnings));
     }
     return rows;
@@ -26234,6 +26237,111 @@ async function runCompatChecks(options) {
   };
 }
 
+// src/trust-zones.ts
+import path53 from "path";
+import { mkdir as mkdir35, writeFile as writeFile32 } from "fs/promises";
+function validateMetadata3(raw) {
+  return validateStringRecord(raw, "metadata");
+}
+function validateZone(raw, field) {
+  const value = assertString2(raw, field);
+  if (!["quarantine", "working", "trusted"].includes(value)) {
+    throw new Error(`${field} must be one of quarantine|working|trusted`);
+  }
+  return value;
+}
+function validateKind(raw) {
+  const value = assertString2(raw, "kind");
+  if (!["memory", "artifact", "state", "trajectory", "external"].includes(value)) {
+    throw new Error("kind must be one of memory|artifact|state|trajectory|external");
+  }
+  return value;
+}
+function validateProvenance(raw) {
+  if (!isRecord2(raw)) throw new Error("provenance must be an object");
+  const sourceClass = assertString2(raw.sourceClass, "provenance.sourceClass");
+  if (!["tool_output", "web_content", "subagent_trace", "system_memory", "user_input", "manual"].includes(sourceClass)) {
+    throw new Error("provenance.sourceClass must be one of tool_output|web_content|subagent_trace|system_memory|user_input|manual");
+  }
+  return {
+    sourceClass,
+    observedAt: assertIsoRecordedAt(assertString2(raw.observedAt, "provenance.observedAt"), "provenance.observedAt"),
+    sessionKey: optionalString(raw.sessionKey),
+    sourceId: optionalString(raw.sourceId),
+    evidenceHash: optionalString(raw.evidenceHash)
+  };
+}
+function resolveTrustZoneStoreDir(memoryDir, overrideDir) {
+  if (typeof overrideDir === "string" && overrideDir.trim().length > 0) {
+    return overrideDir.trim();
+  }
+  return path53.join(memoryDir, "state", "trust-zones");
+}
+function validateTrustZoneRecord(raw) {
+  if (!isRecord2(raw)) throw new Error("trust-zone record must be an object");
+  if (raw.schemaVersion !== 1) throw new Error("schemaVersion must be 1");
+  return {
+    schemaVersion: 1,
+    recordId: assertSafePathSegment(assertString2(raw.recordId, "recordId"), "recordId"),
+    zone: validateZone(raw.zone, "zone"),
+    recordedAt: assertIsoRecordedAt(assertString2(raw.recordedAt, "recordedAt")),
+    kind: validateKind(raw.kind),
+    summary: assertString2(raw.summary, "summary"),
+    provenance: validateProvenance(raw.provenance),
+    promotedFromZone: raw.promotedFromZone === void 0 ? void 0 : validateZone(raw.promotedFromZone, "promotedFromZone"),
+    entityRefs: optionalStringArray2(raw.entityRefs, "entityRefs"),
+    tags: optionalStringArray2(raw.tags, "tags"),
+    metadata: validateMetadata3(raw.metadata)
+  };
+}
+async function readTrustZoneRecords(options) {
+  const rootDir = resolveTrustZoneStoreDir(options.memoryDir, options.trustZoneStoreDir);
+  const files = await listJsonFiles(path53.join(rootDir, "zones"));
+  const records = [];
+  const invalidRecords = [];
+  for (const filePath of files) {
+    try {
+      records.push(validateTrustZoneRecord(await readJsonFile(filePath)));
+    } catch (error) {
+      invalidRecords.push({
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return { files, records, invalidRecords };
+}
+async function getTrustZoneStoreStatus(options) {
+  const rootDir = resolveTrustZoneStoreDir(options.memoryDir, options.trustZoneStoreDir);
+  const zonesDir = path53.join(rootDir, "zones");
+  const { files, records, invalidRecords } = await readTrustZoneRecords(options);
+  records.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
+  const byZone = {};
+  const byKind = {};
+  for (const record of records) {
+    byZone[record.zone] = (byZone[record.zone] ?? 0) + 1;
+    byKind[record.kind] = (byKind[record.kind] ?? 0) + 1;
+  }
+  return {
+    enabled: options.enabled,
+    promotionEnabled: options.promotionEnabled,
+    rootDir,
+    zonesDir,
+    records: {
+      total: files.length,
+      valid: records.length,
+      invalid: invalidRecords.length,
+      byZone,
+      byKind,
+      latestRecordId: records[0]?.recordId,
+      latestRecordedAt: records[0]?.recordedAt,
+      latestZone: records[0]?.zone
+    },
+    latestRecord: records[0],
+    invalidRecords
+  };
+}
+
 // src/cli.ts
 function rankCandidateForKeep(a, b) {
   const aConfidence = typeof a.frontmatter.confidence === "number" ? a.frontmatter.confidence : 0;
@@ -26430,6 +26538,14 @@ async function runCausalTrajectoryStatusCliCommand(options) {
     enabled: options.causalTrajectoryMemoryEnabled
   });
 }
+async function runTrustZoneStatusCliCommand(options) {
+  return getTrustZoneStoreStatus({
+    memoryDir: options.memoryDir,
+    trustZoneStoreDir: options.trustZoneStoreDir,
+    enabled: options.trustZonesEnabled,
+    promotionEnabled: options.quarantinePromotionEnabled
+  });
+}
 async function runSessionCheckCliCommand(options) {
   return analyzeSessionIntegrity({ memoryDir: options.memoryDir });
 }
@@ -26657,7 +26773,7 @@ function policyVersionForValues(values, config) {
   return createHash10("sha256").update(JSON.stringify(normalized)).digest("hex").slice(0, 12);
 }
 async function readRuntimePolicySnapshot2(config, fileName) {
-  const filePath = path53.join(config.memoryDir, "state", fileName);
+  const filePath = path54.join(config.memoryDir, "state", fileName);
   const snapshot = await readRuntimePolicySnapshot(filePath, {
     maxStaleDecayThreshold: config.lifecycleArchiveDecayThreshold
   });
@@ -27241,14 +27357,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 = path53.join(orchestrator.config.memoryDir, "namespaces", ns);
+  const candidate = path54.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 = [path53.join(memoryDir, "facts"), path53.join(memoryDir, "corrections")];
+  const roots = [path54.join(memoryDir, "facts"), path54.join(memoryDir, "corrections")];
   const out = [];
   const walk = async (dir) => {
     let entries;
@@ -27259,7 +27375,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 = path53.join(dir, entryName);
+      const fullPath = path54.join(dir, entryName);
       if (entry.isDirectory()) {
         await walk(fullPath);
         continue;
@@ -27588,6 +27704,16 @@ function registerCli(api, orchestrator) {
         console.log(JSON.stringify(status, null, 2));
         console.log("OK");
       });
+      cmd.command("trust-zone-status").description("Show trust-zone store status, zoned record counts, and latest stored record").action(async () => {
+        const status = await runTrustZoneStatusCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          trustZoneStoreDir: orchestrator.config.trustZoneStoreDir,
+          trustZonesEnabled: orchestrator.config.trustZonesEnabled,
+          quarantinePromotionEnabled: orchestrator.config.quarantinePromotionEnabled
+        });
+        console.log(JSON.stringify(status, null, 2));
+        console.log("OK");
+      });
       cmd.command("conversation-index-health").description("Show conversation index backend health and index stats").action(async () => {
         const health = await runConversationIndexHealthCliCommand(orchestrator);
         console.log(JSON.stringify(health, null, 2));
@@ -28237,7 +28363,7 @@ function registerCli(api, orchestrator) {
         }
       });
       cmd.command("identity").description("Show agent identity reflections").action(async () => {
-        const workspaceDir = path53.join(process.env.HOME ?? "~", ".openclaw", "workspace");
+        const workspaceDir = path54.join(process.env.HOME ?? "~", ".openclaw", "workspace");
         const identity = await orchestrator.storage.readIdentity(workspaceDir);
         if (!identity) {
           console.log("No identity file found.");
@@ -28460,8 +28586,8 @@ function registerCli(api, orchestrator) {
         const options = args[0] ?? {};
         const threadId = options.thread;
         const top = parseInt(options.top ?? "10", 10);
-        const memoryDir = path53.join(process.env.HOME ?? "~", ".openclaw", "workspace", "memory", "local");
-        const threading = new ThreadingManager(path53.join(memoryDir, "threads"));
+        const memoryDir = path54.join(process.env.HOME ?? "~", ".openclaw", "workspace", "memory", "local");
+        const threading = new ThreadingManager(path54.join(memoryDir, "threads"));
         if (threadId) {
           const thread = await threading.loadThread(threadId);
           if (!thread) {
@@ -28937,9 +29063,9 @@ async function recordObjectiveStateSnapshotsFromAgentMessages(options) {
 }
 
 // src/index.ts
-import { readFile as readFile38, writeFile as writeFile32 } from "fs/promises";
+import { readFile as readFile38, writeFile as writeFile33 } from "fs/promises";
 import { readFileSync as readFileSync4 } from "fs";
-import path54 from "path";
+import path55 from "path";
 import os6 from "os";
 var ENGRAM_REGISTERED_GUARD = "__openclawEngramRegistered";
 var ENGRAM_HOOK_APIS = "__openclawEngramHookApis";
@@ -28947,7 +29073,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 : path54.join(homeDir, ".openclaw", "openclaw.json");
+    const configPath = explicitConfigPath && explicitConfigPath.length > 0 ? explicitConfigPath : path55.join(homeDir, ".openclaw", "openclaw.json");
     const content = readFileSync4(configPath, "utf-8");
     const config = JSON.parse(content);
     const pluginEntry = config?.plugins?.entries?.["openclaw-engram"];
@@ -29197,11 +29323,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 = path54.join(
+              const signalPath = path55.join(
                 workspaceDir,
                 `.compaction-reset-signal-${safeSessionKey}`
               );
-              await writeFile32(
+              await writeFile33(
                 signalPath,
                 JSON.stringify({
                   sessionKey,
@@ -29228,7 +29354,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 = path54.join(os6.homedir(), ".openclaw", "cron", "jobs.json");
+      const cronFilePath = path55.join(os6.homedir(), ".openclaw", "cron", "jobs.json");
       try {
         let jobsData = { version: 1, jobs: [] };
         try {
@@ -29269,7 +29395,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
           state: {}
         };
         jobsData.jobs.push(newJob);
-        await writeFile32(cronFilePath, JSON.stringify(jobsData, null, 2), "utf-8");
+        await writeFile33(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);