The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.
Python agentic-memoryagentic-memory-systemagentsaiai-agentschatgptgenaillmlong-term-memorymemorymemory-managementpythonragstate-management
feat(openclaw): add per-agent memory isolation for multi-agent setups (#4245)
Utkarsh3ffe43f99fd8
diff --git a/openclaw/README.md b/openclaw/README.mdindex 3f939d9de..ef2f79dbf 100644--- a/openclaw/README.md+++ b/openclaw/README.md@@ -30,6 +30,26 @@ The agent tools (`memory_search`, `memory_list`) accept a `scope` parameter (`"sAll new parameters are optional and backward-compatible — existing configurations work without changes.+### Per-agent memory isolation++In multi-agent setups, each agent automatically gets its own memory namespace. Session keys following the pattern `agent:<agentId>:<uuid>` are parsed to derive isolated namespaces (`${userId}:agent:${agentId}`). Single-agent deployments are unaffected — plain session keys and `agent:main:*` keys resolve to the configured `userId`.++**How it works:**++- The agent's session key is inspected on every recall/capture cycle+- If the key matches `agent:<name>:<uuid>`, memories are stored under `userId:agent:<name>`+- Different agents never see each other's memories unless explicitly queried++**Explicit cross-agent queries:**++All memory tools (`memory_search`, `memory_store`, `memory_list`, `memory_forget`) accept an optional `agentId` parameter to query another agent's namespace:++```+memory_search({ query: "user's tech stack", agentId: "researcher" })+```++Resolution priority: explicit `agentId` > explicit `userId` > session-derived > configured default.+## Setup```bash@@ -87,11 +107,11 @@ The agent gets five tools it can call during conversations:| Tool | Description ||------|-------------|-| `memory_search` | Search memories by natural language |-| `memory_list` | List all stored memories for a user |-| `memory_store` | Explicitly save a fact |+| `memory_search` | Search memories by natural language. Optional `agentId` to scope to a specific agent. |+| `memory_list` | List all stored memories for a user. Optional `agentId` to scope to a specific agent. |+| `memory_store` | Explicitly save a fact. Optional `agentId` to store under a specific agent's namespace. || `memory_get` | Retrieve a memory by ID |-| `memory_forget` | Delete by ID or by query |+| `memory_forget` | Delete by ID or by query. Optional `agentId` to scope deletion to a specific agent. |## CLI@@ -107,6 +127,12 @@ openclaw mem0 search "what languages does the user know" --scope session# Statsopenclaw mem0 stats++# Search a specific agent's memories+openclaw mem0 search "user preferences" --agent researcher++# Stats for a specific agent+openclaw mem0 stats --agent researcher```## Optionsdiff --git a/openclaw/index.test.ts b/openclaw/index.test.tsnew file mode 100644index 000000000..b5151e4ff--- /dev/null+++ b/openclaw/index.test.ts@@ -0,0 +1,165 @@+/**+ * Regression tests for per-agent memory isolation helpers.+ *+ * Addresses review feedback: targeted coverage for auth/session state,+ * malformed input, and the resolveUserId priority chain.+ */+import { describe, it, expect } from "vitest";+import {+ extractAgentId,+ effectiveUserId,+ agentUserId,+ resolveUserId,+} from "./index.ts";++// ---------------------------------------------------------------------------+// extractAgentId+// ---------------------------------------------------------------------------+describe("extractAgentId", () => {+ it("returns agentId from a well-formed session key", () => {+ expect(extractAgentId("agent:researcher:550e8400-e29b")).toBe("researcher");+ });++ it("returns undefined for the 'main' sentinel", () => {+ expect(extractAgentId("agent:main:abc-123")).toBeUndefined();+ });++ it("returns undefined for undefined/null/empty input", () => {+ expect(extractAgentId(undefined)).toBeUndefined();+ expect(extractAgentId("")).toBeUndefined();+ });++ it("returns undefined for non-agent session keys", () => {+ expect(extractAgentId("user:alice:xyz")).toBeUndefined();+ expect(extractAgentId("some-random-uuid")).toBeUndefined();+ });++ it("handles keys with extra colons after the UUID portion", () => {+ expect(extractAgentId("agent:beta:uuid:extra:stuff")).toBe("beta");+ });++ it("returns undefined when agentId segment is empty", () => {+ // pattern: agent::<uuid> — empty agentId+ expect(extractAgentId("agent::some-uuid")).toBeUndefined();+ });++ it("returns undefined when key is only 'agent:' with no trailing colon", () => {+ expect(extractAgentId("agent:")).toBeUndefined();+ });++ it("is case-sensitive (Agent != agent)", () => {+ expect(extractAgentId("Agent:researcher:uuid")).toBeUndefined();+ });++ it("handles whitespace-only agentId as truthy string", () => {+ // " " is a non-empty match — returned as-is (validation is caller's job)+ expect(extractAgentId("agent: :uuid")).toBe(" ");+ });+});++// ---------------------------------------------------------------------------+// effectiveUserId+// ---------------------------------------------------------------------------+describe("effectiveUserId", () => {+ const base = "alice";++ it("returns base userId when sessionKey is undefined", () => {+ expect(effectiveUserId(base)).toBe("alice");+ expect(effectiveUserId(base, undefined)).toBe("alice");+ });++ it("returns namespaced userId for agent session keys", () => {+ expect(effectiveUserId(base, "agent:researcher:uuid-1")).toBe(+ "alice:agent:researcher",+ );+ });++ it("falls back to base for 'main' agent sessions", () => {+ expect(effectiveUserId(base, "agent:main:uuid-2")).toBe("alice");+ });++ it("falls back to base for non-agent session keys", () => {+ expect(effectiveUserId(base, "plain-session-id")).toBe("alice");+ });+});++// ---------------------------------------------------------------------------+// agentUserId+// ---------------------------------------------------------------------------+describe("agentUserId", () => {+ it("produces the correct namespaced format", () => {+ expect(agentUserId("alice", "researcher")).toBe("alice:agent:researcher");+ });++ it("handles empty agentId (caller is responsible for validation)", () => {+ expect(agentUserId("alice", "")).toBe("alice:agent:");+ });+});++// ---------------------------------------------------------------------------+// resolveUserId — priority chain+// ---------------------------------------------------------------------------+describe("resolveUserId", () => {+ const base = "alice";++ it("prefers explicit agentId over everything else", () => {+ expect(+ resolveUserId(+ base,+ { agentId: "researcher", userId: "bob" },+ "agent:beta:uuid",+ ),+ ).toBe("alice:agent:researcher");+ });++ it("uses explicit userId when agentId is absent", () => {+ expect(+ resolveUserId(base, { userId: "bob" }, "agent:beta:uuid"),+ ).toBe("bob");+ });++ it("derives from session key when both agentId and userId are absent", () => {+ expect(+ resolveUserId(base, {}, "agent:gamma:uuid"),+ ).toBe("alice:agent:gamma");+ });++ it("falls back to base userId when nothing else is provided", () => {+ expect(resolveUserId(base, {})).toBe("alice");+ expect(resolveUserId(base, {}, undefined)).toBe("alice");+ });++ it("ignores empty-string agentId (falsy)", () => {+ expect(resolveUserId(base, { agentId: "" })).toBe("alice");+ });++ it("ignores empty-string userId (falsy)", () => {+ expect(resolveUserId(base, { userId: "" })).toBe("alice");+ });+});++// ---------------------------------------------------------------------------+// Cross-agent isolation sanity checks+// ---------------------------------------------------------------------------+describe("multi-agent isolation", () => {+ const base = "user-42";++ it("different agents get different namespaces", () => {+ const alphaId = effectiveUserId(base, "agent:alpha:uuid-a");+ const betaId = effectiveUserId(base, "agent:beta:uuid-b");+ expect(alphaId).not.toBe(betaId);+ expect(alphaId).toBe("user-42:agent:alpha");+ expect(betaId).toBe("user-42:agent:beta");+ });++ it("same agent across sessions yields the same namespace", () => {+ const s1 = effectiveUserId(base, "agent:alpha:session-1");+ const s2 = effectiveUserId(base, "agent:alpha:session-2");+ expect(s1).toBe(s2);+ });++ it("main session shares the base namespace (no isolation)", () => {+ const mainId = effectiveUserId(base, "agent:main:uuid-m");+ expect(mainId).toBe(base);+ });+});diff --git a/openclaw/index.ts b/openclaw/index.tsindex 1879edba2..74c9d4c2b 100644--- a/openclaw/index.ts+++ b/openclaw/index.ts@@ -10,6 +10,8 @@* - Short-term (session-scoped) and long-term (user-scoped) memory* - Auto-recall: injects relevant memories (both scopes) before each agent turn* - Auto-capture: stores key facts scoped to the current session after each agent turn+ * - Per-agent isolation: multi-agent setups write/read from separate userId namespaces+ * automatically via sessionKey routing (zero breaking changes for single-agent setups)* - CLI: openclaw mem0 search, openclaw mem0 stats* - Dual mode: platform or open-source (self-hosted)*/@@ -605,6 +607,50 @@ function categoriesToArray(return Object.entries(cats).map(([key, value]) => ({ [key]: value }));}+// ============================================================================+// Per-agent isolation helpers (exported for testability)+// ============================================================================++/**+ * Parse an agent ID from a session key following the pattern `agent:<agentId>:<uuid>`.+ * Returns undefined for non-agent sessions, the "main" sentinel, or malformed keys.+ */+export function extractAgentId(sessionKey: string | undefined): string | undefined {+ if (!sessionKey) return undefined;+ const match = sessionKey.match(/^agent:([^:]+):/);+ const agentId = match?.[1];+ // "main" is the primary session — fall back to configured userId+ if (!agentId || agentId === "main") return undefined;+ return agentId;+}++/**+ * Derive the effective user_id from a session key, namespacing per-agent.+ * Falls back to baseUserId when the session is not agent-scoped.+ */+export function effectiveUserId(baseUserId: string, sessionKey?: string): string {+ const agentId = extractAgentId(sessionKey);+ return agentId ? `${baseUserId}:agent:${agentId}` : baseUserId;+}++/** Build a user_id for an explicit agentId (e.g. from tool params). */+export function agentUserId(baseUserId: string, agentId: string): string {+ return `${baseUserId}:agent:${agentId}`;+}++/**+ * Resolve user_id with priority: explicit agentId > explicit userId > session-derived > configured.+ */+export function resolveUserId(+ baseUserId: string,+ opts: { agentId?: string; userId?: string },+ currentSessionId?: string,+): string {+ if (opts.agentId) return agentUserId(baseUserId, opts.agentId);+ if (opts.userId) return opts.userId;+ return effectiveUserId(baseUserId, currentSessionId);+}+// ============================================================================// Plugin Definition// ============================================================================@@ -624,14 +670,23 @@ const memoryPlugin = {// Track current session ID for tool-level session scopinglet currentSessionId: string | undefined;+ // ========================================================================+ // Per-agent isolation helpers (thin wrappers around exported functions)+ // ========================================================================+ const _effectiveUserId = (sessionKey?: string) =>+ effectiveUserId(cfg.userId, sessionKey);+ const _agentUserId = (id: string) => agentUserId(cfg.userId, id);+ const _resolveUserId = (opts: { agentId?: string; userId?: string }) =>+ resolveUserId(cfg.userId, opts, currentSessionId);+api.logger.info(`openclaw-mem0: registered (mode: ${cfg.mode}, user: ${cfg.userId}, graph: ${cfg.enableGraph}, autoRecall: ${cfg.autoRecall}, autoCapture: ${cfg.autoCapture})`,);// Helper: build add options- function buildAddOptions(userIdOverride?: string, runId?: string): AddOptions {+ function buildAddOptions(userIdOverride?: string, runId?: string, sessionKey?: string): AddOptions {const opts: AddOptions = {- user_id: userIdOverride || cfg.userId,+ user_id: userIdOverride || _effectiveUserId(sessionKey),source: "OPENCLAW",};if (runId) opts.run_id = runId;@@ -649,9 +704,10 @@ const memoryPlugin = {userIdOverride?: string,limit?: number,runId?: string,+ sessionKey?: string,): SearchOptions {const opts: SearchOptions = {- user_id: userIdOverride || cfg.userId,+ user_id: userIdOverride || _effectiveUserId(sessionKey),top_k: limit ?? cfg.topK,limit: limit ?? cfg.topK,threshold: cfg.searchThreshold,@@ -686,6 +742,12 @@ const memoryPlugin = {"User ID to scope search (default: configured userId)",}),),+ agentId: Type.Optional(+ Type.String({+ description:+ "Agent ID to search memories for a specific agent (e.g. \"researcher\"). Overrides userId.",+ }),+ ),scope: Type.Optional(Type.Union([Type.Literal("session"),@@ -698,39 +760,41 @@ const memoryPlugin = {),}),async execute(_toolCallId, params) {- const { query, limit, userId, scope = "all" } = params as {+ const { query, limit, userId, agentId, scope = "all" } = params as {query: string;limit?: number;userId?: string;+ agentId?: string;scope?: "session" | "long-term" | "all";};try {let results: MemoryItem[] = [];+ const uid = _resolveUserId({ agentId, userId });if (scope === "session") {if (currentSessionId) {results = await provider.search(query,- buildSearchOptions(userId, limit, currentSessionId),+ buildSearchOptions(uid, limit, currentSessionId),);}} else if (scope === "long-term") {results = await provider.search(query,- buildSearchOptions(userId, limit),+ buildSearchOptions(uid, limit),);} else {// "all" — search both scopes and combineconst longTermResults = await provider.search(query,- buildSearchOptions(userId, limit),+ buildSearchOptions(uid, limit),);let sessionResults: MemoryItem[] = [];if (currentSessionId) {sessionResults = await provider.search(query,- buildSearchOptions(userId, limit, currentSessionId),+ buildSearchOptions(uid, limit, currentSessionId),);}// Deduplicate by ID, preferring long-term@@ -803,6 +867,12 @@ const memoryPlugin = {description: "User ID to scope this memory",}),),+ agentId: Type.Optional(+ Type.String({+ description:+ "Agent ID to store memory under a specific agent's namespace (e.g. \"researcher\"). Overrides userId.",+ }),+ ),metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {description: "Optional metadata to attach to this memory",@@ -816,18 +886,20 @@ const memoryPlugin = {),}),async execute(_toolCallId, params) {- const { text, userId, longTerm = true } = params as {+ const { text, userId, agentId, longTerm = true } = params as {text: string;userId?: string;+ agentId?: string;metadata?: Record<string, unknown>;longTerm?: boolean;};try {+ const uid = _resolveUserId({ agentId, userId });const runId = !longTerm && currentSessionId ? currentSessionId : undefined;const result = await provider.add([{ role: "user", content: text }],- buildAddOptions(userId, runId),+ buildAddOptions(uid, runId, currentSessionId),);const added =@@ -919,7 +991,7 @@ const memoryPlugin = {name: "memory_list",label: "Memory List",description:- "List all stored memories for a user. Use this when you want to see everything that's been remembered, rather than searching for something specific.",+ "List all stored memories for a user or agent. Use this when you want to see everything that's been remembered, rather than searching for something specific.",parameters: Type.Object({userId: Type.Optional(Type.String({@@ -927,6 +999,12 @@ const memoryPlugin = {"User ID to list memories for (default: configured userId)",}),),+ agentId: Type.Optional(+ Type.String({+ description:+ "Agent ID to list memories for a specific agent (e.g. \"researcher\"). Overrides userId.",+ }),+ ),scope: Type.Optional(Type.Union([Type.Literal("session"),@@ -939,11 +1017,11 @@ const memoryPlugin = {),}),async execute(_toolCallId, params) {- const { userId, scope = "all" } = params as { userId?: string; scope?: "session" | "long-term" | "all" };+ const { userId, agentId, scope = "all" } = params as { userId?: string; agentId?: string; scope?: "session" | "long-term" | "all" };try {let memories: MemoryItem[] = [];- const uid = userId || cfg.userId;+ const uid = _resolveUserId({ agentId, userId });if (scope === "session") {if (currentSessionId) {@@ -1026,7 +1104,7 @@ const memoryPlugin = {name: "memory_forget",label: "Memory Forget",description:- "Delete memories from Mem0. Provide a specific memoryId to delete directly, or a query to search and delete matching memories. GDPR-compliant.",+ "Delete memories from Mem0. Provide a specific memoryId to delete directly, or a query to search and delete matching memories. Supports agent-scoped deletion. GDPR-compliant.",parameters: Type.Object({query: Type.Optional(Type.String({@@ -1036,11 +1114,18 @@ const memoryPlugin = {memoryId: Type.Optional(Type.String({ description: "Specific memory ID to delete" }),),+ agentId: Type.Optional(+ Type.String({+ description:+ "Agent ID to scope deletion to a specific agent's memories (e.g. \"researcher\").",+ }),+ ),}),async execute(_toolCallId, params) {- const { query, memoryId } = params as {+ const { query, memoryId, agentId } = params as {query?: string;memoryId?: string;+ agentId?: string;};try {@@ -1055,9 +1140,10 @@ const memoryPlugin = {}if (query) {+ const uid = _resolveUserId({ agentId });const results = await provider.search(query,- buildSearchOptions(undefined, 5),+ buildSearchOptions(uid, 5),);if (!results || results.length === 0) {@@ -1148,10 +1234,12 @@ const memoryPlugin = {.argument("<query>", "Search query").option("--limit <n>", "Max results", String(cfg.topK)).option("--scope <scope>", 'Memory scope: "session", "long-term", or "all"', "all")- .action(async (query: string, opts: { limit: string; scope: string }) => {+ .option("--agent <agentId>", "Search a specific agent's memory namespace")+ .action(async (query: string, opts: { limit: string; scope: string; agent?: string }) => {try {const limit = parseInt(opts.limit, 10);const scope = opts.scope as "session" | "long-term" | "all";+ const uid = opts.agent ? _agentUserId(opts.agent) : _effectiveUserId(currentSessionId);let allResults: MemoryItem[] = [];@@ -1159,7 +1247,7 @@ const memoryPlugin = {if (currentSessionId) {const sessionResults = await provider.search(query,- buildSearchOptions(undefined, limit, currentSessionId),+ buildSearchOptions(uid, limit, currentSessionId),);if (sessionResults?.length) {allResults.push(...sessionResults.map((r) => ({ ...r, _scope: "session" as const })));@@ -1173,7 +1261,7 @@ const memoryPlugin = {if (scope === "long-term" || scope === "all") {const longTermResults = await provider.search(query,- buildSearchOptions(undefined, limit),+ buildSearchOptions(uid, limit),);if (longTermResults?.length) {allResults.push(...longTermResults.map((r) => ({ ...r, _scope: "long-term" as const })));@@ -1212,14 +1300,16 @@ const memoryPlugin = {mem0.command("stats").description("Show memory statistics from Mem0")- .action(async () => {+ .option("--agent <agentId>", "Show stats for a specific agent")+ .action(async (opts: { agent?: string }) => {try {+ const uid = opts.agent ? _agentUserId(opts.agent) : cfg.userId;const memories = await provider.getAll({- user_id: cfg.userId,+ user_id: uid,source: "OPENCLAW",});console.log(`Mode: ${cfg.mode}`);- console.log(`User: ${cfg.userId}`);+ console.log(`User: ${uid}${opts.agent ? ` (agent: ${opts.agent})` : ""}`);console.log(`Total memories: ${Array.isArray(memories) ? memories.length : "unknown"}`,);@@ -1249,10 +1339,10 @@ const memoryPlugin = {if (sessionId) currentSessionId = sessionId;try {- // Search long-term memories (user-scoped)+ // Search long-term memories (user-scoped, isolated per agent)const longTermResults = await provider.search(event.prompt,- buildSearchOptions(),+ buildSearchOptions(undefined, undefined, undefined, sessionId),);// Search session memories (session-scoped) if we have a session ID@@ -1260,7 +1350,7 @@ const memoryPlugin = {if (currentSessionId) {sessionResults = await provider.search(event.prompt,- buildSearchOptions(undefined, undefined, currentSessionId),+ buildSearchOptions(undefined, undefined, currentSessionId, sessionId),);}@@ -1365,7 +1455,7 @@ const memoryPlugin = {if (formattedMessages.length === 0) return;- const addOpts = buildAddOptions(undefined, currentSessionId);+ const addOpts = buildAddOptions(undefined, currentSessionId, sessionId);const result = await provider.add(formattedMessages,addOpts,diff --git a/openclaw/package.json b/openclaw/package.jsonindex 58eb5f8f6..9ee6e9947 100644--- a/openclaw/package.json+++ b/openclaw/package.json@@ -11,6 +11,9 @@"mem0","long-term-memory"],+ "scripts": {+ "test": "vitest run"+ },"dependencies": {"@sinclair/typebox": "0.34.47","mem0ai": "^2.2.1"@@ -19,5 +22,8 @@"extensions": ["./index.ts"]+ },+ "devDependencies": {+ "vitest": "^4.0.18"}-}\ No newline at end of file+}