@romiluz/clawmongo 2026.3.22 → 2026.3.24

package/docs/research/2026-03-22-memory-pain-points-web.md

@@ -0,0 +1,338 @@
+# Web Research: Agent Memory Pain Points -- Real User Complaints
+
+## Execution
+- Preferred backend: websearch+webfetch
+- Allowed fallbacks: webfetch-only
+- Research round: 1
+
+## Sources Used
+- GitHub Issues: openclaw/openclaw (30 memory-related issues analyzed)
+- GitHub Issues: crewAIInc/crewAI (30 memory-related issues analyzed)
+- GitHub Issues: langchain-ai/langchain (30 memory-related issues analyzed)
+- GitHub Issues: Significant-Gravitas/AutoGPT (3 memory-related issues analyzed)
+- GitHub README: mem0ai/mem0 (problem statement and architecture)
+- arXiv: Survey on Memory Mechanisms in LLM-Based Agents (2404.13501)
+- Reddit: blocked by platform (Google search also blocked); findings derived from issue trackers and project documentation
+
+## Research Quality
+- Status: COMPLETE
+- Quality level: high
+- Backend mode: websearch+webfetch
+- Note: Reddit direct access was blocked; compensated with deep GitHub issue mining across 4 major projects (93+ issues reviewed). GitHub issues contain higher-signal complaints than Reddit (reproducible bugs, code-level analysis, production telemetry).
+
+---
+
+## CATEGORY 1: "Memory Management Is In Chaos" -- Config Confusion
+
+**Source:** openclaw/openclaw#43747 (labeled: bug, regression)
+
+The single most damning issue title: **"[Bug]: Memory management is in chaos."** A user discovered that OpenClaw has TWO memory backends (SQLite builtin + QMD markdown files) running simultaneously with NO unified configuration. Different team members had different behavior and did not know why.
+
+Key user quotes:
+- "Who added the QMD feature! This is of no design at all!"
+- "I don't like the QMD. I think this should be configurable."
+- "It's confusing. both [memory directories] exist in my ~/.openclaw folder"
+- Config is "scattered: agents.defaults.compaction.memoryFlush, memory.qmd.*, etc."
+
+**The real pain:** Users cannot reason about WHERE their agent's memory lives, HOW it gets there, or WHICH backend is active. There is no single `memory.type` config. Memory behavior changes silently across versions.
+
+**Related issues:**
+- #47023: memory.qmd.mcporter enabled but memory_search still uses raw qmd query on Linux
+- #46687: Memory file naming inconsistency between AGENTS.md template and session-memory hook
+
+---
+
+## CATEGORY 2: "Memory Just Disappears" -- Silent Data Loss
+
+### 2a. No Write Tool Exists (openclaw#52033)
+
+**Title:** "[Bug]: Tool memory_set not found"
+
+A user asked their agent to "remember this" (Chinese text). The agent called `memory_get` on MEMORY.md **50+ times** in a loop, never finding a way to write. Root cause analysis from a commenter:
+
+- `src/agents/tool-catalog.ts` only lists `memory_search` and `memory_get` -- there is NO `memory_set` core tool
+- The system prompt tells agents to "use memory tools" but only read-oriented tools exist
+- Result: the user's instruction was silently lost forever
+
+**This is the universal failure mode:** agents appear to work (tool calls execute) but nothing is persisted.
+
+### 2b. Plugin Tool Results Silently Dropped (openclaw#47573)
+
+Memory plugin tools (`memory_forget`, `memory_store_batch`) execute successfully but results never reach the session layer. Agent goes silent. Only discoverable after the fact. Requires gateway restart.
+
+### 2c. SQLite Index Goes Empty (openclaw#46599)
+
+After long sessions, memory_search returns "database is not open." The SQLite index silently empties or corrupts, making all stored memory unsearchable.
+
+### 2d. Memory Flush Never Actually Fires (openclaw#43006)
+
+A contributor asked: "Are you actually seeing memory flush working correctly? I'm pretty sure I've never seen memory flush work prior to compaction. It always happens post compaction." -- meaning memory is lost DURING compaction, not saved BEFORE it.
+
+### 2e. Search Returns Paths That Get Can't Resolve (openclaw#50313)
+
+QMD memory_search returns normalized/slugified paths. When the agent calls memory_get with that path, it fails silently. Knowledge base gives "empty results instead of the files you found."
+
+---
+
+## CATEGORY 3: MEMORY.md Is a Token Bomb -- Cost and Performance
+
+**Source:** openclaw/openclaw#26949
+
+MEMORY.md is fully injected into the system prompt DESPITE memory_search/memory_get tools being available. Users report:
+
+- 93.5% of token budget wasted on workspace file injection (#9157)
+- Production user @albinati measured: switching to hierarchical lazy-loading achieved **97.5% payload reduction** (683KB cold storage, 17KB hot path)
+- Token burn rate dropped from ~1.7M input tokens/day to ~42K
+- "Lost in the Middle" attention degradation drops to zero with lazy loading
+
+**The workaround users invented:** Strip MEMORY.md to a lightweight "bootloader" index, move dense context to `memory/*.md` domain files, let memory_search find them on demand.
+
+This is the #1 FinOps pain point for production agent deployments.
+
+---
+
+## CATEGORY 4: No Memory Isolation Between Agents
+
+**Source:** openclaw/openclaw#15325, #38797
+
+All agents share a single memory pool. No `agentId` scoping. Problems:
+
+- Agent A's memories pollute Agent B's recall
+- Privacy leak in multi-user setups (one user's conversation surfaces in another's context)
+- No way to have agent-specific memory retention policies
+
+Community workarounds:
+- @NAPTiON: file-based approach with local Llama 3.2 1B categorizer routing to per-project directories
+- @jamebobob: built openclaw-mem0-multi-pool with user_id as pool discriminator, N:M agent-pool routing
+- Both confirm the approach works but should be built-in
+
+---
+
+## CATEGORY 5: Single Memory Plugin Slot -- Can't Compose Memory Layers
+
+**Source:** openclaw/openclaw#38874 (2 thumbs up, enhancement)
+
+The memory system has a **single plugin slot** -- only one memory backend can be active. But in practice, different memory types serve orthogonal purposes:
+
+- Vector memory (LanceDB, Mem0): semantic similarity, fast recall
+- Graph memory (Cognee, Graphiti): entity relationships, multi-hop reasoning
+- File memory (markdown): structured facts, user preferences
+
+Users need BOTH simultaneously. Current workarounds:
+- @prudkov: disabled Cognee plugin, runs it as standalone Docker API server, queries via custom `kind: "knowledge-graph"` plugin
+- @m13v: layers memory systems outside the plugin model entirely, uses routing layer to decide which source to query
+
+Proposed solution: `kind: "memory-augment"` plugin type that hooks into recall/capture lifecycle without competing for the exclusive slot.
+
+---
+
+## CATEGORY 6: File Watcher Is Silently Dead
+
+**Source:** openclaw/openclaw#34400
+
+Chokidar v4 removed glob support. The file watcher was effectively dead -- `ensureWatcher()` passes `memory/**/*.md` but chokidar v4 silently ignores it. No file changes were detected without gateway restart.
+
+Additional bugs discovered:
+- `DATED_MEMORY_PATH_RE` regex doesn't match dated files in subdirectories -- temporal decay broken
+- `search()` sync is fire-and-forget -- first search after dirty returns stale results
+- New files in subdirectories invisible until process restart even after forced reindex
+
+Users organizing memory into logical subfolders (family/, projects/) find the entire retrieval system goes blind.
+
+---
+
+## CATEGORY 7: LangChain Memory -- Fundamental Architecture Problems
+
+**Source:** langchain-ai/langchain GitHub issues (30 analyzed)
+
+LangChain's memory system has been a persistent pain point across hundreds of issues. Key themes:
+
+### 7a. Memory Incompatible with Retrieval Chains
+- #2303 (high engagement): ConversationalRetrievalChain + Memory doesn't work
+- #2256: Memory not supported with sources chain
+- Pattern: the moment you add source attribution or retrieval, memory breaks
+
+### 7b. Agent-Memory Configuration Hell
+- #4000: Structured Chat Agent doesn't support ConversationMemory
+- #891: Input variable conflicts in conversational agents with memory
+- Pattern: adding memory to agents requires fighting the framework
+
+### 7c. Memory Leak (Literal)
+- Multiple issues about ResourceWarning, unclosed sockets, RAM growing unbounded
+- Instance management problems with FastAPI services (must singleton, not re-instantiate)
+
+### 7d. The "Deprecated" Problem
+LangChain deprecated its memory abstractions in favor of langgraph checkpointing. This left thousands of users with broken upgrade paths and undocumented migration steps.
+
+---
+
+## CATEGORY 8: CrewAI Memory -- Broken By Default
+
+**Source:** crewAIInc/crewAI GitHub issues (30 analyzed)
+
+### 8a. Long-Term Memory Never Actually Stores Data (#1222, 2024-2025)
+Multiple users reported: `memory=True` creates `long_term_memory.db` but the file is empty. The LLM evaluation step (`TaskEvaluator.evaluate()`) silently fails because it can't parse LLM output into structured `TaskEvaluation`. Error: "Missing attributes for long term memory: 'str' object has no attribute 'quality'."
+
+This was reported in August 2024, confirmed by 5+ users, and auto-closed by stale-bot without a fix.
+
+### 8b. Memory Forces OpenAI Calls Even When Running Locally (#447)
+"Passing memory=True reaches out to Open AI, even when running locally with Ollama." Memory feature defaults to external API calls regardless of your LLM configuration.
+
+### 8c. Storage Backend Lock-in (#967, #635)
+Users need alternatives beyond SQLite/Chroma. Requests for MongoDB, Postgres, Valkey/Redis backends were filed and went stale.
+
+### 8d. Memory Module Silently Fails (#1388)
+"CrewAI 0.6 Memory module failed and was not called at all." No error, no warning, just silent absence.
+
+### 8e. Cross-Crew Memory Sharing Impossible (#714)
+Memory doesn't persist across different Crew instances. Each kickoff() starts fresh. Users expected same-instance memory to carry over -- it doesn't.
+
+### 8f. Episodic Amnesia from Context Reset (#4415)
+When context is reset between tasks (to prevent pollution), ALL learned context is wiped: "The system should ideally get smarter with each use, not reset to a base state every time."
+
+---
+
+## CATEGORY 9: AutoGPT Memory -- External Service Failures
+
+**Source:** Significant-Gravitas/AutoGPT issues
+
+- #1073: Local memory file warning -- "auto-gpt.json does not exist. Local memory would not be saved to a file." Persistence failure = session data lost between runs.
+- #328: Pinecone connection error -- vector DB integration failure prevents ALL memory operations
+- #38: Chunking inefficiencies -- how text is split for memory storage affects retrieval accuracy
+
+Pattern: memory depends on external services that fail, and there is NO graceful degradation.
+
+---
+
+## CATEGORY 10: Enterprise Memory Requirements
+
+Synthesized from GitHub issues, community proposals, and project documentation:
+
+### 10a. Audit Trail
+- openclaw#50096 proposes "Long-Term Memory & Knowledge Management" with UAML providing 3-layer recall with SQL archive as "complete safety net"
+- CrewAI#4439 proposes "Agent Trust Stack" with provenance chains, canonical event modeling, deterministic replay
+- Requirement: every memory operation must be traceable, replayable, and attributable
+
+### 10b. Multi-User / Multi-Tenant Isolation
+- openclaw#15325: per-agent memory isolation
+- openclaw#45042: privacy filter by guild/session
+- "Without namespace isolation, Agent A's memory retrieval could surface content from Agent B's private conversations. This isn't hypothetical -- we've seen it happen with shared vector stores."
+
+### 10c. Compliance and Encryption
+- UAML memory (openclaw#50096): PQC encryption (ML-KEM-768, NIST FIPS 203), "designed for regulated environments (GDPR, ISO 27001)"
+- Requirement: memory at rest and in transit must be encrypted; data residency controls
+
+### 10d. Memory Lifecycle / TTL
+- openclaw#45042: "Not all memories should live forever... A ttl or decay_weight field would let retrieval naturally deprioritize stale context"
+- Different memory types need different decay: rules/preferences persist forever, pending tasks and operational context decay after ~90 days
+- openclaw#51385: "frequency-aware ranking, consolidation, and forgetting -- human-like memory lifecycle"
+
+### 10e. Scalability
+- Mem0 benchmarks: 91% faster responses, 90% lower token usage vs full-context
+- Production user measured 97.5% token reduction with hierarchical lazy-loading
+- Without proper memory architecture, costs scale linearly with memory size
+
+### 10f. Disaster Recovery
+- Multiple references to KeepMyClaw (backup service) across OpenClaw issues -- indicating real demand for memory state recovery
+- Sessions corrupt, reset, lose state from provider errors, gateway crashes, session manager bugs
+- "When the session layer drops results silently, external backups preserve the full context"
+
+---
+
+## WHAT CHANGED THE RECOMMENDATION
+
+**The single highest-signal finding:**
+
+The OpenClaw ecosystem has spawned **at least 8 third-party memory solutions** (UAML, KeepMyClaw, mem9, Synapse, SuperBrain, NAPTiON pipeline, user-memories, openclaw-mem0-multi-pool) in the span of weeks -- all trying to fix the same fundamental problem: **the default memory system is file-based, single-slot, lacks write primitives, has no isolation, silently loses data, and wastes tokens.**
+
+This is not a "nice to have" feature gap. This is a market signal that the memory layer is broken enough to spawn an entire ecosystem of workarounds.
+
+ClawMongo's v2 architecture (event-first, MongoDB-native, multi-path retrieval, graph traversal, episode materialization) directly addresses every single pain point documented above:
+
+| Pain Point | ClawMongo v2 Answer |
+|---|---|
+| Config chaos (2 backends, scattered config) | Single MongoDB backend, unified config |
+| Silent data loss / no write tool | Events as primary write target, canonical truth |
+| Token bomb (full injection) | Retrieval planner selects relevant paths only |
+| No agent isolation | Scope field on events, entities, episodes |
+| Single memory slot | 6 retrieval paths (chunks, events, entities, relations, episodes, structured) |
+| File watcher dead | MongoDB Change Streams (no file watching) |
+| No audit trail | Immutable event log, ingest/projection runs |
+| No TTL/lifecycle | expiresAt + TTL indexes (planned from AWM research) |
+| Cross-session amnesia | Persistent MongoDB storage, episode materialization |
+| Scalability | Atlas-native vector search, horizontal scaling |
+
+---
+
+## GOTCHAS / WARNINGS
+
+1. **The "memory_set not found" pattern is universal** -- agents that can READ memory but not WRITE it will loop indefinitely. Any memory system MUST have explicit write primitives exposed as agent tools.
+
+2. **Silent failures are worse than crashes** -- across ALL frameworks, the most damaging bugs are silent ones: empty databases, dropped tool results, dead file watchers. Users only discover data loss after the fact.
+
+3. **Memory configuration sprawl kills adoption** -- OpenClaw's scattered config (memoryFlush, qmd.*, backend, plugin entries) is a cautionary tale. ClawMongo must have ONE clear config surface.
+
+4. **Plugin/extension architecture matters** -- single-slot memory blocks composition. ClawMongo's multi-collection approach inherently supports parallel memory types but this must be exposed through clear APIs.
+
+5. **Production cost is the adoption gate** -- the 97.5% token reduction from lazy-loading shows that naive memory injection makes production deployment economically unviable. Retrieval planning is not optional.
+
+6. **Cross-agent memory sharing is a top-3 request** -- CrewAI, OpenClaw, and AutoGPT all have issues requesting it. Memory isolation + controlled sharing must be first-class.
+
+7. **LangChain's deprecation of memory abstractions** left users stranded -- any memory API surface must be stable and migration-safe.
+
+## REFERENCES
+
+### OpenClaw Issues (Primary Source)
+- https://github.com/openclaw/openclaw/issues/52033 -- memory_set not found (no write tool)
+- https://github.com/openclaw/openclaw/issues/43747 -- "Memory management is in chaos"
+- https://github.com/openclaw/openclaw/issues/26949 -- MEMORY.md token bomb
+- https://github.com/openclaw/openclaw/issues/38874 -- single memory plugin slot
+- https://github.com/openclaw/openclaw/issues/15325 -- per-agent memory isolation
+- https://github.com/openclaw/openclaw/issues/34400 -- recursive subdirectory search broken
+- https://github.com/openclaw/openclaw/issues/50313 -- search/get path mismatch
+- https://github.com/openclaw/openclaw/issues/47573 -- plugin tool results silently dropped
+- https://github.com/openclaw/openclaw/issues/46599 -- SQLite index empty after long session
+- https://github.com/openclaw/openclaw/issues/43006 -- memory flush doesn't fire before compaction
+- https://github.com/openclaw/openclaw/issues/50096 -- Long-term memory & knowledge management
+- https://github.com/openclaw/openclaw/issues/45042 -- active memory retrieval + context compaction
+- https://github.com/openclaw/openclaw/issues/51385 -- frequency-aware ranking and forgetting
+- https://github.com/openclaw/openclaw/issues/48558 -- Anthropic Memory Tool support
+- https://github.com/openclaw/openclaw/issues/43408 -- case-insensitive MEMORY.md duplication
+- https://github.com/openclaw/openclaw/issues/49495 -- plugin config rejected by gateway validator
+- https://github.com/openclaw/openclaw/issues/51676 -- memory_search fails to load (bad npm publish)
+- https://github.com/openclaw/openclaw/issues/27863 -- memory_write for orchestrator sessions
+- https://github.com/openclaw/openclaw/issues/9157 -- 93.5% token budget wasted
+- https://github.com/openclaw/openclaw/issues/46570 -- memory search only returns sessions, not memory files
+
+### CrewAI Issues
+- https://github.com/crewAIInc/crewAI/issues/1222 -- long-term memory not storing data
+- https://github.com/crewAIInc/crewAI/issues/447 -- memory=True calls OpenAI even with Ollama
+- https://github.com/crewAIInc/crewAI/issues/967 -- alternative database storage
+- https://github.com/crewAIInc/crewAI/issues/1388 -- memory module silently failed
+- https://github.com/crewAIInc/crewAI/issues/714 -- sharing memory between crew instances
+- https://github.com/crewAIInc/crewAI/issues/4415 -- episodic amnesia from context reset
+- https://github.com/crewAIInc/crewAI/issues/4509 -- Pydantic validation error saving memory
+- https://github.com/crewAIInc/crewAI/issues/4703 -- telemetry fails with custom memory backends
+- https://github.com/crewAIInc/crewAI/issues/4682 -- agent loop detection (memory-related)
+- https://github.com/crewAIInc/crewAI/issues/4030 -- external memory with Mem0/Valkey fails
+- https://github.com/crewAIInc/crewAI/issues/4222 -- memory leak in execution_spans
+- https://github.com/crewAIInc/crewAI/issues/4210 -- memory leak from @lru_cache on instance methods
+- https://github.com/crewAIInc/crewAI/issues/4423 -- Mem0Storage crashes with JSON string config
+
+### LangChain Issues
+- https://github.com/langchain-ai/langchain/issues/2303 -- ConversationalRetrievalChain + Memory
+- https://github.com/langchain-ai/langchain/issues/2256 -- Memory not supported with sources chain
+- https://github.com/langchain-ai/langchain/issues/4000 -- Structured Chat Agent + ConversationMemory
+- https://github.com/langchain-ai/langchain/issues/891 -- input variable conflicts with memory
+
+### AutoGPT Issues
+- https://github.com/Significant-Gravitas/AutoGPT/issues/1073 -- local memory file not saved
+- https://github.com/Significant-Gravitas/AutoGPT/issues/328 -- Pinecone connection failure
+- https://github.com/Significant-Gravitas/AutoGPT/issues/38 -- chunking problems
+
+### Other Sources
+- https://github.com/mem0ai/mem0 -- Mem0 architecture and problem statement
+- arXiv 2404.13501 -- Survey: Memory Mechanisms in LLM-Based Agents
+
+---
+Web research complete.

package/docs/research/2026-03-22-openclaw-ecosystem-github.md

@@ -0,0 +1,306 @@
+# GitHub Research: OpenClaw Ecosystem
+
+## Execution
+- Preferred backend: web-only (no Octocode MCP available)
+- Allowed fallbacks: WebFetch, local codebase reading
+- Research round: 1
+
+## Sources Used
+- Local codebase (ClawMongo fork, synced 0 behind upstream as of 2026-03-22)
+- GitHub web (openclaw/openclaw repo page, issues, pulse, forks, topics)
+- npmjs.com (openclaw package)
+- DeepWiki (openclaw/openclaw architectural analysis)
+- GitHub competitor repos (AutoGPT, CrewAI)
+
+## Research Quality
+- Status: COMPLETE
+- Quality level: high
+- Backend mode: web-only
+- Note: Local codebase is 0 commits behind upstream/main and 273 commits ahead, making it a reliable mirror of upstream + ClawMongo additions.
+
+---
+
+## 1. OpenClaw Repository Overview
+
+**Repo:** github.com/openclaw/openclaw
+**Tagline:** "Your own personal AI assistant. Any OS. Any Platform. The lobster way."
+
+### Metrics (as of 2026-03-22)
+| Metric | Value |
+|--------|-------|
+| Stars | 329,000 |
+| Forks | 63,900 |
+| Open issues | 8,756 |
+| Commits (all time) | 20,918 |
+| Security advisories | 288 |
+| npm weekly downloads | 1,109,169 |
+| npm package name | `openclaw` |
+| Latest npm version | 2026.3.13 |
+| License | MIT |
+| Language | TypeScript (ESM) |
+| Runtime | Node 24 (recommended) / Node 22.16+ |
+
+### History / Name Evolution
+Warelay -> Clawdbot -> Moltbot -> OpenClaw (from VISION.md). Backward-compat shims exist for clawdbot/moltbot naming.
+
+### Maintainers (from CONTRIBUTING.md)
+- **Peter Steinberger (@steipete)** -- Benevolent Dictator
+- **Shadow (@thewilloftheshadow)** -- Discord, community moderation, ClawHub
+- **Vignesh (@vignesh07)** -- Memory (QMD), TUI, IRC, Lobster
+- **Jos (@joshp123)** -- Telegram, API, Nix
+- **Ayaan Zaidi (@obviyus)** -- Telegram, Android
+- **Tyler Yust (@tyler6204)** -- Agents/subagents, cron, BlueBubbles, macOS
+- **Mariano Belinky (@mbelinky)** -- iOS, Security
+- **Nimrod Gutman (@ngutman)** -- iOS, macOS
+- **Vincent Koc (@vincentkoc)** -- Agents, Telemetry, Hooks, Security
+- Plus 6+ additional domain maintainers covering CLI, plugins, Matrix, ACP, docs, and JS infra
+
+---
+
+## 2. npm Package Metadata
+
+```json
+{
+  "name": "openclaw",
+  "version": "2026.3.13",
+  "description": "Personal AI assistant you run on your own devices...",
+  "license": "MIT",
+  "author": "steipete",
+  "bin": { "openclaw": "openclaw.mjs" },
+  "dependencies": 55,
+  "weeklyDownloads": 1109169
+}
+```
+
+ClawMongo fork publishes as `@romiluz/clawmongo` with dual bin entries (`clawmongo` + `openclaw` alias).
+
+### Plugin SDK Surface (package.json exports)
+The npm package exposes 35+ subpath exports under `./plugin-sdk/*`, including:
+- Core: `./plugin-sdk`, `./plugin-sdk/core`, `./plugin-sdk/runtime`
+- Channels: `./plugin-sdk/channel-setup`, `./plugin-sdk/channel-runtime`, `./plugin-sdk/channel-reply-pipeline`
+- Providers: `./plugin-sdk/provider-setup`, `./plugin-sdk/self-hosted-provider-setup`
+- Runtime: `./plugin-sdk/agent-runtime`, `./plugin-sdk/gateway-runtime`, `./plugin-sdk/cli-runtime`
+- Security: `./plugin-sdk/security-runtime`, `./plugin-sdk/ssrf-runtime`
+- Media: `./plugin-sdk/media-runtime`, `./plugin-sdk/speech-runtime`
+- Other: `./plugin-sdk/sandbox`, `./plugin-sdk/routing`, `./plugin-sdk/hook-runtime`, `./plugin-sdk/acp-runtime`
+
+This is one of the most comprehensive plugin SDK surfaces in the agent runtime space.
+
+---
+
+## 3. Extensions / Plugin Ecosystem
+
+**Total extensions: 78 directories** under `extensions/`.
+
+### By Category
+
+**Channel Plugins (24 messaging platforms):**
+WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, BlueBubbles, iMessage, IRC, Microsoft Teams, Matrix, Feishu/Lark, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon/Urbit, Twitch, Zalo, Zalo Personal, WebChat, plus voice-call and device-pair
+
+**LLM/AI Provider Plugins (25+ providers):**
+OpenAI, Anthropic, Anthropic Vertex, Google, Amazon Bedrock, Mistral, Ollama, OpenRouter, GitHub Copilot, Perplexity, xAI, Together, NVIDIA, Hugging Face, fal, MiniMax, Moonshot, BytePlus, Chutes, Venice, Volcengine, vLLM, SGLang, Qianfan, Kimi, Xiaomi, Model Studio, Kilocode, OpenCode, OpenCode Go, Z.AI, Copilot Proxy, Cloudflare AI Gateway, Vercel AI Gateway
+
+**Speech / Media Plugins:**
+ElevenLabs (speech), Microsoft (speech), talk-voice
+
+**Tool / Utility Plugins:**
+Brave (web search), Firecrawl (web scraping), Tavily (web search), lobster (typed workflow pipelines), diffs (diff viewer), llm-task (JSON-only LLM tasks), open-prose (VM skill pack)
+
+**Infrastructure Plugins:**
+diagnostics-otel (OpenTelemetry), openshell (sandbox backend), acpx (ACP runtime), memory-core (memory tools), thread-ownership, phone-control, synthetic
+
+**Auth Plugins:**
+google-antigravity-auth, openai-codex-auth, qwen-portal-auth
+
+### Plugin Architecture
+- Plugins register via `definePluginEntry()` with `OpenClawPluginApi`
+- Plugins can register: tools, CLI commands, memory prompt sections, context engines
+- Memory is a special "kind" slot (only one memory plugin active at a time)
+- Distribution: npm packages or local extension loading
+- Plugin marketplace support exists (Claude marketplace, ClawHub)
+- MCP integration via external `mcporter` bridge (not built into core)
+
+---
+
+## 4. Memory Architecture (Upstream vs ClawMongo)
+
+### Upstream OpenClaw Memory
+- **Default backends:** `builtin` (SQLite) and `qmd` (Quick Markdown) for vector/hybrid search
+- **QMD:** QmdMemoryManager -- Markdown-file-based memory with vector search via LanceDB
+- **Memory plugin slot:** `memory-core` extension provides `memory_search`, `memory_get`, `kb_search`, `memory_write` tools
+- VISION.md states: "Memory is a special plugin slot where only one memory plugin can be active at a time. Today we ship multiple memory options; over time we plan to converge on one recommended default path."
+- Upstream recently pivoted toward QMD as the recommended backend
+
+### ClawMongo Memory (Fork Additions, 273 commits ahead)
+- **MongoDB-only:** Community mongod + mongot, Voyage AI autoEmbed
+- **20 collections, 53 standard indexes, up to 8 MongoDB Search indexes**
+- **Canonical events architecture:** events as single source of truth, everything else derived
+- **8 retrieval paths:** active-critical, procedural, structured, raw-window, graph, episodic, kb, hybrid
+- **Knowledge graph:** $graphLookup with bi-directional expansion
+- **Episode materialization:** auto-triggers on session gaps or event count thresholds
+- **Structured memory:** salience, temporal validity, state, provenance, revision tracking
+- **Procedures:** versioned workflow artifacts with intent tags and ordered steps
+- **Retrieval planner:** pure-function path scoring based on query analysis
+- **1,632 lines** in mongodb-schema.ts alone
+
+### Key Architectural Gap
+Upstream treats memory as a file/Markdown concern. ClawMongo treats memory as a database-first concern with explicit write/read/audit semantics. The fork's memory system is materially more sophisticated than upstream's QMD or SQLite paths.
+
+---
+
+## 5. Onboarding Flow
+
+**34 files** under `src/commands/onboard*.ts` covering:
+- `onboard.ts` -- main entry, dispatches to interactive or non-interactive
+- `onboard-interactive.ts` -- step-by-step wizard
+- `onboard-non-interactive.ts` -- scripted/headless setup
+- `onboard-channels.ts` -- channel configuration
+- `onboard-config.ts` -- config file generation
+- `onboard-hooks.ts` -- hook setup
+- `onboard-skills.ts` -- skill enablement
+- `onboard-search.ts` -- provider search/discovery
+- `onboard-custom.ts` -- custom provider setup
+- `onboard-remote.ts` -- remote gateway setup
+- `onboard-helpers.ts` -- shared utilities
+- `onboard-types.ts` -- type definitions
+
+**Key features:**
+- Interactive wizard (default) or `--non-interactive` for CI/automation
+- `--install-daemon` flag installs launchd/systemd user service
+- Auth choices: setup-token (Anthropic), openai-codex (OAuth), etc.
+- `--accept-risk` required for non-interactive mode (security gate)
+- Reset scopes: `config`, `config+creds+sessions`, `full`
+- Cross-platform: macOS, Linux, Windows (WSL2 recommended)
+
+---
+
+## 6. Companion Apps
+
+OpenClaw ships native apps under `apps/`:
+- **macOS** -- SwiftUI, Sparkle updates, voice wake, menubar gateway
+- **iOS** -- SwiftUI, voice wake, Observation framework
+- **Android** -- Kotlin, dark theme, Talk speech, SMS/call log search
+- **shared** -- cross-platform code
+
+This is unusual for an agent runtime. Most competitors are CLI-only or web-only.
+
+---
+
+## 7. Community Activity Patterns
+
+### Issue Categories (8,756 open)
+1. Gateway stability during long-running operations
+2. Cross-platform compatibility (Windows/Linux filesystem)
+3. Multi-language/localization gaps
+4. Third-party service integration reliability
+5. Plugin dependency resolution
+6. Memory/session stability (OOM, leaks)
+7. Channel-specific bugs (Telegram, Discord, Matrix)
+
+### Contributing Bar
+- Bugs/small fixes: direct PR welcome
+- New features: start a Discussion or Discord first
+- Refactor-only PRs: not accepted unless maintainer-requested
+- AI-generated code: welcomed, must be marked and tested
+- CI requirements: `pnpm build && pnpm check && pnpm test`
+
+### Recent Changelog Activity (Unreleased)
+The unreleased changelog section shows 50+ entries, indicating very high development velocity. Recent additions include:
+- Anthropic Vertex provider support
+- `/btw` side-question command
+- Pluggable sandbox backends (OpenShell)
+- SSH sandbox backend
+- Firecrawl/Tavily web search providers
+- Claude/Codex/Cursor bundle compatibility
+- Plugin marketplace support
+- MiniMax, Xiaomi model updates
+- Telegram topic auto-labeling
+- Matrix bot-to-bot communication
+- GPT-5.4-mini/nano forward-compat
+
+---
+
+## 8. Competitive Landscape
+
+### Direct Competitors
+
+| Project | Stars | Language | Focus | Memory | Channels |
+|---------|-------|----------|-------|--------|----------|
+| **OpenClaw** | 329K | TypeScript | Personal assistant, multi-channel | SQLite/QMD/pluggable | 24 messaging platforms |
+| **AutoGPT** | 183K | Python/TS | Agent builder platform, low-code | PostgreSQL | Web UI only |
+| **CrewAI** | 46.8K | Python | Multi-agent orchestration | Pluggable | None (library) |
+| **LangChain** | ~90K | Python/JS | LLM framework/toolkit | Pluggable (100+ stores) | None (library) |
+
+### What Makes OpenClaw Unique
+
+1. **Multi-channel native:** 24 messaging platforms, all in one runtime. No other agent framework comes close. AutoGPT has a web UI. CrewAI has nothing. LangChain is a library.
+
+2. **Self-hosted, single-user, privacy-first:** runs on your devices, local gateway binds to loopback. Not a SaaS platform.
+
+3. **Native companion apps:** macOS, iOS, Android apps with voice wake, canvas, TUI. AutoGPT has a web builder. CrewAI has a cloud offering. Neither has native apps.
+
+4. **25+ LLM providers:** provider plugins for essentially every major and niche LLM provider. Most frameworks support 5-10.
+
+5. **Plugin SDK depth:** 35+ subpath exports, channel/provider/tool/memory/context-engine extension points. The plugin surface is production-grade, not a toy API.
+
+6. **Active development velocity:** 20,918 commits, 50+ unreleased changelog entries, 15+ named maintainers. This is one of the most actively developed open-source agent projects.
+
+7. **Security posture:** dedicated SECURITY.md, GHSA workflow, trust page, DM pairing policies, SSRF protection, secret-ref system, sandbox backends. Most agent frameworks treat security as an afterthought.
+
+### Where OpenClaw is Weaker vs Competitors
+
+1. **Multi-agent orchestration:** CrewAI's role-based crew/flow model is more sophisticated for multi-agent task decomposition. OpenClaw's multi-agent is per-workspace isolation, not collaborative crews.
+
+2. **Workflow automation:** AutoGPT's visual builder is more accessible for non-developers. OpenClaw is terminal-first by design.
+
+3. **Memory sophistication (upstream):** Upstream's QMD/SQLite memory is basic compared to what LangChain can plug into (100+ vector stores). ClawMongo addresses this gap with MongoDB-native memory.
+
+4. **Python ecosystem:** CrewAI and LangChain have Python's AI/ML ecosystem advantage. OpenClaw's TypeScript choice trades ecosystem breadth for hackability and web-developer familiarity.
+
+---
+
+## 9. Other Forks / Variants
+
+The fork network shows hundreds of forks, with several patterns:
+- **Renamed forks:** `clawdbot`, `moltbot` appear dozens of times (legacy names)
+- **Specialized forks:** `openclaw-meets-kiro`, `openclaw-msns`, `openclaw-westworld`, `openclaw-rust`
+- **ClawMongo** (this fork): the only known MongoDB-native fork with 273 commits of divergence
+
+No other fork appears to have the scope of architectural divergence that ClawMongo has with its MongoDB-first memory rewrite.
+
+---
+
+## 10. What Makes ClawMongo Differentiated from Upstream
+
+| Dimension | Upstream OpenClaw | ClawMongo |
+|-----------|-------------------|-----------|
+| Memory backend | SQLite / QMD (Markdown + LanceDB) | MongoDB Community + mongot |
+| Memory model | File-based, flat search | Event-sourced, 20 collections, 8 retrieval paths |
+| Vector search | LanceDB local | Voyage AI autoEmbed via mongot (no app-side embedding code) |
+| Knowledge graph | None | $graphLookup with entities/relations/bi-directional expansion |
+| Episodes | None | Auto-materialized from event windows |
+| Structured memory | Basic | Salience, temporal validity, state, provenance, revision tracking |
+| Procedures | None | Versioned workflow artifacts with intent tags |
+| Retrieval planning | Simple search | 8-path planner with query analysis |
+| Operational visibility | Limited | Ingest runs, projection runs, relevance telemetry |
+| Collections | ~2 | 20 |
+| Indexes | Few | 53 standard + 8 search indexes |
+
+---
+
+## What Changed the Recommendation
+
+**Highest-signal finding:** OpenClaw has 329K stars and 1.1M weekly npm downloads, making it one of the most popular open-source agent projects globally -- far larger than AutoGPT (183K stars) in star count and community size. The upstream project is actively developed with 15+ maintainers, 78 extensions, 24 messaging channels, and native apps for 3 platforms. However, upstream's memory system (QMD/SQLite) is the acknowledged weak point -- VISION.md explicitly states they plan to "converge on one recommended default path" for memory. ClawMongo's MongoDB-native memory architecture (20 collections, 8 retrieval paths, knowledge graph, episodes, procedures) fills the exact gap that upstream acknowledges but has not yet addressed. This positions ClawMongo not as a competing fork but as the production memory backend that OpenClaw needs.
+
+## References
+- https://github.com/openclaw/openclaw (329K stars)
+- https://www.npmjs.com/package/openclaw (1.1M weekly downloads)
+- https://deepwiki.com/openclaw/openclaw
+- https://github.com/Significant-Gravitas/AutoGPT (183K stars)
+- https://github.com/crewAIInc/crewAI (46.8K stars)
+- https://docs.openclaw.ai
+- Local: VISION.md, CONTRIBUTING.md, CHANGELOG.md, package.json
+- Local: extensions/ (78 plugins), src/memory/ (MongoDB architecture), src/commands/onboard*.ts (34 files)
+
+---
+GitHub research complete.