openclaw-memory-atmem 1.0.0 → 2.0.0

package/README.md

@@ -5,11 +5,11 @@ 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 atmem==1.0.0
+python -m pip install atmem==2.0.0
 atmem openclaw install
 ```
 
-The installer pins `openclaw-memory-atmem@1.0.0`, binds the exact `atmem` executable, copies existing OpenClaw memory, configures shadow mode, restarts the gateway and verifies the loaded plugin. Direct npm installation cannot perform or prove those steps.
+The installer pins `openclaw-memory-atmem@2.0.0`, binds the exact `atmem` executable, copies existing OpenClaw memory, configures shadow mode, restarts the gateway and verifies the loaded plugin. Direct npm installation cannot perform or prove those steps.
 
 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.
 

package/dist/index.js

@@ -333,7 +333,13 @@ function register(api) {
         }
     };
     const flightRunId = (eventRunId, ctx) => eventRunId ?? ctx.runId ?? ctx.sessionKey ?? ctx.sessionId ?? "unidentified-run";
-    const recordBlackbox = async (eventType, eventRunId, ctx, payload, toolCallId) => {
+    const canonicalToolName = (value) => {
+        const normalized = value.trim();
+        return normalized.startsWith("openclaw") && normalized.length > "openclaw".length
+            ? normalized.slice("openclaw".length)
+            : normalized;
+    };
+    const recordBlackbox = async (eventType, eventRunId, ctx, payload, toolCallId, correlation = {}) => {
         if (!cfg.controlPlane.blackboxEnabled)
             return;
         try {
@@ -342,6 +348,11 @@ function register(api) {
                 run_id: flightRunId(eventRunId, ctx),
                 session_id: ctx.sessionId ?? ctx.sessionKey,
                 tool_call_id: toolCallId,
+                turn_id: correlation.turnId ?? flightRunId(eventRunId, ctx),
+                retrieval_id: correlation.retrievalId,
+                context_event_id: correlation.contextEventId,
+                context_receipt_id: correlation.contextReceiptId,
+                outcome_id: correlation.outcomeId,
                 payload,
             }, cfg.recall.timeoutMs);
         }
@@ -485,13 +496,28 @@ function register(api) {
     });
     api.on("llm_output", async (event, ctx) => {
         const responses = Array.isArray(event.assistantTexts) ? event.assistantTexts : [];
+        const visibleText = responses.map(String).join("");
+        const assistantVisibleTextSha256 = digestText(visibleText);
+        const modelOutputBundleSha256 = digestJson(responses);
+        const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? "default-session";
+        const pending = pendingPrompts.get(sessionKey);
+        if (pending) {
+            pendingPrompts.set(sessionKey, {
+                ...pending,
+                assistantVisibleTextSha256,
+                modelOutputBundleSha256,
+            });
+        }
         await recordBlackbox("model.output", event.runId, ctx, {
             provider: event.provider,
             model: event.model,
             resolved_ref: event.resolvedRef,
             harness_id: event.harnessId,
-            response_sha256: digestJson(responses),
-            response_chars: responses.reduce((total, value) => total + String(value).length, 0),
+            response_sha256: assistantVisibleTextSha256,
+            assistant_visible_text_sha256: assistantVisibleTextSha256,
+            model_output_bundle_sha256: modelOutputBundleSha256,
+            response_digest_profile: "atmem-assistant-visible-text-utf8-v1",
+            response_chars: visibleText.length,
             response_count: responses.length,
             usage: event.usage ?? {},
             reasoning_effort: event.reasoningEffort,
@@ -558,10 +584,10 @@ function register(api) {
     };
     async function personaBlock(sessionKey) {
         if (!cfg.persona.enabled)
-            return "";
+            return { block: "", recordIds: [] };
         const now = Date.now();
         if (personaCache && now - personaCache.ts < cfg.persona.ttlSeconds * 1000) {
-            return personaCache.block;
+            return personaCache;
         }
         const result = (await client.callTool("memory_persona", {
             session_id: sessionKey,
@@ -570,8 +596,13 @@ function register(api) {
                 ? "compact"
                 : "full",
         }, cfg.recall.timeoutMs));
-        personaCache = { block: result?.block ?? "", ts: now };
-        return personaCache.block;
+        personaCache = {
+            block: result?.block ?? "",
+            recordIds: result?.record_ids ?? [],
+            contextEventId: result?.context_event_id,
+            ts: now,
+        };
+        return personaCache;
     }
     // ---- auto-recall: persona + bounded, audited recall injection ---------
     api.on("before_prompt_build", async (event, ctx) => {
@@ -589,13 +620,26 @@ function register(api) {
                     text: userText,
                     ts: Date.now(),
                     exposureId: prepared.exposure_id,
+                    contextReceiptId: prepared.context_receipt_id,
                 });
-                await recordBlackbox(prepared.inject && prepared.context ? "context.injected" : "context.prepared", undefined, ctx, {
+                await recordBlackbox("context.disposition", undefined, ctx, {
+                    disposition: prepared.inject && prepared.context
+                        ? "injected"
+                        : prepared.mode === "shadow" && (prepared.preview_context ?? "")
+                            ? "withheld_by_policy"
+                            : "no_relevant_memory",
                     context_sha256: digestText(prepared.context ?? ""),
+                    context_block_sha256: digestText(prepared.context ?? ""),
+                    context_envelope_sha256: digestJson({ appendContext: prepared.context ?? "" }),
+                    context_receipt_sha256: prepared.manifest_sha256,
+                    digest_profile: "atmem-context-envelope-canonical-json-v1",
                     context_chars: (prepared.context ?? "").length,
                     candidate_ids: prepared.candidate_ids ?? [],
                     exposure_id: prepared.exposure_id,
                     mode: prepared.mode,
+                    context_location: prepared.inject ? "appendContext" : "none",
+                }, undefined, {
+                    contextReceiptId: prepared.context_receipt_id,
                 });
                 if (prepared.inject && prepared.context) {
                     api.logger.info(`${TAG} memory control plane ${prepared.mode ?? "active"} context exposed`);
@@ -604,21 +648,52 @@ function register(api) {
                 return;
             }
             catch (error) {
+                await recordBlackbox("context.disposition", undefined, ctx, {
+                    disposition: "recall_failed",
+                    context_block_sha256: digestText(""),
+                    context_envelope_sha256: digestJson({}),
+                    digest_profile: "atmem-context-envelope-canonical-json-v1",
+                    context_chars: 0,
+                    candidate_ids: [],
+                    mode: "control-plane",
+                    context_location: "none",
+                    reason: error instanceof Error ? error.message : String(error),
+                });
                 api.logger.warn(`${TAG} memory control plane failed closed: ${error instanceof Error ? error.message : String(error)}`);
                 return;
             }
         }
         if (!cfg.recall.enabled && !cfg.persona.enabled) {
-            if (takeoverGuidance)
-                return { appendSystemContext: takeoverGuidance };
+            const result = takeoverGuidance
+                ? { appendSystemContext: takeoverGuidance }
+                : {};
+            await recordBlackbox("context.disposition", undefined, ctx, {
+                disposition: "not_applicable",
+                context_block_sha256: digestText(""),
+                context_envelope_sha256: digestJson(result),
+                digest_profile: "atmem-context-envelope-canonical-json-v1",
+                context_chars: 0,
+                candidate_ids: [],
+                mode: "direct",
+                context_location: "none",
+            });
+            if (Object.keys(result).length)
+                return result;
             return;
         }
         let persona = "";
+        let personaRecordIds = [];
+        let personaContextEventId;
         let recall = "";
+        let recallFailed = false;
         try {
-            persona = await personaBlock(sessionKey);
+            const personaResult = await personaBlock(sessionKey);
+            persona = personaResult.block;
+            personaRecordIds = personaResult.recordIds;
+            personaContextEventId = personaResult.contextEventId;
         }
         catch (error) {
+            recallFailed = true;
             api.logger.warn(`${TAG} persona skipped: ${error instanceof Error ? error.message : String(error)}`);
         }
         try {
@@ -643,6 +718,7 @@ function register(api) {
                             injectedRecordIds: result.record_ids ?? [],
                             retrievalId: result.retrieval_id,
                             contextEventId: result.context_event_id,
+                            contextReceiptId: result.context_event_id,
                         });
                     }
                 }
@@ -650,25 +726,68 @@ function register(api) {
         }
         catch (error) {
             // Never block the turn on recall problems.
+            recallFailed = true;
             api.logger.warn(`${TAG} auto-recall skipped: ${error instanceof Error ? error.message : String(error)}`);
         }
+        let result = {};
+        let contextLocation = "none";
         if (cfg.cacheAware.enabled) {
-            const result = {};
             const systemParts = [takeoverGuidance, persona].filter(Boolean);
             if (systemParts.length)
                 result.appendSystemContext = systemParts.join("\n\n");
             if (recall)
                 result.appendContext = recall;
-            if (Object.keys(result).length)
-                return result;
-            return;
+            contextLocation = recall
+                ? "appendContext"
+                : persona
+                    ? "appendSystemContext"
+                    : "none";
+        }
+        else {
+            const parts = [persona, recall].filter(Boolean);
+            if (parts.length)
+                result.prependContext = parts.join("\n\n") + "\n\n";
+            if (takeoverGuidance)
+                result.appendSystemContext = takeoverGuidance;
+            contextLocation = parts.length ? "prependContext" : "none";
+        }
+        const memoryContext = [persona, recall].filter(Boolean).join("\n\n");
+        const current = pendingPrompts.get(sessionKey);
+        const candidateIds = [...new Set([
+                ...personaRecordIds,
+                ...(current?.injectedRecordIds ?? []),
+            ])];
+        const componentEventIds = [...new Set([
+                personaContextEventId,
+                current?.contextEventId,
+            ].filter((value) => Boolean(value)))];
+        const contextEnvelopeSha256 = digestJson(result);
+        const contextReceiptId = componentEventIds.length
+            ? `ctxr_${digestJson({ componentEventIds, contextEnvelopeSha256 })}`
+            : undefined;
+        if (current) {
+            pendingPrompts.set(sessionKey, { ...current, contextReceiptId });
         }
-        const parts = [persona, recall].filter(Boolean);
-        const result = {};
-        if (parts.length)
-            result.prependContext = parts.join("\n\n") + "\n\n";
-        if (takeoverGuidance)
-            result.appendSystemContext = takeoverGuidance;
+        await recordBlackbox("context.disposition", undefined, ctx, {
+            disposition: memoryContext
+                ? "injected"
+                : recallFailed
+                    ? "recall_failed"
+                    : "no_relevant_memory",
+            context_sha256: digestText(memoryContext),
+            context_block_sha256: digestText(memoryContext),
+            context_envelope_sha256: contextEnvelopeSha256,
+            digest_profile: "atmem-context-envelope-canonical-json-v1",
+            context_chars: memoryContext.length,
+            candidate_ids: candidateIds,
+            context_component_event_ids: componentEventIds,
+            mode: "direct",
+            context_location: contextLocation,
+        }, undefined, {
+            retrievalId: current?.retrievalId,
+            contextEventId: current?.contextEventId ?? personaContextEventId,
+            contextReceiptId,
+        });
         if (Object.keys(result).length)
             return result;
     });
@@ -676,6 +795,7 @@ function register(api) {
     api.on("before_tool_call", async (event, ctx) => {
         await recordBlackbox("tool.requested", event.runId, ctx, {
             tool_name: event.toolName,
+            tool_canonical_name: canonicalToolName(event.toolName),
             tool_kind: event.toolKind,
             params_sha256: digestJson(event.params ?? {}),
             param_keys: Object.keys(event.params ?? {}).sort(),
@@ -690,6 +810,7 @@ function register(api) {
             "and memory_search or memory_get for recall.";
         await recordBlackbox("tool.completed", event.runId, ctx, {
             tool_name: event.toolName,
+            tool_canonical_name: canonicalToolName(event.toolName),
             outcome: "error",
             error_category: "blocked_by_memory_boundary",
             result_sha256: digestText(reason),
@@ -701,6 +822,7 @@ function register(api) {
     api.on("after_tool_call", async (event, ctx) => {
         await recordBlackbox("tool.completed", event.runId, ctx, {
             tool_name: event.toolName,
+            tool_canonical_name: canonicalToolName(event.toolName),
             result_sha256: digestJson(event.result ?? null),
             outcome: event.error ? "error" : "completed",
             error_category: event.error ? "tool_error" : undefined,
@@ -734,15 +856,19 @@ function register(api) {
                         continue;
                     const responseText = messageText(message.content);
                     if (responseText) {
+                        const assistantVisibleTextSha256 = cached.assistantVisibleTextSha256 ?? digestText(responseText);
                         await client.callTool("memory_log_action", {
                             action_type: "agent.response_after_memory",
                             payload: {
-                                response_sha256: createHash("sha256")
-                                    .update(responseText, "utf8")
-                                    .digest("hex"),
+                                response_sha256: assistantVisibleTextSha256,
+                                assistant_visible_text_sha256: assistantVisibleTextSha256,
+                                model_output_bundle_sha256: cached.modelOutputBundleSha256,
+                                response_digest_profile: "atmem-assistant-visible-text-utf8-v1",
                                 injected_record_ids: cached.injectedRecordIds,
                                 retrieval_id: cached.retrievalId,
                                 context_event_id: cached.contextEventId,
+                                context_receipt_id: cached.contextReceiptId,
+                                run_id: flightRunId(event.runId, ctx),
                                 response_content_stored: false,
                                 success: event.success !== false,
                             },
@@ -788,13 +914,23 @@ function register(api) {
             api.logger.warn(`${TAG} auto-capture failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         finally {
+            const cancelled = event.cancelled === true;
+            const turnMessagesSha256 = digestJson(event.messages ?? []);
             await recordBlackbox("turn.ended", event.runId, ctx, {
-                success: event.success !== false,
-                cancelled: false,
+                success: event.success === true && !cancelled,
+                cancelled,
                 error_category: event.error ? "agent_error" : undefined,
+                failure_kind: cancelled ? "cancelled" : event.error ? "agent_error" : undefined,
+                reason: event.error,
                 duration_ms: event.durationMs ?? 0,
-                messages_sha256: digestJson(event.messages ?? []),
+                messages_sha256: turnMessagesSha256,
+                turn_messages_sha256: turnMessagesSha256,
+                digest_profile: "atmem-turn-messages-canonical-json-v1",
                 messages_count: Array.isArray(event.messages) ? event.messages.length : 0,
+            }, undefined, {
+                retrievalId: cached?.retrievalId,
+                contextEventId: cached?.contextEventId,
+                contextReceiptId: cached?.contextReceiptId,
             });
         }
     });

package/dist/src/rpc-client.js

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

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": "1.0.0",
+  "version": "2.0.0",
   "commandAliases": ["memory-atmem"],
   "activation": {
     "onStartup": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-atmem",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "OpenClaw Agent Black Box and memory control-plane bridge for AtMem",
   "type": "module",
   "main": "./dist/index.js",