openclaw-memory-atmem 2.2.6 → 2.3.2

package/README.md

@@ -5,7 +5,7 @@ This npm package is the host bridge for AtMem. It is not a standalone memory eng
 Use the Python-owned installer:
 
 ```bash
-python -m pip install --upgrade atmem==2.2.6
+python -m pip install --upgrade atmem==2.3.2
 atmem openclaw install
 ```
 
@@ -22,7 +22,7 @@ Existing AtMem 2.1 users run `atmem openclaw upgrade` after upgrading the Python
 package. This preserves the current memory mode and migration, verifies the new
 bridge with a self-test flight, and rolls back the bridge on failure.
 
-Bridge `2.2.6` includes exact task-context delivery, the shared
+Bridge `2.3.2` includes durable execution-event spooling in addition to exact task-context delivery and the shared
 calibrated retrieval decision, and delegated context correlation. When the host
 supplies `taskId` in hook context, the bridge requests only that governed task,
 checks its byte digest, contributes it separately from recalled memory, and
@@ -32,7 +32,11 @@ bridge does not claim it can block OpenClaw execution.
 
 In shadow mode the bridge observes native-memory changes without injecting AtMem context. In active mode it exposes compatible memory search/get tools, model-semantic capture, bounded recall and native-path protection. `atmem control restore` restores the saved OpenClaw configuration and native memory.
 
-The bridge also supplies Agent Black Box hooks. It records model/tool lifecycle digests and bounded metadata—not raw prompts, responses, parameters or results—so `atmem blackbox verify RUN_ID` can check timeline integrity and observed tool-hook closure. See the [Agent Black Box guide](../../docs/agent-blackbox.md) for the exact boundary.
+The bridge also supplies Agent Black Box hooks. With default full capture it sends
+exact host-observed prompts, model boundaries, tool arguments/results and supported
+multimodal parts into AtMem's encrypted evidence vault, alongside digest-bound
+lifecycle metadata. Metadata-only and recorder-off modes remain explicit operator
+choices. See the [Agent Black Box guide](../../docs/agent-blackbox.md) for the exact boundary.
 
 See the repository [OpenClaw setup](../../docs/openclaw-setup.md) and [control-plane guarantees](../../docs/control-plane.md).
 
@@ -54,3 +58,12 @@ actual terminal host tool-event results supply fallback observations when typed
 completion hooks are absent. Only matched requests close, with content-free
 bounded caching and duplicate suppression. Fully observed
 terminal tool errors close evidence as `completed_with_tool_errors`, not success.
+
+Local development follow-up: automatic recall now requires calibrated direct
+query support by default (`recall.requireDirectSupport: true`). Persona is an
+explicit opt-in (`persona.enabled: true`); setup defaults it off to avoid adding
+unrelated personal facts to every request. When enabled, persona records are
+excluded from recall so each appears once. Existing explicit persona settings
+are respected; set `persona.enabled: false` to adopt selective recall. Explicit
+memory search remains available. The legacy rank-only mode is available with
+`recall.requireDirectSupport: false`; it can admit weak matches.

package/dist/index.js

@@ -20,10 +20,12 @@
 import os from "node:os";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
