@joshuaswarren/openclaw-engram 9.0.46 → 9.0.47

package/README.md

@@ -46,7 +46,7 @@ AI agents forget everything between conversations. Engram fixes that.
 - **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`.
 - **Artifact recovery recall** — Engram can now, when both `creationMemoryEnabled` and `workProductRecallEnabled` are enabled, surface prompt-relevant work-product ledger entries back into recall as a dedicated `Work Products` section and inspect reuse candidates with `openclaw engram work-product-recall-search`.
 - **Commitment lifecycle foundation** — Engram can now, when `creationMemoryEnabled`, `commitmentLedgerEnabled`, and `commitmentLifecycleEnabled` are enabled, transition existing commitments to `fulfilled` / `cancelled` / `expired`, inspect overdue and stale obligations in `openclaw engram commitment-status`, and run deterministic lifecycle cleanup with `openclaw engram commitment-lifecycle-run`.
-- **Resume-bundle format foundation** — Engram can now, when `creationMemoryEnabled` and `resumeBundlesEnabled` are enabled, persist typed crash-recovery resume bundles, inspect them with `openclaw engram resume-bundle-status`, and write deterministic handoff shells through `openclaw engram resume-bundle-record`.
+- **Resume-bundle builder** — Engram can now, when `creationMemoryEnabled` and `resumeBundlesEnabled` are enabled, persist typed crash-recovery resume bundles, inspect them with `openclaw engram resume-bundle-status`, write explicit handoff shells through `openclaw engram resume-bundle-record`, and build bounded resume bundles from transcript recovery, recent objective-state snapshots, work products, and open commitments through `openclaw engram resume-bundle-build`.
 - **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
@@ -229,7 +229,7 @@ Key settings:
 | `commitmentLifecycleEnabled` | `false` | Enable commitment lifecycle transitions, stale tracking, and resolved-entry cleanup for the commitment ledger |
 | `commitmentStaleDays` | `14` | Days before an open commitment without a due date is considered stale in lifecycle status |
 | `commitmentLedgerDir` | `{memoryDir}/state/commitment-ledger` | Root directory for typed commitment ledger entries |
-| `resumeBundlesEnabled` | `false` | Enable typed resume-bundle storage plus the operator-facing `resume-bundle-status` and `resume-bundle-record` commands |
+| `resumeBundlesEnabled` | `false` | Enable typed resume-bundle storage plus the operator-facing `resume-bundle-status`, `resume-bundle-record`, and `resume-bundle-build` commands |
 | `resumeBundleDir` | `{memoryDir}/state/resume-bundles` | Root directory for typed resume bundles |
 | `workProductRecallEnabled` | `false` | Inject prompt-relevant work-product ledger entries into recall and expose `openclaw engram work-product-recall-search` |
 | `workProductLedgerDir` | `{memoryDir}/state/work-product-ledger` | Root directory for typed work-product ledger entries |

package/dist/index.js

@@ -27828,6 +27828,7 @@ async function runCompatChecks(options) {
 // src/resume-bundles.ts
 import path59 from "path";
 import { mkdir as mkdir40, writeFile as writeFile37 } from "fs/promises";
+var DEFAULT_RESUME_BUNDLE_REF_LIMIT = 5;
 function resolveResumeBundleDir(memoryDir, overrideDir) {
   if (typeof overrideDir === "string" && overrideDir.trim().length > 0) {
     return overrideDir.trim();
@@ -27862,6 +27863,128 @@ function validateResumeBundle(raw) {
     metadata: validateStringRecord(raw.metadata, "metadata")
   };
 }
+async function readValidatedItems(options) {
+  const files = await listJsonFiles(options.rootDir);
+  const items = [];
+  for (const filePath of files) {
+    try {
+      items.push(options.validate(await readJsonFile(filePath)));
+    } catch {
+    }
+  }
+  return items;
+}
+async function readObjectiveStateSnapshotsForSession(options) {
+  const rootDir = resolveObjectiveStateStoreDir(options.memoryDir, options.objectiveStateStoreDir);
+  const items = await readValidatedItems({
+    rootDir: path59.join(rootDir, "snapshots"),
+    validate: validateObjectiveStateSnapshot
+  });
+  return items.filter((item) => item.sessionKey === options.sessionKey).sort((left, right) => right.recordedAt.localeCompare(left.recordedAt)).slice(0, options.maxResults ?? DEFAULT_RESUME_BUNDLE_REF_LIMIT);
+}
+async function readWorkProductEntriesForSession(options) {
+  const rootDir = resolveWorkProductLedgerDir(options.memoryDir, options.workProductLedgerDir);
+  const items = await readValidatedItems({
+    rootDir: path59.join(rootDir, "entries"),
+    validate: validateWorkProductLedgerEntry
+  });
+  return items.filter((item) => item.sessionKey === options.sessionKey).sort((left, right) => right.recordedAt.localeCompare(left.recordedAt)).slice(0, options.maxResults ?? DEFAULT_RESUME_BUNDLE_REF_LIMIT);
+}
+async function readCommitmentEntriesForSession(options) {
+  const rootDir = resolveCommitmentLedgerDir(options.memoryDir, options.commitmentLedgerDir);
+  const items = await readValidatedItems({
+    rootDir: path59.join(rootDir, "entries"),
+    validate: validateCommitmentLedgerEntry
+  });
+  return items.filter((item) => item.sessionKey === options.sessionKey).filter((item) => options.state ? item.state === options.state : true).sort((left, right) => right.recordedAt.localeCompare(left.recordedAt)).slice(0, options.maxResults ?? DEFAULT_RESUME_BUNDLE_REF_LIMIT);
+}
+function buildRecoveryFact(recoverySummary) {
+  return recoverySummary.healthy ? `Transcript recovery healthy with ${recoverySummary.issueCount} issue(s), ${recoverySummary.incompleteTurns} incomplete turn(s), and ${recoverySummary.brokenChains} broken chain(s).` : `Transcript recovery flagged ${recoverySummary.issueCount} issue(s), ${recoverySummary.incompleteTurns} incomplete turn(s), and ${recoverySummary.brokenChains} broken chain(s); checkpoint healthy: ${recoverySummary.checkpointHealthy ? "yes" : "no"}.`;
+}
+function buildBundleSummary(options) {
+  const parts = [
+    `${options.openCommitmentCount} open commitment(s)`,
+    `${options.workProductCount} recent work product(s)`,
+    `${options.objectiveSnapshotCount} recent objective-state snapshot(s)`
+  ];
+  if (options.recoveryHealthy === false) {
+    parts.push("transcript recovery issues remain");
+  }
+  return `Resume ${options.sessionKey}: ${parts.join(", ")}.`;
+}
+async function buildResumeBundleFromState(options) {
+  const recordedAt = assertIsoRecordedAt(options.recordedAt, "recordedAt");
+  const maxRefsPerStore = Math.max(1, Math.floor(options.maxRefsPerStore ?? DEFAULT_RESUME_BUNDLE_REF_LIMIT));
+  const objectiveSnapshots = options.objectiveStateMemoryEnabled ? await readObjectiveStateSnapshotsForSession({
+    memoryDir: options.memoryDir,
+    objectiveStateStoreDir: options.objectiveStateStoreDir,
+    sessionKey: options.sessionKey,
+    maxResults: maxRefsPerStore
+  }) : [];
+  const workProducts = options.creationMemoryEnabled ? await readWorkProductEntriesForSession({
+    memoryDir: options.memoryDir,
+    workProductLedgerDir: options.workProductLedgerDir,
+    sessionKey: options.sessionKey,
+    maxResults: maxRefsPerStore
+  }) : [];
+  const commitments = options.creationMemoryEnabled && options.commitmentLedgerEnabled ? await readCommitmentEntriesForSession({
+    memoryDir: options.memoryDir,
+    commitmentLedgerDir: options.commitmentLedgerDir,
+    sessionKey: options.sessionKey,
+    maxResults: maxRefsPerStore,
+    state: "open"
+  }) : [];
+  const openCommitments = commitments;
+  const recordedAtMs = Date.parse(recordedAt);
+  const overdueCommitments = openCommitments.filter((entry) => {
+    if (!entry.dueAt) return false;
+    const dueAtMs = Date.parse(entry.dueAt);
+    return Number.isFinite(dueAtMs) && dueAtMs < recordedAtMs;
+  });
+  let recoverySummary;
+  if (options.transcriptEnabled) {
+    const transcript = new TranscriptManager(parseConfig({
+      memoryDir: options.memoryDir,
+      transcriptEnabled: true
+    }));
+    await transcript.initialize();
+    recoverySummary = await transcript.getRecoverySummary(options.sessionKey);
+  }
+  const keyFacts = [
+    recoverySummary ? buildRecoveryFact(recoverySummary) : void 0,
+    workProducts[0]?.summary,
+    objectiveSnapshots[0]?.summary
+  ].filter((value) => typeof value === "string" && value.length > 0);
+  const nextActions = openCommitments.map((entry) => entry.summary).filter((summary, index, values) => values.indexOf(summary) === index).slice(0, maxRefsPerStore);
+  const riskFlags = [
+    recoverySummary && !recoverySummary.healthy ? buildRecoveryFact(recoverySummary) : void 0,
+    ...objectiveSnapshots.filter((snapshot) => snapshot.outcome === "failure" || snapshot.outcome === "partial").map((snapshot) => snapshot.summary),
+    ...overdueCommitments.map((entry) => `Overdue commitment: ${entry.summary}`)
+  ].filter(
+    (value, index, values) => typeof value === "string" && value.length > 0 && values.indexOf(value) === index
+  );
+  return validateResumeBundle({
+    schemaVersion: 1,
+    bundleId: options.bundleId,
+    recordedAt,
+    sessionKey: options.sessionKey,
+    source: options.source ?? "system",
+    scope: options.scope,
+    summary: buildBundleSummary({
+      sessionKey: options.sessionKey,
+      openCommitmentCount: openCommitments.length,
+      workProductCount: workProducts.length,
+      objectiveSnapshotCount: objectiveSnapshots.length,
+      recoveryHealthy: recoverySummary?.healthy
+    }),
+    objectiveStateSnapshotRefs: objectiveSnapshots.map((snapshot) => snapshot.snapshotId),
+    workProductEntryRefs: workProducts.map((entry) => entry.entryId),
+    commitmentEntryRefs: openCommitments.map((entry) => entry.entryId),
+    keyFacts: keyFacts.length > 0 ? keyFacts : void 0,
+    nextActions: nextActions.length > 0 ? nextActions : void 0,
+    riskFlags: riskFlags.length > 0 ? riskFlags : void 0
+  });
+}
 async function recordResumeBundle(options) {
   const rootDir = resolveResumeBundleDir(options.memoryDir, options.resumeBundleDir);
   const validated = validateResumeBundle(options.bundle);
@@ -28354,6 +28477,31 @@ async function runResumeBundleRecordCliCommand(options) {
     bundle: options.bundle
   });
 }
+async function runResumeBundleBuildCliCommand(options) {
+  if (!options.creationMemoryEnabled || !options.resumeBundlesEnabled) {
+    return null;
+  }
+  const bundle = await buildResumeBundleFromState({
+    memoryDir: options.memoryDir,
+    sessionKey: options.sessionKey,
+    bundleId: options.bundleId,
+    recordedAt: options.recordedAt,
+    scope: options.scope,
+    transcriptEnabled: options.transcriptEnabled,
+    objectiveStateMemoryEnabled: options.objectiveStateMemoryEnabled,
+    objectiveStateStoreDir: options.objectiveStateStoreDir,
+    creationMemoryEnabled: options.creationMemoryEnabled,
+    workProductLedgerDir: options.workProductLedgerDir,
+    commitmentLedgerEnabled: options.commitmentLedgerEnabled,
+    commitmentLedgerDir: options.commitmentLedgerDir
+  });
+  const filePath = await recordResumeBundle({
+    memoryDir: options.memoryDir,
+    resumeBundleDir: options.resumeBundleDir,
+    bundle
+  });
+  return { bundle, filePath };
+}
 async function runCommitmentStatusCliCommand(options) {
   return getCommitmentLedgerStatus({
     memoryDir: options.memoryDir,
@@ -29669,6 +29817,31 @@ function registerCli(api, orchestrator) {
         console.log(JSON.stringify({ wrote: filePath !== null, filePath }, null, 2));
         console.log("OK");
       });
+      cmd.command("resume-bundle-build").description("Build and persist a resume bundle from transcript recovery, objective state, work products, and open commitments").requiredOption("--bundle-id <bundleId>", "Resume bundle id").requiredOption("--recorded-at <recordedAt>", "ISO timestamp for the bundle").requiredOption("--session-key <sessionKey>", "Session key that owns the bundle").requiredOption("--scope <scope>", "Primary scope or recovery domain for the bundle").action(async (...args) => {
+        const options = args[0] ?? {};
+        const built = await runResumeBundleBuildCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          resumeBundleDir: orchestrator.config.resumeBundleDir,
+          objectiveStateStoreDir: orchestrator.config.objectiveStateStoreDir,
+          workProductLedgerDir: orchestrator.config.workProductLedgerDir,
+          commitmentLedgerDir: orchestrator.config.commitmentLedgerDir,
+          creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+          resumeBundlesEnabled: orchestrator.config.resumeBundlesEnabled,
+          transcriptEnabled: orchestrator.config.transcriptEnabled,
+          objectiveStateMemoryEnabled: orchestrator.config.objectiveStateMemoryEnabled,
+          commitmentLedgerEnabled: orchestrator.config.commitmentLedgerEnabled,
+          bundleId: String(options.bundleId ?? ""),
+          recordedAt: String(options.recordedAt ?? ""),
+          sessionKey: String(options.sessionKey ?? ""),
+          scope: String(options.scope ?? "")
+        });
+        console.log(JSON.stringify({
+          wrote: built !== null,
+          filePath: built?.filePath ?? null,
+          bundle: built?.bundle ?? null
+        }, null, 2));
+        console.log("OK");
+      });
       cmd.command("commitment-status").description("Show commitment ledger status, entry counts, and the latest recorded commitment").action(async () => {
         const status = await runCommitmentStatusCliCommand({
           memoryDir: orchestrator.config.memoryDir,