@joshuaswarren/openclaw-engram 9.0.41 → 9.0.42

package/README.md

@@ -43,6 +43,7 @@ AI agents forget everything between conversations. Engram fixes that.
 - **Verified episodic recall** — Engram can now, when `verifiedRecallEnabled` is enabled, inject a dedicated `Verified Episodes` recall section that reuses memory boxes but only surfaces boxes whose cited source memories still verify as non-archived episodes.
 - **Semantic rule promotion** — Engram can now, when `semanticRulePromotionEnabled` is enabled, promote explicit `IF ... THEN ...` rules from verified episodic memories into durable `rule` memories with lineage, source-memory provenance, duplicate suppression, and the operator-facing `openclaw engram semantic-rule-promote` CLI.
 - **Verified rule recall** — Engram can now, when `semanticRuleVerificationEnabled` is enabled, inject a dedicated `Verified Rules` recall section that re-checks promoted rule memories against their cited source episodes at recall time and downgrades stale provenance before the rule can surface.
+- **Creation-memory ledger** — Engram can now, when `creationMemoryEnabled` is enabled, persist a typed work-product ledger for explicit outputs agents create or update, inspect it with `openclaw engram work-product-status`, and write deterministic entries through `openclaw engram work-product-record`.
 - **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
@@ -172,6 +173,8 @@ openclaw engram trust-zone-status           # Trust-zone record counts and lates
 openclaw engram trust-zone-promote          # Dry-run or apply a trust-zone promotion with provenance/corroboration enforcement
 openclaw engram harmonic-search <query>     # Preview blended harmonic retrieval matches
 openclaw engram verified-recall-search <query> # Preview verified episodic recall matches
+openclaw engram work-product-status         # Work-product ledger counts and latest recorded output
+openclaw engram work-product-record         # Record a typed work-product ledger entry
 openclaw engram conversation-index-health    # Conversation index status
 openclaw engram graph-health                 # Entity graph status
 openclaw engram tier-status                  # Hot/cold tier metrics
@@ -213,6 +216,8 @@ Key settings:
 | `verifiedRecallEnabled` | `false` | Inject prompt-relevant memory boxes only when their cited source memories verify as non-archived episodes |
 | `semanticRulePromotionEnabled` | `false` | Enable deterministic promotion of explicit `IF ... THEN ...` rules from verified episodic memories via `openclaw engram semantic-rule-promote` |
 | `semanticRuleVerificationEnabled` | `false` | Verify promoted semantic rules against their cited source episodes at recall time and inject a dedicated `Verified Rules` section via `openclaw engram semantic-rule-verify` |
+| `creationMemoryEnabled` | `false` | Enable the creation-memory foundation, including the work-product ledger and operator-facing write/status commands |
+| `workProductLedgerDir` | `{memoryDir}/state/work-product-ledger` | Root directory for typed work-product ledger entries |
 
 Full reference: [Config Reference](docs/config-reference.md)
 

package/dist/index.js