-import { createReadStream } from "node:fs";
 import { lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 import { ToolObservations, observationContext } from "./src/tool-observations.js";
+import { progressCardComparison } from "./src/tool-result-comparison.js";
+import { toolErrorReason } from "./src/tool-errors.js";
+import { ExecutionSpool } from "./src/execution-spool.js";
 import { delegatedIdentity, isolatedCliProcess } from "./src/delegated-identity.js";
 import { AtmemClient } from "./src/rpc-client.js";
 import { runSetup } from "./src/setup.js";
@@ -45,7 +47,10 @@ const PROMPT_CACHE_TTL_MS = 10 * 60 * 1000;
 const MAX_PENDING_PROMPTS = 256;
 function parseConfig(raw) {
     const cfg = (raw ?? {});
-    const dbPath = expandHome(String(cfg.dbPath ?? "~/.atmem/memories.db"));
+    const selectedHome = process.env.ATMEM_HOME
+        ? expandHome(process.env.ATMEM_HOME)
+        : path.join(os.homedir(), ".atmem");
+    const dbPath = expandHome(String(cfg.dbPath ?? path.join(selectedHome, "memory", "memories.db")));
     const subject = String(cfg.subject ?? "default");
     const stringMap = (value) => value && typeof value === "object" && !Array.isArray(value)
         ? Object.fromEntries(Object.entries(value)
@@ -62,8 +67,8 @@ function parseConfig(raw) {
         ].filter(Boolean))];
     const controlPlane = {
         enabled: cfg.controlPlane?.enabled === true,
-        statePath: expandHome(String(cfg.controlPlane?.statePath ?? "~/.atmem/control-plane.json")),
-        blackboxEnabled: cfg.controlPlane?.enabled === true || cfg.controlPlane?.blackboxEnabled === true,
+        statePath: expandHome(String(cfg.controlPlane?.statePath ?? path.join(selectedHome, "config", "control-plane.json"))),
+        blackboxEnabled: Boolean(cfg.controlPlane) && cfg.controlPlane?.blackboxEnabled !== false,
     };
     const delegatedContext = {
         userId: String(cfg.delegatedContext?.userId ?? "").trim(),
@@ -97,10 +102,11 @@ function parseConfig(raw) {
             maxRecords: Number(cfg.recall?.maxRecords ?? 3),
             maxChars: Number(cfg.recall?.maxChars ?? 1200),
             minScore: Number(cfg.recall?.minScore ?? 0.3),
+            requireDirectSupport: cfg.recall?.requireDirectSupport !== false,
             timeoutMs: Number(cfg.recall?.timeoutMs ?? 4000),
         },
         persona: {
-            enabled: cfg.persona?.enabled !== false,
+            enabled: cfg.persona?.enabled === true,
             maxChars: Number(cfg.persona?.maxChars ?? 600),
             ttlSeconds: Number(cfg.persona?.ttlSeconds ?? 300),
         },
@@ -226,7 +232,7 @@ async function writeAttachmentBinding(root, key, items) {
     const payload = {
         format: "atmem-openclaw-attachment-binding-v1",
         keySha256: createHash("sha256").update(key).digest("hex"),
-        items,
+        items: items.map(({ dataBase64: _discarded, ...item }) => item),
         updatedAt: Date.now(),
     };
     await writeFile(temporary, JSON.stringify(payload), { encoding: "utf8", mode: 0o600 });
@@ -256,17 +262,57 @@ async function readAttachmentBinding(root, key) {
 }
 function modalityFromMime(mimeType) {
     const mime = mimeType.toLowerCase();
-    if (mime.startsWith("image/"))
+    if (mime === "image" || mime.startsWith("image/"))
         return "image";
-    if (mime.startsWith("audio/"))
+    if (mime === "audio" || mime.startsWith("audio/"))
         return "audio";
-    if (mime.startsWith("video/"))
+    if (mime === "video" || mime.startsWith("video/"))
         return "video";
-    if (mime === "application/pdf" || mime.startsWith("text/") || mime.includes("document")) {
+    if (mime === "document" || mime === "application/pdf" || mime.startsWith("text/") || mime.includes("document")) {
         return "document";
     }
     return null;
 }
+function inlineMediaParts(value) {
+    const parts = [];
+    const seen = new Set();
+    const visit = (item) => {
+        if (typeof item === "string") {
+            const match = /^data:([^;,]+);base64,([A-Za-z0-9+/]+={0,2})$/.exec(item);
+            if (!match)
+                return;
+            const mimeType = match[1].toLowerCase();
+            const modality = modalityFromMime(mimeType);
+            if (!modality)
+                return;
+            const bytes = Buffer.from(match[2], "base64");
+            if (bytes.length > 100 * 1024 * 1024 || bytes.toString("base64") !== match[2])
+                return;
+            const digest = createHash("sha256").update(bytes).digest("hex");
+            if (seen.has(digest))
+                return;
+            seen.add(digest);
+            parts.push({
+                type: modality,
+                mime_type: mimeType,
+                data_base64: match[2],
+                representation: "model_input",
+            });
+            return;
+        }
+        if (Array.isArray(item)) {
+            for (const child of item)
+                visit(child);
+            return;
+        }
+        if (item && typeof item === "object") {
+            for (const child of Object.values(item))
+                visit(child);
+        }
+    };
+    visit(value);
+    return parts;
+}
 function withinPath(candidate, root) {
     return candidate === root || candidate.startsWith(root + path.sep);
 }
@@ -279,12 +325,12 @@ async function hashInboundAttachment(filePath, mimeType) {
         throw new Error("OpenClaw attachment path is outside the managed media directory");
     }
     const before = await lstat(resolved);
-    if (!before.isFile() || before.size > 512 * 1024 * 1024) {
+    // The 2.3 consumer-hardware profile is measured and bounded at 100 MiB per artifact.
+    if (!before.isFile() || before.size > 100 * 1024 * 1024) {
         throw new Error("OpenClaw attachment is not a bounded regular file");
     }
-    const hash = createHash("sha256");
-    for await (const chunk of createReadStream(resolved))
-        hash.update(chunk);
+    const exactBytes = await readFile(resolved);
+    const hash = createHash("sha256").update(exactBytes);
     const after = await lstat(resolved);
     if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
         throw new Error("OpenClaw attachment changed while its digest was computed");
@@ -300,6 +346,53 @@ async function hashInboundAttachment(filePath, mimeType) {
         mimeType,
         bytes: before.size,
         capturedAt: Date.now(),
+        dataBase64: exactBytes.toString("base64"),
+    };
+}
+function managedMediaPath(reference) {
+    const match = /^media:\/\/inbound\/([A-Za-z0-9][A-Za-z0-9._-]{0,255})$/.exec(reference);
+    if (!match || match[1] === "." || match[1] === "..")
+        return null;
+    const root = process.env.ATMEM_OPENCLAW_MEDIA_ROOT
+        ? expandHome(process.env.ATMEM_OPENCLAW_MEDIA_ROOT)
+        : path.join(os.homedir(), ".openclaw", "media");
+    return path.join(root, "inbound", match[1]);
+}
+function attachmentFields(value) {
+    const selected = [];
+    const seen = new Set();
+    const add = (reference, mimeType) => {
+        if (typeof reference !== "string" || !reference)
+            return;
+        const resolved = reference.startsWith("media://") ? managedMediaPath(reference) : reference;
+        if (!resolved || seen.has(resolved))
+            return;
+        seen.add(resolved);
+        selected.push({
+            path: resolved,
+            type: typeof mimeType === "string" && mimeType
+                ? mimeType
+                : "application/octet-stream",
+        });
+    };
+    const visit = (item) => {
+        if (Array.isArray(item)) {
+            for (const child of item)
+                visit(child);
+            return;
+        }
+        if (!item || typeof item !== "object")
+            return;
+        const row = item;
+        add(row.path ?? row.url, row.contentType ?? row.mimeType ?? row.kind);
+        if (row.__openclaw && typeof row.__openclaw === "object") {
+            visit(row.__openclaw.media);
+        }
+    };
+    visit(value);
+    return {
+        paths: selected.map((item) => item.path),
+        types: selected.map((item) => item.type),
     };
 }
 function recordIdFromPath(value) {
@@ -311,7 +404,16 @@ function recordIdFromPath(value) {
 }
 function register(api) {
     const cfg = parseConfig(api.pluginConfig);
-    const attachmentBindingRoot = path.join(path.dirname(cfg.controlPlane.enabled ? cfg.controlPlane.statePath : cfg.dbPath), "openclaw-attachment-bindings");
+    const stateDirectory = path.dirname(cfg.controlPlane.statePath);
+    const selectedHome = process.env.ATMEM_HOME
+        ? expandHome(process.env.ATMEM_HOME)
+        : path.basename(stateDirectory) === "config"
+            ? path.dirname(stateDirectory)
+            : stateDirectory;
+    const runtimeRoot = path.basename(stateDirectory) === "config" || process.env.ATMEM_HOME
+        ? path.join(selectedHome, "runtime")
+        : selectedHome;
+    const attachmentBindingRoot = path.join(runtimeRoot, "openclaw-attachment-bindings");
     const client = new AtmemClient({
         command: cfg.command,
         args: cfg.commandArgs,
@@ -326,6 +428,7 @@ function register(api) {
             log: (message) => api.logger.debug?.(`${TAG} ${message}`),
             logError: (message) => api.logger.warn(`${TAG} ${message}`),
         });
+    const executionSpool = new ExecutionSpool(path.join(runtimeRoot, "openclaw-execution-spool.json"));
     // Let long-lived hosts close the stdio child during lifecycle shutdown.
     // The client's bounded idle shutdown also covers one-shot local runners.
     api.registerService?.({
@@ -434,13 +537,27 @@ function register(api) {
             ? normalized.slice("openclaw".length)
             : normalized;
     };
+    const governedMemoryTools = new Set([
+        "memory_search",
+        "memory_get",
+        "memory_remember",
+        "atmem_observe",
+        "atmem_forget_artifact",
+        "atmem_trace",
+        "atmem_tasks",
+        "atmem_task_progress",
+    ]);
     const recordBlackbox = async (eventType, eventRunId, ctx, payload, toolCallId, correlation = {}) => {
         if (!cfg.controlPlane.blackboxEnabled)
             return;
         try {
-            await blackboxClient.callTool("control_record_blackbox_event", {
+            await executionSpool.enqueue({
                 event_type: eventType,
                 run_id: flightRunId(eventRunId, ctx),
+                execution_id: ctx.executionId,
+                parent_execution_id: ctx.parentExecutionId,
+                attempt_id: ctx.attemptId,
+                retry_of_attempt_id: ctx.retryOfAttemptId,
                 agent_id: agentIdFor(ctx),
                 workspace_id: workspaceIdFor(ctx),
                 subject_id: Object.keys(cfg.agentSubjects).length ? subjectFor(ctx) : undefined,
@@ -452,7 +569,8 @@ function register(api) {
                 context_receipt_id: correlation.contextReceiptId,
                 outcome_id: correlation.outcomeId,
                 payload,
-            }, cfg.recall.timeoutMs);
+            });
+            await executionSpool.flush((event) => blackboxClient.callTool("control_record_blackbox_event", event, cfg.recall.timeoutMs));
         }
         catch (error) {
             api.logger.warn(`${TAG} blackbox event ${eventType} was not recorded: ${error instanceof Error ? error.message : String(error)}`);
@@ -507,6 +625,9 @@ function register(api) {
                 prompt_sha256: promptSha256,
                 prompt_chars: prompt.length,
                 images_count: imagesCount,
+                _atmem_evidence: {
+                    parts: [{ type: "text", text: prompt }],
+                },
             });
             try {
                 await stageInbound(prompt, ctx);
@@ -522,7 +643,7 @@ function register(api) {
         });
         await pending;
     };
-    const bindInboundAttachments = async (keys, paths, types) => {
+    const bindInboundAttachments = async (keys, paths, types, ctx) => {
         const generation = ++nextAttachmentGeneration;
         for (const key of keys) {
             inboundAttachments.delete(key);
@@ -532,6 +653,20 @@ function register(api) {
         if (!paths.length)
             return;
         const items = await Promise.all(paths.map((filePath, index) => hashInboundAttachment(filePath, types[index] ?? types[0] ?? "application/octet-stream")));
+        for (const item of items) {
+            await recordBlackbox("turn.attachment", undefined, ctx, {
+                result_sha256: item.mediaSha256,
+                response_stream_bytes: item.bytes,
+                _atmem_evidence: {
+                    parts: [{
+                            type: item.modality,
+                            mime_type: item.mimeType,
+                            data_base64: item.dataBase64,
+                            host_reference: item.hostReference,
+                        }],
+                },
+            });
+        }
         for (const key of keys) {
             if (inboundAttachmentGeneration.get(key) === generation) {
                 inboundAttachments.set(key, { items, ts: Date.now() });
@@ -557,7 +692,8 @@ function register(api) {
             : typeof rawType === "string"
                 ? [rawType]
                 : [];
-        return { paths, types };
+        const current = attachmentFields(message);
+        return current.paths.length ? current : { paths, types };
     };
     const writtenMessageBindingKeys = (message, ctx) => {
         const idempotencyKey = typeof message.idempotencyKey === "string"
@@ -574,23 +710,57 @@ function register(api) {
     };
     api.on("message_received", async (event, ctx) => {
         const metadata = event.metadata ?? {};
-        const paths = Array.isArray(metadata.mediaPaths)
+        // OpenClaw 2026.9 exposes stable media facts on the event. The metadata
+        // aliases are deprecated and can be absent even though the model receives
+        // the attachment, so use them only as a compatibility fallback.
+        const media = Array.isArray(event.media) ? event.media : [];
+        const currentFields = attachmentFields(media);
+        const current = currentFields.paths.map((path, index) => ({
+            path,
+            type: currentFields.types[index] ?? "application/octet-stream",
+        }));
+        const originalMedia = Array.isArray(event.originalMedia) ? event.originalMedia : [];
+        const originalFields = attachmentFields(originalMedia);
+        const original = originalFields.paths.map((path, index) => ({
+            path,
+            type: originalFields.types[index] ?? "application/octet-stream",
+        }));
+        const legacyPaths = Array.isArray(metadata.mediaPaths)
             ? metadata.mediaPaths.filter((value) => typeof value === "string")
-            : typeof metadata.mediaPath === "string"
-                ? [metadata.mediaPath]
-                : [];
-        const types = Array.isArray(metadata.mediaTypes)
+            : typeof metadata.mediaPath === "string" ? [metadata.mediaPath] : [];
+        const legacyTypes = Array.isArray(metadata.mediaTypes)
             ? metadata.mediaTypes.filter((value) => typeof value === "string")
-            : typeof metadata.mediaType === "string"
-                ? [metadata.mediaType]
-                : [];
+            : typeof metadata.mediaType === "string" ? [metadata.mediaType] : [];
+        const legacyOriginalPaths = Array.isArray(metadata.originalMediaPaths)
+            ? metadata.originalMediaPaths.filter((value) => typeof value === "string")
+            : typeof metadata.originalMediaPath === "string" ? [metadata.originalMediaPath] : [];
+        const legacyOriginalTypes = Array.isArray(metadata.originalMediaTypes)
+            ? metadata.originalMediaTypes.filter((value) => typeof value === "string")
+            : typeof metadata.originalMediaType === "string" ? [metadata.originalMediaType] : [];
+        const selected = current.length
+            ? current
+            : original.length
+                ? original
+                : legacyPaths.map((path, index) => ({
+                    path,
+                    type: legacyTypes[index] ?? legacyTypes[0] ?? "application/octet-stream",
+                })).concat(legacyOriginalPaths.map((path, index) => ({
+                    path,
+                    type: legacyOriginalTypes[index] ?? legacyOriginalTypes[0] ?? "application/octet-stream",
+                })));
+        const paths = selected.map((fact) => fact.path);
+        const types = selected.map((fact) => fact.type);
         const keys = [...new Set([
                 event.sessionKey,
                 event.runId,
                 ...contextIds(ctx),
             ].filter((value) => Boolean(value)))];
         try {
-            await bindInboundAttachments(keys, paths, types);
+            // A staging-pending event has not supplied a safe local path yet. Do not
+            // erase an earlier binding for the same turn while OpenClaw is staging it.
+            if (!paths.length && (event.mediaStagingPending || metadata.mediaStagingPending === true))
+                return;
+            await bindInboundAttachments(keys, paths, types, ctx);
         }
         catch (error) {
             api.logger.warn(`${TAG} inbound attachment provenance unavailable: ${error instanceof Error ? error.message : String(error)}`);
@@ -633,12 +803,21 @@ function register(api) {
                 context_location: deliveredLocation,
                 success: delivered,
                 reason: delivered ? undefined : `expected one exact delegated segment; observed ${occurrences}`,
+                _atmem_evidence: {
+                    context: exact,
+                    delivered_location: deliveredLocation,
+                },
             }, undefined, { contextReceiptId: pending.contextReceiptId });
             if (delivered && pending.exposureId) {
                 await callFor(ctx, "control_exposure_shown", { exposure_id: pending.exposureId }, cfg.recall.timeoutMs);
             }
             cachePendingPrompt(sessionKey, { ...pending, delegatedContext: undefined });
         }
+        const modelMediaParts = inlineMediaParts([
+            event.historyMessages,
+            event.messages,
+            event.images,
+        ]);
         await recordBlackbox("model.input", event.runId, ctx, {
             provider: event.provider,
             model: event.model,
@@ -650,6 +829,13 @@ function register(api) {
             history_count: Array.isArray(event.historyMessages) ? event.historyMessages.length : 0,
             images_count: event.imagesCount ?? 0,
             tools_count: Array.isArray(event.tools) ? event.tools.length : 0,
+            _atmem_evidence: {
+                prompt: event.prompt ?? "",
+                system_prompt: event.systemPrompt ?? "",
+                history_messages: event.historyMessages ?? [],
+                tools: event.tools ?? [],
+                parts: modelMediaParts,
+            },
         });
     });
     api.on("llm_output", async (event, ctx) => {
@@ -680,6 +866,10 @@ function register(api) {
             usage: event.usage ?? {},
             reasoning_effort: event.reasoningEffort,
             fast_mode: event.fastMode,
+            _atmem_evidence: {
+                assistant_texts: responses,
+                usage: event.usage ?? {},
+            },
         });
     });
     api.registerCli?.(({ program }) => {
@@ -995,6 +1185,8 @@ function register(api) {
                     max_records: cfg.recall.maxRecords,
                     max_chars: cfg.recall.maxChars,
                     min_score: cfg.recall.minScore,
+                    require_direct_support: cfg.recall.requireDirectSupport,
+                    exclude_record_ids: personaRecordIds,
                     reference_mode: cfg.cacheAware.enabled && cfg.cacheAware.compactReferences
                         ? "compact"
                         : "full",
@@ -1072,8 +1264,15 @@ function register(api) {
             context_chars: memoryContext.length,
             candidate_ids: candidateIds,
             context_component_event_ids: componentEventIds,
+            persona_record_count: personaRecordIds.length,
+            recall_record_count: (current?.injectedRecordIds ?? []).length,
+            context_selection_profile: cfg.recall.requireDirectSupport ? "direct-support-v1" : "rank-threshold-v1",
             mode: "direct",
             context_location: contextLocation,
+            _atmem_evidence: {
+                context: memoryContext,
+                envelope: result,
+            },
         }, undefined, {
             retrievalId: current?.retrievalId,
             contextEventId: current?.contextEventId ?? personaContextEventId,
@@ -1111,7 +1310,16 @@ function register(api) {
             derived_path_sha256: Array.isArray(event.derivedPaths)
                 ? event.derivedPaths.map((value) => digestText(String(value)))
                 : [],
+            _atmem_evidence: {
+                params: event.params ?? {},
+                derived_paths: event.derivedPaths ?? [],
+            },
         }, event.toolCallId ?? ctx.toolCallId);
+        // These virtual tools operate through AtMem. Their arguments legitimately
+        // contain values such as `corpus: "memory"`; they are not filesystem
+        // access to OpenClaw's frozen MEMORY.md or memory/* tree.
+        if (governedMemoryTools.has(canonicalToolName(event.toolName)))
+            return;
         if (!cfg.takeoverActive || !cfg.nativeWorkspaces.some((workspace) => touchesNativeMemory(event, workspace)))
             return;
         const reason = "AtMem takeover blocked access to OpenClaw's frozen native memory " +
@@ -1134,9 +1342,18 @@ function register(api) {
             tool_name: event.toolName,
             tool_canonical_name: canonicalToolName(event.toolName),
             result_sha256: digestJson(event.result ?? null),
+            ...(!event.error ? progressCardComparison(event.toolName, event.result, digestJson) : {}),
             outcome: event.error ? "error" : "completed",
             error_category: event.error ? "tool_error" : undefined,
+            error_reason: event.error ? toolErrorReason(event.error) : undefined,
+            error_sha256: event.error ? digestText(event.error) : undefined,
+            result_present: event.result !== undefined,
             duration_ms: event.durationMs ?? 0,
+            _atmem_evidence: {
+                params: event.params ?? {},
+                result: event.result ?? null,
+                error: event.error ?? null,
+            },
         }, event.toolCallId ?? ctx.toolCallId);
     });
     // ---- auto-capture: user turn through the pipeline, assistant as digest -
@@ -1146,11 +1363,25 @@ function register(api) {
                 tool_name: saved.name, tool_canonical_name: canonicalToolName(saved.name),
                 result_sha256: saved.result.digest, outcome: saved.result.error ? "error" : "completed",
                 error_category: saved.result.error ? "tool_error" : undefined,
+                error_reason: saved.result.reason,
+                error_sha256: saved.result.errorDigest,
                 reason: "observed_terminal_host_tool_event",
             }, saved.callId);
         });
         const sessionKey = sessionKeyFor(ctx);
         const observedTurnInputKey = turnInputKey(ctx);
+        // Current OpenClaw WebChat persists exact attachment provenance on the
+        // user transcript as __openclaw.media[].url = media://inbound/<id>. Some
+        // earlier hooks omit it, so agent_end is the durable late-capture boundary.
+        const completedTurnMedia = attachmentFields(event.messages);
+        if (completedTurnMedia.paths.length) {
+            try {
+                await bindInboundAttachments([...new Set([sessionKey, event.runId, ...contextIds(ctx)].filter((value) => Boolean(value)))], completedTurnMedia.paths, completedTurnMedia.types, ctx);
+            }
+            catch (error) {
+                api.logger.warn(`${TAG} completed-turn attachment capture unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         const cached = pendingPrompts.get(sessionKey);
         deletePendingPrompt(sessionKey);
         const userText = cached?.text?.replace(INJECT_RE, "").trim();
@@ -1254,6 +1485,10 @@ function register(api) {
                 turn_messages_sha256: turnMessagesSha256,
                 digest_profile: "atmem-turn-messages-canonical-json-v1",
                 messages_count: Array.isArray(event.messages) ? event.messages.length : 0,
+                _atmem_evidence: {
+                    messages: event.messages ?? [],
+                    error: event.error ?? null,
+                },
             }, undefined, {
                 retrievalId: cached?.retrievalId,
                 contextEventId: cached?.contextEventId,
@@ -1274,8 +1509,10 @@ function register(api) {
         // by scanning the media directory or scraping its name from user text.
         const attachmentFields = writtenMessageAttachmentFields(message);
         const attachmentKeys = writtenMessageBindingKeys(message, ctx);
-        if (attachmentKeys.length) {
-            void bindInboundAttachments(attachmentKeys, attachmentFields.paths, attachmentFields.types).catch((error) => {
+        // A sparse transcript message is normal in current OpenClaw. It must not
+        // erase the binding already established by message_received.
+        if (attachmentKeys.length && attachmentFields.paths.length) {
+            void bindInboundAttachments(attachmentKeys, attachmentFields.paths, attachmentFields.types, ctx).catch((error) => {
                 api.logger.warn(`${TAG} persisted attachment provenance unavailable: ${error instanceof Error ? error.message : String(error)}`);
             });
         }

package/dist/src/execution-spool.js

@@ -0,0 +1,189 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+const SPOOL_AAD = Buffer.from("atmem-openclaw-encrypted-execution-spool-v2", "utf8");
+/** A bounded, atomic local spool. Removal requires a durable terminal receipt. */
+export class ExecutionSpool {
+    filePath;
+    maxPending;
+    maxAgeMs;
+    keyPath;
+    state = null;
+    serial = Promise.resolve();
+    constructor(filePath, maxPending = 2048, maxAgeMs = 7 * 24 * 60 * 60 * 1000, keyPath = path.resolve(path.dirname(filePath), "..", ".atmem-evidence-keys", "openclaw-spool.key")) {
+        this.filePath = filePath;
+        this.maxPending = maxPending;
+        this.maxAgeMs = maxAgeMs;
+        this.keyPath = keyPath;
+        if (maxPending < 2)
+            throw new Error("execution spool capacity must be at least 2");
+    }
+    enqueue(value) {
+        return this.exclusive(async () => {
+            const state = await this.load();
+            this.expirePending(state, Date.now() - this.maxAgeMs);
+            const envelope = {
+                ...value,
+                event_id: randomUUID(),
+                producer_instance_id: state.producerInstanceId,
+                producer_epoch: state.producerEpoch,
+                producer_sequence: state.nextSequence++,
+                event_time: new Date().toISOString(),
+            };
+            state.pending.push(envelope);
+            if (state.pending.length > this.maxPending) {
+                const dropped = state.pending.length - this.maxPending + 1;
+                const removed = state.pending.splice(0, dropped);
+                state.pending.unshift({
+                    event_type: "capture.gap",
+                    run_id: String(envelope.run_id ?? "capture-spool"),
+                    payload: {
+                        reason: "spool_capacity_exceeded",
+                        dropped_count: removed.length,
+                        first_sequence: removed[0]?.producer_sequence,
+                        last_sequence: removed.at(-1)?.producer_sequence,
+                    },
+                    event_id: randomUUID(),
+                    producer_instance_id: state.producerInstanceId,
+                    producer_epoch: state.producerEpoch,
+                    producer_sequence: state.nextSequence++,
+                    event_time: new Date().toISOString(),
+                });
+            }
+            await this.persist(state);
+            return envelope;
+        });
+    }
+    flush(send) {
+        return this.exclusive(async () => {
+            const state = await this.load();
+            let acknowledged = 0;
+            while (state.pending.length) {
+                const result = await send(state.pending[0]);
+                const receipt = result;
+                const accepted = receipt?.durably_accepted === true;
+                const classifiedConflict = receipt?.decision === "conflict" &&
+                    receipt?.durably_classified === true;
+                if (!accepted && !classifiedConflict) {
+                    throw new Error("AtMem did not confirm a durable terminal execution-event decision");
+                }
+                state.pending.shift();
+                acknowledged += 1;
+                await this.persist(state);
+            }
+            return acknowledged;
+        });
+    }
+    async snapshot() {
+        return this.exclusive(async () => ({ ...(await this.load()), pending: [...(await this.load()).pending] }));
+    }
+    exclusive(action) {
+        const next = this.serial.then(action, action);
+        this.serial = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    async load() {
+        if (this.state)
+            return this.state;
+        try {
+            const wrapper = JSON.parse(await readFile(this.filePath, "utf8"));
+            if (wrapper.format !== "atmem-openclaw-encrypted-execution-spool-v2") {
+                throw new Error("unsupported execution spool format");
+            }
+            const key = await this.loadOrCreateKey();
+            const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(wrapper.nonce, "base64"));
+            decipher.setAAD(SPOOL_AAD);
+            decipher.setAuthTag(Buffer.from(wrapper.tag, "base64"));
+            const plain = Buffer.concat([
+                decipher.update(Buffer.from(wrapper.ciphertext, "base64")), decipher.final(),
+            ]).toString("utf8");
+            const value = JSON.parse(plain);
+            if (value.format !== "atmem-openclaw-execution-spool-v1" || !Array.isArray(value.pending)) {
+                throw new Error("unsupported decrypted execution spool state");
+            }
+            // Pending events retain their original epoch. New events get a fresh
+            // epoch and sequence after every plugin process start.
+            this.state = {
+                ...value,
+                producerEpoch: randomUUID(),
+                nextSequence: 1,
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT")
+                throw error;
+            this.state = {
+                format: "atmem-openclaw-execution-spool-v1",
+                producerInstanceId: randomUUID(),
+                producerEpoch: randomUUID(),
+                nextSequence: 1,
+                pending: [],
+            };
+        }
+        await this.persist(this.state);
+        return this.state;
+    }
+    async persist(state) {
+        await mkdir(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+        const key = await this.loadOrCreateKey();
+        const nonce = randomBytes(12);
+        const cipher = createCipheriv("aes-256-gcm", key, nonce);
+        cipher.setAAD(SPOOL_AAD);
+        const ciphertext = Buffer.concat([
+            cipher.update(JSON.stringify(state), "utf8"), cipher.final(),
+        ]);
+        const wrapper = {
+            format: "atmem-openclaw-encrypted-execution-spool-v2",
+            suite: "AES-256-GCM",
+            nonce: nonce.toString("base64"),
+            ciphertext: ciphertext.toString("base64"),
+            tag: cipher.getAuthTag().toString("base64"),
+        };
+        const temporary = `${this.filePath}.${process.pid}.${randomUUID()}.tmp`;
+        await writeFile(temporary, `${JSON.stringify(wrapper)}\n`, { encoding: "utf8", mode: 0o600 });
+        await rename(temporary, this.filePath);
+        await chmod(this.filePath, 0o600);
+    }
+    async loadOrCreateKey() {
+        await mkdir(path.dirname(this.keyPath), { recursive: true, mode: 0o700 });
+        try {
+            const encoded = (await readFile(this.keyPath, "utf8")).trim();
+            const key = Buffer.from(encoded, "base64");
+            if (key.length !== 32)
+                throw new Error("execution spool key must be 256 bits");
+            return key;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const key = randomBytes(32);
+            await writeFile(this.keyPath, `${key.toString("base64")}\n`, {
+                encoding: "utf8", mode: 0o600, flag: "wx",
+            });
+            await chmod(this.keyPath, 0o600);
+            return key;
+        }
+    }
+    expirePending(state, cutoff) {
+        const expired = state.pending.filter(event => Date.parse(event.event_time) < cutoff);
+        if (!expired.length)
+            return;
+        state.pending = state.pending.filter(event => Date.parse(event.event_time) >= cutoff);
+        state.pending.unshift({
+            event_type: "capture.gap",
+            run_id: String(expired.at(-1)?.run_id ?? "capture-spool"),
+            payload: {
+                reason: "spool_retention_expired",
+                dropped_count: expired.length,
+                first_sequence: expired[0].producer_sequence,
+                last_sequence: expired.at(-1)?.producer_sequence,
+            },
+            event_id: randomUUID(),
+            producer_instance_id: state.producerInstanceId,
+            producer_epoch: state.producerEpoch,
+            producer_sequence: state.nextSequence++,
+            event_time: new Date().toISOString(),
+        });
+    }
+}

package/dist/src/rpc-client.js

@@ -128,7 +128,7 @@ export class AtmemClient {
             capabilities: {},
             clientInfo: {
                 name: "openclaw-memory-atmem",
-                version: "2.2.6",
+                version: "2.3.2",
             },
         });
         this.notify("notifications/initialized", {});

package/dist/src/setup.js

@@ -42,7 +42,7 @@ export function setupWrites(options) {
             minScore: 0.3,
             timeoutMs: 3000,
         },
-        persona: { enabled: true, maxChars: 600, ttlSeconds: 300 },
+        persona: { enabled: false, maxChars: 600, ttlSeconds: 300 },
         capture: { enabled: true, captureAssistant: true },
         cacheAware: { enabled: true, compactReferences: true },
         tools: { enabled: true },

package/dist/src/tool-errors.js

@@ -0,0 +1,31 @@
+/** Retain a bounded diagnostic, never the full tool result or stack trace. */
+export function toolErrorReason(value) {
+    let text = value;
+    if (value && typeof value === "object") {
+        const row = value;
+        text = row.error ?? row.message;
+        if (text && typeof text === "object")
+            text = text.message;
+        if (text === undefined && Array.isArray(row.content)) {
+            text = row.content.find(item => item?.type === "text" && typeof item.text === "string")?.text;
+        }
+    }
+    if (typeof text !== "string" || !text.trim())
+        return undefined;
+    const bounded = text.slice(0, 8192);
+    // OpenClaw wraps thrown web errors as untrusted API content. Extract only
+    // its narrow status prefix, never the page text or instructions beneath it.
+    if (bounded.startsWith("SECURITY NOTICE:")) {
+        const status = bounded.match(/<<<EXTERNAL_UNTRUSTED_CONTENT id="[a-f0-9]+">>>\r?\nSource: API\r?\n---\r?\n(Web fetch failed \([1-5][0-9]{2}\)):/);
+        return status?.[1];
+    }
+    return bounded.split(/[\r\n]/, 1)[0]
+        .replace(/https?:\/\/[^\s<>]+/gi, "[redacted-url]")
+        .replace(/\b(?:Bearer|Basic)\s+\S+/gi, "[redacted-auth]")
+        .replace(/\b(?:api[_-]?key|token|password|passwd|secret|authorization|cookie)\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/gi, "[redacted-credential]")
+        .replace(/\b(?:sk-|ghp_|github_pat_)[A-Za-z0-9_-]+/g, "[redacted-token]")
+        .replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, "[redacted-email]")
+        .replace(/(?:[A-Za-z]:\\|\/)[^\s<>"']+/g, "[redacted-path]")
+        .replace(/"[^"\r\n]*"|'[^'\r\n]*'/g, "[redacted-value]")
+        .replace(/[\x00-\x1f\x7f]/g, " ").trim().slice(0, 512) || undefined;
+}

package/dist/src/tool-observations.js

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
+import { toolErrorReason } from "./tool-errors.js";
 const CACHE_KEY = Symbol.for("atmem.tool-observation-cache.v1");
 const sharedCache = globalThis;
 const cache = sharedCache[CACHE_KEY] ??= new Map();
 /** Some hosts deny run-context writes from tool hooks after registry reload.
- * Keep a bounded content-free process fallback, isolated by installation config.
+ * Keep a bounded content-minimized process fallback, isolated by installation config.
  */
 export function observationContext(host, scope) {
     const keyFor = (runId, namespace) => JSON.stringify([scope, runId, namespace]);
@@ -45,7 +46,7 @@ function canonical(name) {
     const unwrapped = name.replace(/^mcp__openclaw__/, "");
     return { Read: "read", Bash: "exec" }[unwrapped] ?? unwrapped;
 }
-/** Stores only scope, names and digests in bounded ephemeral observation context. */
+/** Stores scope, names, digests and redacted error diagnostics in bounded ephemeral context. */
 export class ToolObservations {
     access;
     digest;
@@ -88,9 +89,12 @@ export class ToolObservations {
             (event.agentId !== undefined && event.agentId !== saved.ctx.agentId) ||
             canonical(d.name) !== canonical(saved.name))
             return;
-        const result = { digest: this.digest(d.result), error: d.isError };
+        const result = { digest: this.digest(d.result), error: d.isError,
+            reason: d.isError ? toolErrorReason(d.error ?? d.result) : undefined,
+            errorDigest: d.isError && d.error !== undefined ? this.digest(d.error) : undefined };
         const conflict = saved.conflict || (saved.result !== undefined &&
-            (saved.result.digest !== result.digest || saved.result.error !== result.error));
+            (saved.result.digest !== result.digest || saved.result.error !== result.error ||
+                saved.result.errorDigest !== result.errorDigest));
         this.access.setRunContext({ ...key, value: { ...saved, result, conflict } });
     }
     async flush(ctx, record) {

package/dist/src/tool-result-comparison.js

@@ -0,0 +1,45 @@
+// Exact OpenClaw progress_card ↔ native relay equivalence. Never discard raw digests.
+export function progressCardComparison(name, result, digest) {
+    if (name !== "progress_card")
+        return {};
+    const record = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+    const keys = (v, expected) => Object.keys(v).sort().join(",") === [...expected].sort().join(",");
+    const native = Array.isArray(result);
+    if (!native && (!record(result) || !keys(result, ["content", "details"])))
+        return {};
+    const content = native ? result : result.content;
+    if (!Array.isArray(content) || content.length !== 2 || !content.every(v => record(v) && keys(v, ["type", "text"]) && v.type === (native ? "input_text" : "text") &&
+        typeof v.text === "string" && v.text.length <= 1024))
+        return {};
+    let payload;
+    try {
+        payload = JSON.parse(content[1].text);
+    }
+    catch {
+        return {};
+    }
+    if (!record(payload) || !keys(payload, ["revision", "steps"]))
+        return {};
+    const { revision, steps } = payload;
+    if (revision !== null && (!Number.isSafeInteger(revision) || revision < 1))
+        return {};
+    if (steps !== null && (!record(steps) || !keys(steps, ["completed", "total"]) ||
+        !Number.isSafeInteger(steps.completed) || !Number.isSafeInteger(steps.total) ||
+        steps.completed < 0 || steps.total < 1 || steps.total > 50 ||
+        steps.completed > steps.total))
+        return {};
+    if (revision === null && steps !== null)
+        return {};
+    const expected = revision === null ? "Progress card cleared" : steps === null
+        ? `Progress card updated (rev ${revision})`
+        : `Progress card updated (rev ${revision}, ${steps.completed}/${steps.total} done)`;
+    if (content[0].text !== expected || content[1].text !== JSON.stringify(payload, null, 2))
+        return {};
+    if (!native && digest(result.details) !== digest(payload))
+        return {};
+    return {
+        result_comparison_profile: "openclaw-progress-card-v1",
+        result_comparison_sha256: digest(payload),
+        result_observation_shape: native ? "native_input_text" : "tool_content_details",
+    };
+}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "memory-atmem",
   "name": "Memory (atmem)",
   "description": "OpenClaw bridge installed and managed by the AtMem memory control plane.",
-  "version": "2.2.6",
+  "version": "2.3.2",
   "commandAliases": ["memory-atmem"],
   "activation": {
     "onStartup": true,
@@ -37,7 +37,7 @@
       },
       "dbPath": {
         "type": "string",
-        "default": "~/.atmem/memories.db",
+        "default": "~/.atmem/memory/memories.db",
         "description": "SQLite database path (also auditable from outside OpenClaw via `atmem verify`)"
       },
       "subject": {
@@ -81,15 +81,16 @@
           "enabled": { "type": "boolean", "default": true },
           "maxRecords": { "type": "number", "default": 3, "description": "Max memories injected per turn" },
           "maxChars": { "type": "number", "default": 1200, "description": "Total character budget for the injected block" },
+          "requireDirectSupport": { "type": "boolean", "default": true, "description": "Require direct query relevance for automatic recall; rank score alone is insufficient" },
           "minScore": { "type": "number", "default": 0.3, "description": "Minimum relevance score; 0.3 requires a lexical match (priors alone never inject)" },
           "timeoutMs": { "type": "number", "default": 4000, "description": "Recall timeout; on timeout the turn proceeds without injection" }
         }
       },
       "persona": {
         "type": "object",
-        "description": "L3 persona snapshot injected alongside recall",
+        "description": "Optional always-on persona snapshot; disabled by default to avoid unrelated context",
         "properties": {
-          "enabled": { "type": "boolean", "default": true },
+          "enabled": { "type": "boolean", "default": false },
           "maxChars": { "type": "number", "default": 600, "description": "Character budget for the <user_persona> block" },
           "ttlSeconds": { "type": "number", "default": 300, "description": "Persona cache lifetime; also invalidated whenever new memory is captured" }
         }
@@ -128,13 +129,13 @@
           },
           "statePath": {
             "type": "string",
-            "default": "~/.atmem/control-plane.json",
+            "default": "~/.atmem/config/control-plane.json",
             "description": "Digest-bound control file written by `atmem control`."
           },
           "blackboxEnabled": {
             "type": "boolean",
-            "default": false,
-            "description": "Record content-minimizing agent flights through the private control protocol. Managed automatically by the AtMem installer."
+            "default": true,
+            "description": "Record encrypted full-fidelity text, link/page, file, image, audio and video evidence plus metadata through the private control protocol. Set false to disable the recorder."
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-atmem",
-  "version": "2.2.6",
+  "version": "2.3.2",
   "description": "OpenClaw Agent Black Box and memory control-plane bridge for AtMem",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,7 +40,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node test/manifest.mjs && node test/hook-context-compat.mjs && node test/setup.mjs && node test/hooks.mjs && node test/delegated-identity.mjs && node test/tool-observations.mjs && node test/task-tools.mjs && node test/delegated-context-contract.mjs",
+    "test": "node test/manifest.mjs && node test/hook-context-compat.mjs && node test/setup.mjs && node test/hooks.mjs && node test/delegated-identity.mjs && node test/tool-observations.mjs && node test/tool-result-comparison.mjs && node test/blackbox-diagnostics.mjs && node test/execution-spool.mjs && node test/task-tools.mjs && node test/delegated-context-contract.mjs",
     "smoke": "node test/smoke.mjs && node test/task-journey.mjs && node test/delegated-journey.mjs",
     "prepack": "npm run build && npm run typecheck && npm test && npm run smoke",
     "hook-context": "node test/hook-context-compat.mjs",