openclaw-memory-atmem 2.0.1 → 2.1.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==2.0.1
+python -m pip install atmem==2.1.0
 atmem openclaw install
 ```
 
-The installer pins `openclaw-memory-atmem@2.0.1`, 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.1.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

@@ -43,6 +43,19 @@ function parseConfig(raw) {
     const cfg = (raw ?? {});
     const dbPath = expandHome(String(cfg.dbPath ?? "~/.atmem/memories.db"));
     const subject = String(cfg.subject ?? "default");
+    const stringMap = (value) => value && typeof value === "object" && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => typeof item === "string" && item.trim())
+            .map(([key, item]) => [key, String(item)]))
+        : {};
+    const agentSubjects = stringMap(cfg.agentSubjects);
+    const agentWorkspaces = Object.fromEntries(Object.entries(stringMap(cfg.agentWorkspaces)).map(([key, value]) => [key, expandHome(value)]));
+    const nativeWorkspace = expandHome(String(cfg.nativeWorkspace ?? ""));
+    const nativeWorkspaces = [...new Set([
+            ...(Array.isArray(cfg.nativeWorkspaces) ? cfg.nativeWorkspaces.map((item) => expandHome(String(item))) : []),
+            ...Object.values(agentWorkspaces),
+            nativeWorkspace,
+        ].filter(Boolean))];
     const controlPlane = {
         enabled: cfg.controlPlane?.enabled === true,
         statePath: expandHome(String(cfg.controlPlane?.statePath ?? "~/.atmem/control-plane.json")),
@@ -57,8 +70,12 @@ function parseConfig(raw) {
                 : ["mcp", "--db", dbPath, "--subject", subject],
         dbPath,
         subject,
+        defaultAgentId: String(cfg.defaultAgentId ?? "main"),
+        agentSubjects,
+        agentWorkspaces,
         takeoverActive: cfg.takeoverActive === true,
-        nativeWorkspace: expandHome(String(cfg.nativeWorkspace ?? "")),
+        nativeWorkspace,
+        nativeWorkspaces,
         recall: {
             enabled: cfg.recall?.enabled !== false,
             maxRecords: Number(cfg.recall?.maxRecords ?? 3),
@@ -312,7 +329,31 @@ function register(api) {
     const inboundAttachments = new Map();
     const inboundAttachmentGeneration = new Map();
     let nextAttachmentGeneration = 0;
-    const contextIds = (ctx) => [...new Set([ctx.runId, ctx.sessionKey, ctx.sessionId].filter((value) => Boolean(value)))];
+    const agentIdFor = (ctx) => {
+        if (ctx.agentId?.trim())
+            return ctx.agentId.trim();
+        const session = ctx.sessionKey ?? ctx.sessionId ?? "";
+        const match = /^agent:([^:]+)(?::|$)/.exec(session);
+        return match?.[1] ?? cfg.defaultAgentId;
+    };
+    const subjectFor = (ctx) => {
+        const agentId = agentIdFor(ctx);
+        if (Object.keys(cfg.agentSubjects).length) {
+            const mapped = cfg.agentSubjects[agentId];
+            if (!mapped)
+                throw new Error(`unmapped OpenClaw persistent agent: ${agentId}`);
+            return mapped;
+        }
+        return cfg.subject;
+    };
+    const scopedKey = (value, ctx) => `${agentIdFor(ctx)}:${value}`;
+    const contextIds = (ctx) => [...new Set([ctx.runId, ctx.sessionKey, ctx.sessionId].filter((value) => Boolean(value)).map((value) => scopedKey(value, ctx)))];
+    const callFor = (ctx, name, args, timeoutMs = cfg.recall.timeoutMs) => {
+        const scoped = cfg.controlPlane.enabled && !Object.keys(cfg.agentSubjects).length
+            ? args
+            : { ...args, subject_id: subjectFor(ctx) };
+        return client.callTool(name, scoped, timeoutMs);
+    };
     const digestText = (value) => createHash("sha256").update(value, "utf8").digest("hex");
     const stableValue = (value) => {
         if (Array.isArray(value))
@@ -346,6 +387,8 @@ function register(api) {
             await blackboxClient.callTool("control_record_blackbox_event", {
                 event_type: eventType,
                 run_id: flightRunId(eventRunId, ctx),
+                agent_id: agentIdFor(ctx),
+                subject_id: Object.keys(cfg.agentSubjects).length ? subjectFor(ctx) : undefined,
                 session_id: ctx.sessionId ?? ctx.sessionKey,
                 tool_call_id: toolCallId,
                 turn_id: correlation.turnId ?? flightRunId(eventRunId, ctx),
@@ -382,7 +425,7 @@ function register(api) {
         const ids = contextIds(ctx);
         if (!ids.length)
             return;
-        await client.callTool("memory_stage_user_message", {
+        await callFor(ctx, "memory_stage_user_message", {
             message: text.trim(),
             source_aliases: ids,
             run_id: ctx.runId,
@@ -499,7 +542,7 @@ function register(api) {
         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 sessionKey = scopedKey(ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? "default-session", ctx);
         const pending = pendingPrompts.get(sessionKey);
         if (pending) {
             pendingPrompts.set(sessionKey, {
@@ -570,7 +613,7 @@ function register(api) {
     }, { commands: ["atmem"] });
     // L3 persona cache: rebuilt on TTL expiry and invalidated when capture
     // writes new memory, so the snapshot never lags a correction.
-    let personaCache = null;
+    const personaCaches = new Map();
     const sweep = () => {
         const now = Date.now();
         for (const [key, value] of pendingPrompts) {
@@ -582,40 +625,43 @@ function register(api) {
                 inboundAttachments.delete(key);
         }
     };
-    async function personaBlock(sessionKey) {
+    async function personaBlock(sessionKey, ctx) {
         if (!cfg.persona.enabled)
             return { block: "", recordIds: [] };
         const now = Date.now();
+        const subject = subjectFor(ctx);
+        const personaCache = personaCaches.get(subject);
         if (personaCache && now - personaCache.ts < cfg.persona.ttlSeconds * 1000) {
             return personaCache;
         }
-        const result = (await client.callTool("memory_persona", {
+        const result = (await callFor(ctx, "memory_persona", {
             session_id: sessionKey,
             max_chars: cfg.persona.maxChars,
             reference_mode: cfg.cacheAware.enabled && cfg.cacheAware.compactReferences
                 ? "compact"
                 : "full",
         }, cfg.recall.timeoutMs));
-        personaCache = {
+        const refreshed = {
             block: result?.block ?? "",
             recordIds: result?.record_ids ?? [],
             contextEventId: result?.context_event_id,
             ts: now,
         };
-        return personaCache;
+        personaCaches.set(subject, refreshed);
+        return refreshed;
     }
     // ---- auto-recall: persona + bounded, audited recall injection ---------
     api.on("before_prompt_build", async (event, ctx) => {
         const userText = event.prompt;
         if (!userText)
             return;
-        const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? "default-session";
+        const sessionKey = scopedKey(ctx.sessionKey ?? ctx.sessionId ?? "default-session", ctx);
         const takeoverGuidance = cfg.takeoverActive ? TAKEOVER_GUIDANCE : "";
         pendingPrompts.set(sessionKey, { text: userText, ts: Date.now() });
         sweep();
         if (cfg.controlPlane.enabled) {
             try {
-                const prepared = (await client.callTool("control_prepare", { query: userText, session_id: sessionKey }, cfg.recall.timeoutMs));
+                const prepared = (await callFor(ctx, "control_prepare", { query: userText, session_id: sessionKey, agent_id: agentIdFor(ctx) }, cfg.recall.timeoutMs));
                 pendingPrompts.set(sessionKey, {
                     text: userText,
                     ts: Date.now(),
@@ -687,7 +733,7 @@ function register(api) {
         let recall = "";
         let recallFailed = false;
         try {
-            const personaResult = await personaBlock(sessionKey);
+            const personaResult = await personaBlock(sessionKey, ctx);
             persona = personaResult.block;
             personaRecordIds = personaResult.recordIds;
             personaContextEventId = personaResult.contextEventId;
@@ -698,7 +744,7 @@ function register(api) {
         }
         try {
             if (cfg.recall.enabled) {
-                const result = (await client.callTool("memory_recall_block", {
+                const result = (await callFor(ctx, "memory_recall_block", {
                     query: userText,
                     session_id: sessionKey,
                     max_records: cfg.recall.maxRecords,
@@ -803,7 +849,7 @@ function register(api) {
                 ? event.derivedPaths.map((value) => digestText(String(value)))
                 : [],
         }, event.toolCallId);
-        if (!cfg.takeoverActive || !touchesNativeMemory(event, cfg.nativeWorkspace))
+        if (!cfg.takeoverActive || !cfg.nativeWorkspaces.some((workspace) => touchesNativeMemory(event, workspace)))
             return;
         const reason = "AtMem takeover blocked access to OpenClaw's frozen native memory " +
             "(MEMORY.md or memory/*). Use memory_remember for durable user facts, " +
@@ -831,20 +877,20 @@ function register(api) {
     });
     // ---- auto-capture: user turn through the pipeline, assistant as digest -
     api.on("agent_end", async (event, ctx) => {
-        const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? "default-session";
+        const sessionKey = scopedKey(ctx.sessionKey ?? ctx.sessionId ?? "default-session", ctx);
         const cached = pendingPrompts.get(sessionKey);
         pendingPrompts.delete(sessionKey);
         const userText = cached?.text?.replace(INJECT_RE, "").trim();
         try {
             if (cfg.takeoverActive) {
-                await client.callTool("memory_clear_user_message", { source_aliases: contextIds(ctx) }, cfg.recall.timeoutMs);
+                await callFor(ctx, "memory_clear_user_message", { source_aliases: contextIds(ctx) }, cfg.recall.timeoutMs);
             }
             if (cfg.controlPlane.enabled) {
                 if (cached?.exposureId) {
-                    await client.callTool("control_exposure_shown", { exposure_id: cached.exposureId }, cfg.recall.timeoutMs);
+                    await callFor(ctx, "control_exposure_shown", { exposure_id: cached.exposureId }, cfg.recall.timeoutMs);
                 }
                 if (event.success !== false) {
-                    await client.callTool("control_sync_openclaw_memory", {}, cfg.recall.timeoutMs);
+                    await callFor(ctx, "control_sync_openclaw_memory", {}, cfg.recall.timeoutMs);
                 }
                 return;
             }
@@ -857,7 +903,7 @@ function register(api) {
                     const responseText = messageText(message.content);
                     if (responseText) {
                         const assistantVisibleTextSha256 = cached.assistantVisibleTextSha256 ?? digestText(responseText);
-                        await client.callTool("memory_log_action", {
+                        await callFor(ctx, "memory_log_action", {
                             action_type: "agent.response_after_memory",
                             payload: {
                                 response_sha256: assistantVisibleTextSha256,
@@ -882,12 +928,12 @@ function register(api) {
                 !cfg.takeoverActive &&
                 event.success !== false &&
                 userText) {
-                await client.callTool("memory_capture", {
+                await callFor(ctx, "memory_capture", {
                     role: "user",
                     content: userText,
                     session_id: sessionKey,
                 });
-                personaCache = null; // new memory may change the persona
+                personaCaches.delete(subjectFor(ctx)); // new memory may change the persona
             }
             if (cfg.capture.enabled &&
                 !cfg.takeoverActive &&
@@ -899,7 +945,7 @@ function register(api) {
                     if (message?.role === "assistant") {
                         const text = messageText(message.content);
                         if (text) {
-                            await client.callTool("memory_capture", {
+                            await callFor(ctx, "memory_capture", {
                                 role: "assistant",
                                 content: text,
                                 session_id: sessionKey,
@@ -1005,9 +1051,9 @@ function register(api) {
                     additionalProperties: false,
                 },
                 async execute(toolCallId, params) {
-                    const sessionKey = toolCtx.sessionKey ?? toolCtx.sessionId;
-                    const sourceAliases = [toolCtx.sessionKey, toolCtx.sessionId]
-                        .filter((value) => Boolean(value));
+                    const rawSessionKey = toolCtx.sessionKey ?? toolCtx.sessionId;
+                    const sessionKey = rawSessionKey ? scopedKey(rawSessionKey, toolCtx) : undefined;
+                    const sourceAliases = contextIds(toolCtx);
                     if (!sessionKey || !sourceAliases.length) {
                         throw new Error("no current authenticated user message is available; memory was not stored");
                     }
@@ -1019,7 +1065,7 @@ function register(api) {
                             .filter(Boolean)
                             .join(":") ??
                         "openclaw-agent";
-                    const result = (await client.callTool("memory_remember", {
+                    const result = (await callFor(toolCtx, "memory_remember", {
                         source_aliases: sourceAliases,
                         interpreted_fact: fact,
                         interpreted_fact_key: params.factKey,
@@ -1032,7 +1078,7 @@ function register(api) {
                     const duplicateId = result.duplicate_ids?.[0];
                     const stored = Boolean(record || duplicateId);
                     if (stored) {
-                        personaCache = null;
+                        personaCaches.delete(subjectFor(toolCtx));
                     }
                     return {
                         content: [{
@@ -1055,7 +1101,7 @@ function register(api) {
         // is disabled. Existing agent prompts and workflows can keep using the
         // same tool names; only the governed storage/retrieval implementation
         // changes underneath them.
-        api.registerTool({
+        api.registerTool((toolCtx) => ({
             name: "memory_search",
             label: "Memory Search",
             description: "Search governed AtMem long-term memory. Compatible with OpenClaw's " +
@@ -1092,7 +1138,7 @@ function register(api) {
                 }
                 const sessionId = `openclaw-memory-search:${toolCallId}`;
                 const maxResults = Math.min(Math.max(Number(params.maxResults) || 6, 1), 20);
-                const records = (await client.callTool("memory_recall", {
+                const records = (await callFor(toolCtx, "memory_recall", {
                     query: String(params.query ?? ""),
                     session_id: sessionId,
                     limit: maxResults,
@@ -1128,8 +1174,8 @@ function register(api) {
                     details: { count: results.length, corpus, sessionId },
                 };
             },
-        }, { name: "memory_search" });
-        api.registerTool({
+        }), { name: "memory_search" });
+        api.registerTool((toolCtx) => ({
             name: "memory_get",
             label: "Memory Get",
             description: "Read one exact governed AtMem record returned by memory_search. " +
@@ -1150,7 +1196,7 @@ function register(api) {
                 const recordId = recordIdFromPath(lookup);
                 if (!recordId) {
                     const sessionId = `openclaw-memory-get:${toolCallId}`;
-                    const sourceResult = (await client.callTool("memory_get_source", {
+                    const sourceResult = (await callFor(toolCtx, "memory_get_source", {
                         path: lookup,
                         session_id: sessionId,
                     }));
@@ -1188,7 +1234,7 @@ function register(api) {
                     };
                 }
                 const sessionId = `openclaw-memory-get:${toolCallId}`;
-                const result = (await client.callTool("memory_get_record", {
+                const result = (await callFor(toolCtx, "memory_get_record", {
                     record_id: recordId,
                     session_id: sessionId,
                 }));
@@ -1211,8 +1257,8 @@ function register(api) {
                     details: { found: Boolean(result?.record), sessionId },
                 };
             },
-        }, { name: "memory_get" });
-        api.registerTool({
+        }), { name: "memory_get" });
+        api.registerTool((toolCtx) => ({
             name: "atmem_search",
             label: "Memory Search (atmem)",
             description: "Search the user's long-term auditable memory. Use when you need " +
@@ -1228,7 +1274,7 @@ function register(api) {
             },
             async execute(toolCallId, params) {
                 const sessionId = `openclaw-tool:${toolCallId}`;
-                const records = (await client.callTool("memory_recall", {
+                const records = (await callFor(toolCtx, "memory_recall", {
                     query: String(params.query ?? ""),
                     session_id: sessionId,
                     limit: Math.min(Math.max(Number(params.limit) || 5, 1), 20),
@@ -1241,8 +1287,8 @@ function register(api) {
                     details: { count: records.length, sessionId },
                 };
             },
-        }, { name: "atmem_search" });
-        api.registerTool({
+        }), { name: "atmem_search" });
+        api.registerTool((toolCtx) => ({
             name: "atmem_forget",
             label: "Memory Forget (atmem)",
             description: "Delete the user's memories matching their request — only call when " +
@@ -1261,13 +1307,13 @@ function register(api) {
             },
             async execute(toolCallId, params) {
                 const sessionId = `openclaw-tool:${toolCallId}`;
-                const result = (await client.callTool("memory_forget", {
+                const result = (await callFor(toolCtx, "memory_forget", {
                     utterance: String(params.utterance ?? ""),
                     session_id: sessionId,
                     turn_id: toolCallId,
                 }));
                 if (result.deleted)
-                    personaCache = null;
+                    personaCaches.delete(subjectFor(toolCtx));
                 const text = result.deleted
                     ? `Deleted ${result.record_ids.length} memorie(s). Receipt: ${JSON.stringify(result.receipt)}`
                     : "No matching memories found to delete.";
@@ -1276,7 +1322,7 @@ function register(api) {
                     details: { deleted: result.deleted, sessionId },
                 };
             },
-        }, { name: "atmem_forget" });
+        }), { name: "atmem_forget" });
         api.registerTool((toolCtx) => ({
             name: "atmem_observe",
             label: "Media Observation (atmem)",
@@ -1392,7 +1438,7 @@ function register(api) {
                     if (suppliedSegment[key] !== undefined)
                         segment[key] = suppliedSegment[key];
                 }
-                const result = (await client.callTool("memory_observe", {
+                const result = (await callFor(toolCtx, "memory_observe", {
                     text: String(params.text ?? ""),
                     modality: requestedModality,
                     media_sha256: mediaSha256,
@@ -1426,7 +1472,7 @@ function register(api) {
                 };
             },
         }), { name: "atmem_observe" });
-        api.registerTool({
+        api.registerTool((toolCtx) => ({
             name: "atmem_forget_artifact",
             label: "Forget Media Artifact (atmem)",
             description: "Only when the user explicitly requests deletion, purge all AtMem " +
@@ -1448,14 +1494,14 @@ function register(api) {
             },
             async execute(toolCallId, params) {
                 const sessionId = `openclaw-tool:${toolCallId}`;
-                const result = (await client.callTool("memory_forget_artifact", {
+                const result = (await callFor(toolCtx, "memory_forget_artifact", {
                     media_sha256: String(params.media_sha256 ?? ""),
                     artifact_id: params.artifact_id,
                     session_id: sessionId,
                     turn_id: toolCallId,
                 }));
                 if (result.deleted)
-                    personaCache = null;
+                    personaCaches.delete(subjectFor(toolCtx));
                 const text = result.deleted
                     ? `Purged ${result.record_ids.length} derived memorie(s). Receipt: ${JSON.stringify(result.receipt)}`
                     : "No active AtMem artifact matched that exact digest.";
@@ -1464,7 +1510,7 @@ function register(api) {
                     details: { deleted: result.deleted, sessionId },
                 };
             },
-        }, { name: "atmem_forget_artifact" });
+        }), { name: "atmem_forget_artifact" });
     }
     api.logger.info(`${TAG} registered (db=${cfg.dbPath}, subject=${cfg.subject}, ` +
         `recall=${cfg.recall.enabled}, capture=${cfg.capture.enabled}, ` +

package/dist/src/rpc-client.js

@@ -128,7 +128,7 @@ export class AtmemClient {
             capabilities: {},
             clientInfo: {
                 name: "openclaw-memory-atmem",
-                version: "2.0.1",
+                version: "2.1.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": "2.0.1",
+  "version": "2.1.0",
   "commandAliases": ["memory-atmem"],
   "activation": {
     "onStartup": true
@@ -42,6 +42,21 @@
         "default": "default",
         "description": "Subject id used for all memory operations (single-user assistant)"
       },
+      "defaultAgentId": {
+        "type": "string",
+        "default": "main",
+        "description": "Persistent OpenClaw agent used when a legacy hook does not expose an agent id. Managed by AtMem."
+      },
+      "agentSubjects": {
+        "type": "object",
+        "additionalProperties": { "type": "string" },
+        "description": "Persistent-agent to governed-memory-subject map. Agents sharing an exact workspace intentionally share a subject."
+      },
+      "agentWorkspaces": {
+        "type": "object",
+        "additionalProperties": { "type": "string" },
+        "description": "Persistent-agent to canonical workspace map. Managed by AtMem."
+      },
       "takeoverActive": {
         "type": "boolean",
         "default": false,
@@ -51,6 +66,11 @@
         "type": "string",
         "description": "Absolute OpenClaw workspace path protected during verified takeover. Set by `atmem control activate`; do not configure manually."
       },
+      "nativeWorkspaces": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "All OpenClaw workspaces protected during takeover, including separate and nested persistent-agent workspaces."
+      },
       "recall": {
         "type": "object",
         "description": "Auto-recall injection before each prompt",

package/package.json

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