@@ -307,6 +307,8 @@ function parseConfig(raw) {
     verifiedRecallEnabled: cfg.verifiedRecallEnabled === true,
     semanticRulePromotionEnabled: cfg.semanticRulePromotionEnabled === true,
     semanticRuleVerificationEnabled: cfg.semanticRuleVerificationEnabled === true,
+    creationMemoryEnabled: cfg.creationMemoryEnabled === true,
+    workProductLedgerDir: typeof cfg.workProductLedgerDir === "string" && cfg.workProductLedgerDir.trim().length > 0 ? cfg.workProductLedgerDir.trim() : path.join(memoryDir, "state", "work-product-ledger"),
     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",
@@ -24878,7 +24880,7 @@ promotionCandidates: ${res.promotionCandidateCount}`
 }
 
 // src/cli.ts
-import path57 from "path";
+import path58 from "path";
 import { access as access3, readFile as readFile37, readdir as readdir24, unlink as unlink7 } from "fs/promises";
 import { createHash as createHash10 } from "crypto";
 
@@ -25759,8 +25761,8 @@ function gatherCandidates(input, warnings) {
       const record = rec;
       const content = typeof record.content === "string" ? record.content : null;
       if (!content) continue;
-      const path59 = typeof record.path === "string" ? record.path : "";
-      if (!path59.startsWith("transcripts/") && !path59.includes("/transcripts/")) continue;
+      const path60 = typeof record.path === "string" ? record.path : "";
+      if (!path60.startsWith("transcripts/") && !path60.includes("/transcripts/")) continue;
       rows.push(...parseJsonl(content, warnings));
     }
     return rows;
@@ -27394,6 +27396,104 @@ async function runCompatChecks(options) {
   };
 }
 
+// src/work-product-ledger.ts
+import path57 from "path";
+import { mkdir as mkdir38, writeFile as writeFile35 } from "fs/promises";
+function resolveWorkProductLedgerDir(memoryDir, overrideDir) {
+  if (typeof overrideDir === "string" && overrideDir.trim().length > 0) {
+    return overrideDir.trim();
+  }
+  return path57.join(memoryDir, "state", "work-product-ledger");
+}
+function validateWorkProductLedgerEntry(raw) {
+  if (!isRecord2(raw)) throw new Error("work-product ledger entry must be an object");
+  if (raw.schemaVersion !== 1) throw new Error("schemaVersion must be 1");
+  const source = assertString2(raw.source, "source");
+  if (!["tool_result", "cli", "system", "manual"].includes(source)) {
+    throw new Error("source must be one of tool_result|cli|system|manual");
+  }
+  const kind = assertString2(raw.kind, "kind");
+  if (!["artifact", "file", "record", "report", "workspace"].includes(kind)) {
+    throw new Error("kind must be one of artifact|file|record|report|workspace");
+  }
+  const action = assertString2(raw.action, "action");
+  if (!["created", "updated", "deleted", "referenced", "published"].includes(action)) {
+    throw new Error("action must be one of created|updated|deleted|referenced|published");
+  }
+  return {
+    schemaVersion: 1,
+    entryId: assertSafePathSegment(assertString2(raw.entryId, "entryId"), "entryId"),
+    recordedAt: assertIsoRecordedAt(assertString2(raw.recordedAt, "recordedAt")),
+    sessionKey: assertString2(raw.sessionKey, "sessionKey"),
+    source,
+    kind,
+    action,
+    scope: assertString2(raw.scope, "scope"),
+    summary: assertString2(raw.summary, "summary"),
+    artifactPath: optionalString(raw.artifactPath),
+    objectiveStateSnapshotRefs: optionalStringArray2(raw.objectiveStateSnapshotRefs, "objectiveStateSnapshotRefs"),
+    entityRefs: optionalStringArray2(raw.entityRefs, "entityRefs"),
+    tags: optionalStringArray2(raw.tags, "tags"),
+    metadata: validateStringRecord(raw.metadata, "metadata")
+  };
+}
+async function recordWorkProductLedgerEntry(options) {
+  const rootDir = resolveWorkProductLedgerDir(options.memoryDir, options.workProductLedgerDir);
+  const validated = validateWorkProductLedgerEntry(options.entry);
+  const day = recordStoreDay(validated.recordedAt);
+  const entriesDir = path57.join(rootDir, "entries", day);
+  const filePath = path57.join(entriesDir, `${validated.entryId}.json`);
+  await mkdir38(entriesDir, { recursive: true });
+  await writeFile35(filePath, JSON.stringify(validated, null, 2), "utf8");
+  return filePath;
+}
+async function readWorkProductLedgerEntries(options) {
+  const rootDir = resolveWorkProductLedgerDir(options.memoryDir, options.workProductLedgerDir);
+  const files = await listJsonFiles(path57.join(rootDir, "entries"));
+  const entries = [];
+  const invalidEntries = [];
+  for (const filePath of files) {
+    try {
+      entries.push(validateWorkProductLedgerEntry(await readJsonFile(filePath)));
+    } catch (error) {
+      invalidEntries.push({
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return { files, entries, invalidEntries };
+}
+async function getWorkProductLedgerStatus(options) {
+  const rootDir = resolveWorkProductLedgerDir(options.memoryDir, options.workProductLedgerDir);
+  const entriesDir = path57.join(rootDir, "entries");
+  const { files, entries, invalidEntries } = await readWorkProductLedgerEntries(options);
+  entries.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
+  const byKind = {};
+  const byAction = {};
+  for (const entry of entries) {
+    byKind[entry.kind] = (byKind[entry.kind] ?? 0) + 1;
+    byAction[entry.action] = (byAction[entry.action] ?? 0) + 1;
+  }
+  return {
+    enabled: options.enabled,
+    rootDir,
+    entriesDir,
+    entries: {
+      total: files.length,
+      valid: entries.length,
+      invalid: invalidEntries.length,
+      byKind,
+      byAction,
+      latestEntryId: entries[0]?.entryId,
+      latestRecordedAt: entries[0]?.recordedAt,
+      latestSessionKey: entries[0]?.sessionKey
+    },
+    latestEntry: entries[0],
+    invalidEntries
+  };
+}
+
 // src/semantic-rule-promotion.ts
 function normalizeRuleWhitespace(value) {
   return value.replace(/\s+/g, " ").trim();
@@ -27775,6 +27875,21 @@ async function runSemanticRuleVerifyCliCommand(options) {
     maxResults: Math.max(1, Math.floor(options.maxResults ?? 3))
   });
 }
+async function runWorkProductStatusCliCommand(options) {
+  return getWorkProductLedgerStatus({
+    memoryDir: options.memoryDir,
+    workProductLedgerDir: options.workProductLedgerDir,
+    enabled: options.creationMemoryEnabled
+  });
+}
+async function runWorkProductRecordCliCommand(options) {
+  if (!options.creationMemoryEnabled) return null;
+  return recordWorkProductLedgerEntry({
+    memoryDir: options.memoryDir,
+    workProductLedgerDir: options.workProductLedgerDir,
+    entry: options.entry
+  });
+}
 async function runTrustZonePromoteCliCommand(options) {
   const result = await promoteTrustZoneRecord({
     memoryDir: options.memoryDir,
@@ -28021,7 +28136,7 @@ function policyVersionForValues(values, config) {
   return createHash10("sha256").update(JSON.stringify(normalized)).digest("hex").slice(0, 12);
 }
 async function readRuntimePolicySnapshot2(config, fileName) {
-  const filePath = path57.join(config.memoryDir, "state", fileName);
+  const filePath = path58.join(config.memoryDir, "state", fileName);
   const snapshot = await readRuntimePolicySnapshot(filePath, {
     maxStaleDecayThreshold: config.lifecycleArchiveDecayThreshold
   });
@@ -28605,14 +28720,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 = path57.join(orchestrator.config.memoryDir, "namespaces", ns);
+  const candidate = path58.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 = [path57.join(memoryDir, "facts"), path57.join(memoryDir, "corrections")];
+  const roots = [path58.join(memoryDir, "facts"), path58.join(memoryDir, "corrections")];
   const out = [];
   const walk = async (dir) => {
     let entries;
@@ -28623,7 +28738,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 = path57.join(dir, entryName);
+      const fullPath = path58.join(dir, entryName);
       if (entry.isDirectory()) {
         await walk(fullPath);
         continue;
@@ -29002,6 +29117,46 @@ function registerCli(api, orchestrator) {
         console.log(JSON.stringify(results, null, 2));
         console.log("OK");
       });
+      cmd.command("work-product-status").description("Show work-product ledger status, entry counts, and the latest recorded work product").action(async () => {
+        const status = await runWorkProductStatusCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          workProductLedgerDir: orchestrator.config.workProductLedgerDir,
+          creationMemoryEnabled: orchestrator.config.creationMemoryEnabled
+        });
+        console.log(JSON.stringify(status, null, 2));
+        console.log("OK");
+      });
+      cmd.command("work-product-record").description("Record a work-product ledger entry when creation-memory is enabled").requiredOption("--entry-id <entryId>", "Ledger entry id").requiredOption("--recorded-at <recordedAt>", "ISO timestamp for the entry").requiredOption("--session-key <sessionKey>", "Session key that created the work product").requiredOption("--source <source>", "Entry source (tool_result|cli|system|manual)").requiredOption("--kind <kind>", "Entry kind (artifact|file|record|report|workspace)").requiredOption(
+        "--entry-action <entryAction>",
+        "Entry action (created|updated|deleted|referenced|published)"
+      ).requiredOption("--scope <scope>", "Primary scope or identifier for the created work product").requiredOption("--summary <summary>", "Human-readable summary of the work product").option("--artifact-path <artifactPath>", "Optional path to the created artifact").option("--tag <tag...>", "Tags to attach to the work-product entry").option("--entity-ref <entityRef...>", "Entity refs to attach to the work-product entry").option(
+        "--objective-state-snapshot-ref <objectiveStateSnapshotRef...>",
+        "Objective-state snapshot refs to link to this work product"
+      ).action(async (...args) => {
+        const options = args[0] ?? {};
+        const filePath = await runWorkProductRecordCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          workProductLedgerDir: orchestrator.config.workProductLedgerDir,
+          creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+          entry: {
+            schemaVersion: 1,
+            entryId: String(options.entryId ?? ""),
+            recordedAt: String(options.recordedAt ?? ""),
+            sessionKey: String(options.sessionKey ?? ""),
+            source: String(options.source ?? ""),
+            kind: String(options.kind ?? ""),
+            action: String(options.entryAction ?? ""),
+            scope: String(options.scope ?? ""),
+            summary: String(options.summary ?? ""),
+            artifactPath: typeof options.artifactPath === "string" ? options.artifactPath : void 0,
+            tags: Array.isArray(options.tag) ? options.tag.map(String) : void 0,
+            entityRefs: Array.isArray(options.entityRef) ? options.entityRef.map(String) : void 0,
+            objectiveStateSnapshotRefs: Array.isArray(options.objectiveStateSnapshotRef) ? options.objectiveStateSnapshotRef.map(String) : void 0
+          }
+        });
+        console.log(JSON.stringify({ wrote: filePath !== null, filePath }, 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({
@@ -29707,7 +29862,7 @@ function registerCli(api, orchestrator) {
         }
       });
       cmd.command("identity").description("Show agent identity reflections").action(async () => {
-        const workspaceDir = path57.join(process.env.HOME ?? "~", ".openclaw", "workspace");
+        const workspaceDir = path58.join(process.env.HOME ?? "~", ".openclaw", "workspace");
         const identity = await orchestrator.storage.readIdentity(workspaceDir);
         if (!identity) {
           console.log("No identity file found.");
@@ -29930,8 +30085,8 @@ function registerCli(api, orchestrator) {
         const options = args[0] ?? {};
         const threadId = options.thread;
         const top = parseInt(options.top ?? "10", 10);
-        const memoryDir = path57.join(process.env.HOME ?? "~", ".openclaw", "workspace", "memory", "local");
-        const threading = new ThreadingManager(path57.join(memoryDir, "threads"));
+        const memoryDir = path58.join(process.env.HOME ?? "~", ".openclaw", "workspace", "memory", "local");
+        const threading = new ThreadingManager(path58.join(memoryDir, "threads"));
         if (threadId) {
           const thread = await threading.loadThread(threadId);
           if (!thread) {
@@ -30407,9 +30562,9 @@ async function recordObjectiveStateSnapshotsFromAgentMessages(options) {
 }
 
 // src/index.ts
-import { readFile as readFile38, writeFile as writeFile35 } from "fs/promises";
+import { readFile as readFile38, writeFile as writeFile36 } from "fs/promises";
 import { readFileSync as readFileSync4 } from "fs";
-import path58 from "path";
+import path59 from "path";
 import os6 from "os";
 var ENGRAM_REGISTERED_GUARD = "__openclawEngramRegistered";
 var ENGRAM_HOOK_APIS = "__openclawEngramHookApis";
@@ -30417,7 +30572,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 : path58.join(homeDir, ".openclaw", "openclaw.json");
+    const configPath = explicitConfigPath && explicitConfigPath.length > 0 ? explicitConfigPath : path59.join(homeDir, ".openclaw", "openclaw.json");
     const content = readFileSync4(configPath, "utf-8");
     const config = JSON.parse(content);
     const pluginEntry = config?.plugins?.entries?.["openclaw-engram"];
@@ -30667,11 +30822,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 = path58.join(
+              const signalPath = path59.join(
                 workspaceDir,
                 `.compaction-reset-signal-${safeSessionKey}`
               );
-              await writeFile35(
+              await writeFile36(
                 signalPath,
                 JSON.stringify({
                   sessionKey,
@@ -30698,7 +30853,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 = path58.join(os6.homedir(), ".openclaw", "cron", "jobs.json");
+      const cronFilePath = path59.join(os6.homedir(), ".openclaw", "cron", "jobs.json");
       try {
         let jobsData = { version: 1, jobs: [] };
         try {
@@ -30739,7 +30894,7 @@ Use this context naturally when relevant. Never quote or expose this memory cont
           state: {}
         };
         jobsData.jobs.push(newJob);
-        await writeFile35(cronFilePath, JSON.stringify(jobsData, null, 2), "utf-8");
+        await writeFile36(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);