Description

Problem

The OpenClaw mem0 plugin was suffering from poor extraction and recall quality in production. Analysis of real-world conversation data (~29K events) revealed compounding issues:

1. Noise pollution in extraction pipeline — System messages (heartbeats, timestamps, routing logs), single-word acknowledgments, and pre-compaction flushes were being sent to Mem0 for extraction, wasting API calls and diluting memory quality.
2. Generic assistant responses diluting signal — Boilerplate assistant replies were being included in extraction context, causing Mem0 to extract non-durable pleasantries instead of actual user facts.
3. Weak recall precision — No client-side threshold filtering or dynamic scoring meant irrelevant memories were injected into agent context.
4. Extraction instructions lacked specificity — Custom instructions were too generic, leading to verbose, non-temporal, intent-focused memories.
5. No trigger filtering — Cron jobs and heartbeats polluted memory with system-generated noise.
6. No multi-agent awareness — Subagent sessions had no memory isolation, causing namespace collisions and orphaned memories.
7. No user attribution in recall — Recalled memories lacked user identity context, risking misattribution.
8. Subagent hallucination — Ephemeral subagent UUIDs created empty namespaces for recall and orphaned namespaces for capture.
9. SQLite init failures in OSS mode — Native SQLite binding resolution fails under jiti, crashing the plugin with no recovery path.
10. Session race condition — Shared mutable currentSessionId variable caused cross-session data leaks when multiple sessions ran concurrently.

Solution

Noise filtering pipeline (isNoiseMessage → isGenericAssistantMessage → stripNoiseFromContent → truncateMessage):

• Pattern-based detection for heartbeats, timestamps, single-word acks, system routing messages, and post-compaction audit logs
• Generic assistant response detection (short boilerplate acknowledgments, help offers, and signaling phrases)
• Inline noise stripping: removes embedded timestamps, system prefixes, and routing lines from otherwise useful messages
• Message truncation to 2000 chars to avoid sending excessive context

Improved recall pipeline:

• Client-side threshold filtering raised to 0.6 for auto-recall (stricter than explicit tool searches at 0.5)
• Dynamic thresholding: drop memories scoring < 50% of top result's score
• Broad recall for short/new-session prompts to provide better initial context (cold-start broadening)

Rewritten custom extraction instructions:

• Temporal anchoring: memories are prefixed with dates for time-aware recall
• Outcome-over-intent: store what happened, not what was planned
• Language preservation: store memories in the user's original language
• Related facts kept together to preserve context (not forced into atomic statements)

Non-interactive trigger filtering (isNonInteractiveTrigger):

• Skips recall and capture for cron, heartbeat, automation, schedule triggers
• Also detects trigger type from session key patterns (:cron:, :heartbeat:)

User identity in recall preamble:

• Recall preamble now includes cfg.userId for better attribution
• Extraction preamble includes user identity so memories are stored with correct attribution

Subagent hallucination prevention (isSubagentSession):

• Detects ephemeral subagent sessions via :subagent: in session keys
• Routes subagent recall to parent (main user) namespace — subagents get the user's long-term context
• Skips capture for subagents — prevents orphaned memories
• Subagent-specific preamble to prevent identity assumption

Multi-agent isolation:

• extractAgentId correctly parses subagent session keys
• effectiveUserId produces isolated namespaces per named agent
• Named agents have completely isolated memory namespaces

Session race condition fix:

• Lifecycle hooks now use ctx.sessionKey directly from the event context instead of shared mutable currentSessionId
• Tools still read currentSessionId as best-effort fallback (they don't receive ctx)

SQLite resilience for OSS mode:

• Provider init promises reset on failure, allowing retry
• OSSProvider retries with history disabled when native SQLite bindings fail
• New oss.disableHistory config option

User-content guard: Skip extraction when no meaningful user content remains after filtering.

Expanded extraction window: from last 10 → last 20 messages + earlier summary messages.

Code refactor: Split monolithic 1772-line index.ts into 6 focused modules.

Build pipeline: Fixed tsconfig for modular .ts imports and typed MemoryClient opts for clean DTS generation.

Type of change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

Unit Tests (78 tests passing)

cd openclaw && npx vitest run   # 78 tests, 0 failures
npx tsc --noEmit                # 0 type errors
npx tsup                        # ESM + DTS build success

• isNoiseMessage: heartbeats, NO_REPLY, timestamps, single-word acks, system routing, post-compaction audit, real content passthrough
• isGenericAssistantMessage: boilerplate detection, long messages passthrough, substantive responses passthrough
• stripNoiseFromContent: embedded timestamps, system prefixes, routing lines, mixed content preservation
• filterMessagesForExtraction: end-to-end pipeline, generic assistant dropping, assistant-only payload filtering
• extractAgentId: main agent, named agents, subagent session keys
• effectiveUserId: main user, agent-scoped users
• isNonInteractiveTrigger: cron, heartbeat, automation, schedule triggers; session key patterns (10 tests)
• isSubagentSession: subagent detection, main agent passthrough, named agent passthrough (4 tests)
• mem0ConfigSchema — disableHistory: config parsing for oss.disableHistory (4 tests)
• OSSProvider — disableHistory passthrough: Memory constructor receives flag (2 tests)
• OSSProvider — SQLite fallback: retry with history disabled on failure (3 tests)
• PlatformProvider — init recovery: initPromise reset on failure (1 test)

Live E2E Tests — npm v0.3.3 vs Local v0.4.0 Comparison

Identical test inputs run on both plugin versions with clean mem0 platform between runs.

Test scenarios:

1. Professional + personal context (staff ML engineer, team, family, pets, hobbies)
2. Technical decision with reasoning (Feast → Tecton migration with benchmarks)
3. Multi-turn debug session (model drift → root cause → fix)
4. Korean language policy update
5. Noise filtering (ok / thanks / HEARTBEAT_OK)
6. Recall — relationships ("Who are important people?")
7. Recall — decisions ("What technical decisions and why?")
8. Recall — unrelated query (sourdough bread)
9. Subagent spawn + entity hygiene

Comparison results:

Additional Test Rounds (prior to reviewer feedback)

• 7-phase comprehensive suite: 55 tests, 0 failures
• Multi-agent namespace isolation: 12 tests across researcher/coder/reviewer agents
• Concurrent session safety: 2 simultaneous sessions, both recalled correctly
• userId exploit test: verified parameter behavior
• GUI tests: trigger filtering and subagent isolation verified via OpenClaw GUI

Known Issues (Not Plugin Bugs)

1. Dollar sign corruption ($0.08 → /bin/zsh.08) — upstream mem0 platform bug
2. Fact updates sometimes create new memories instead of updating — platform-side extraction model behavior

• Unit Test (78 tests)
• Type Check (tsc --noEmit, 0 errors)
• Build (tsup, ESM + DTS)
• Live E2E Comparison (npm v0.3.3 vs Local v0.4.0)
• GUI Test (trigger filtering, subagent 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

Maintainer Checklist

• Made sure Checks passed