Summary

Adds automatic per-agent memory namespace isolation for OpenClaw multi-agent setups. Each agent gets its own memory namespace derived from the session key, ensuring no cross-contamination between agents while maintaining full backward compatibility for single-agent users.

Problem

The current plugin treats all agents as a single user — every agent reads and writes to the same userId namespace. In multi-agent setups (e.g. researcher + coder + planner), this means:

• Agents see each other's memories, causing confusion and irrelevant context
• No way to query or manage a specific agent's memories
• Tools (memory_search, memory_store, etc.) have no awareness of which agent is calling them

Solution

Per-agent namespace isolation

Session keys follow the pattern agent:<agentId>:<uuid>. Four helper functions parse and route to collision-safe namespaces:

Session key: "agent:researcher:abc-123"
→ extractAgentId() → "researcher"
→ effectiveUserId() → "utkarsh:agent:researcher"

Session key: undefined | "plain-uuid" | "agent:main:abc-123"
→ extractAgentId() → undefined
→ effectiveUserId() → "utkarsh" (unchanged — backward compatible)

The ${userId}:agent:${agentId} format prevents collisions (e.g. a user named "researcher" won't clash with an agent named "researcher").

Tool-level agent support

All 4 tools gain an agentId parameter for explicit cross-agent operations:

• memory_search — search a specific agent's memories
• memory_store — store under a specific agent's namespace
• memory_list — list a specific agent's memories
• memory_forget — delete from a specific agent's namespace

Priority: agentId > userId > session-derived > configured default.

CLI enhancements

• openclaw mem0 search "query" --agent researcher — search a specific agent's namespace
• openclaw mem0 stats --agent researcher — view stats for a specific agent

Hook updates

• Auto-recall: passes sessionKey through buildSearchOptions so recalled memories are agent-scoped
• Auto-capture: passes sessionKey through buildAddOptions so captured memories go to the correct namespace

Backward Compatibility

Zero breaking changes. Single-agent users are unaffected because their session keys are either:

• undefined → falls back to cfg.userId
• A plain UUID → no agent: prefix → falls back to cfg.userId
• agent:main:<uuid> → "main" is explicitly treated as the primary session → falls back to cfg.userId

All paths resolve to the same cfg.userId they always did.

Testing

Key tests verified:

• Agent Alpha stores/retrieves its own memories (Python preference)
• Agent Beta stores/retrieves its own memories (Rust preference)
• Main user stores/retrieves its own memories (TypeScript preference)
• Alpha does NOT see Beta's memories (cross-isolation)
• Beta does NOT see Alpha's memories (cross-isolation)
• Main user does NOT see agent memories (cross-isolation)

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules
• I have checked my code and corrected any misspellings

Related

• PR feat(openclaw): per-agent memory isolation via sessionKey #4112 — Earlier attempt at per-agent isolation. This PR supersedes it due to several issues found during review:
  • Namespace collision bug: effectiveUserId() returns the raw agentId (e.g. "researcher") instead of a namespaced ${userId}:agent:${agentId}. This means an agent named "researcher" collides with a real user named "researcher", and agents with the same name across different users share memories.
  • Tools not agent-aware: Only the auto-recall/capture hooks are isolated — the 4 memory tools (memory_search, memory_store, memory_list, memory_forget) still route to the global cfg.userId, bypassing isolation entirely for explicit tool calls.
  • No CLI support: No --agent flag on openclaw mem0 search or openclaw mem0 stats, so operators cannot inspect per-agent memories.
  • Untestable: Helpers are closures inside register() with no way to unit test. This PR exports them as standalone functions with 21 unit tests.
  • No documentation: README not updated with per-agent isolation usage.

Maintainer Checklist

• closes feat: Per-agent memory isolation for openclaw-mem0 plugin #3998 , OpenClaw plugin: Support per-agent memory configuration in multi-agent setups #4126
• Made sure Checks passed