@romiluz/clawmongo 2026.3.22 → 2026.3.24

package/docs/research/2026-03-22-openclaw-positioning-web.md

@@ -0,0 +1,353 @@
+# Web Research: OpenClaw Product Positioning
+
+## Execution
+- Preferred backend: websearch+webfetch
+- Allowed fallbacks: webfetch-only
+- Research round: 1
+
+## Sources Used
+- WebFetch succeeded on: openclaw.ai, docs.openclaw.ai (8 pages), github.com/openclaw/openclaw, npmjs.com/package/openclaw
+- WebFetch failed on: docs.openclaw.ai/concepts/skills (404)
+- Local codebase: README.md, package.json (ClawMongo fork context)
+
+## Research Quality
+- Status: COMPLETE
+- Quality level: high
+- Backend mode: webfetch-only (multiple pages fetched successfully, comprehensive coverage)
+
+---
+
+## 1. What Is OpenClaw?
+
+### Elevator Pitch
+OpenClaw describes itself as **"The AI that actually does things."** and **"your own personal AI assistant"** that you run on your own devices.
+
+### Product Identity
+OpenClaw is NOT a chatbot framework, NOT a memory library, NOT an agent SDK. It is a **complete personal AI assistant product** with:
+- A **Gateway daemon** (always-on control plane)
+- **22+ messaging channel integrations** (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, etc.)
+- **Agent runtime** built on Pi agent core (Claude Agent SDK lineage)
+- **Memory system** (Markdown files + SQLite + optional QMD sidecar)
+- **Tool system** (browser automation, shell access, file operations, web search)
+- **Companion apps** (macOS menubar, iOS, Android)
+- **Voice Wake + Talk Mode** on macOS/iOS/Android
+- **Live Canvas** with A2UI visualization
+- **Extensible skills/plugins** system
+
+### Core Philosophy
+- **Local-first**: runs on your machine, data stays with you
+- **Multi-channel**: one assistant reachable from any chat app
+- **Always-on**: gateway daemon runs in background
+- **Single-user**: personal assistant, not enterprise multi-tenant
+- **"AI as teammate, not tool"**: positioned as a persistent companion, not a one-shot API
+
+### Key Taglines Used
+- "The AI that actually does things."
+- "your own personal AI assistant"
+- "Any OS. Any Platform. The lobster way."
+- "a better version of Siri built outside corporate constraints"
+
+---
+
+## 2. Who Uses OpenClaw?
+
+### Target Audience
+- **Primary**: Developers and technical power users who want AI automation with full control
+- **Secondary**: Privacy-conscious users who want local-first AI
+- **Aspirational**: Non-technical users (onboarding wizard tries to lower the bar)
+
+### Use Cases Marketed
+- Clear inboxes, send emails, manage calendars
+- Check flight reservations
+- Autonomous background tasks (cron jobs)
+- Browser automation (fill forms, extract data)
+- File system operations (read/write/execute)
+- Code assistance (built on agent SDK with coding tools)
+
+### NOT Positioned For
+- Enterprise/team deployments (single-user focused)
+- Chatbot-as-a-service platforms
+- API-only agent frameworks
+- Customer-facing bot builders
+
+---
+
+## 3. Channel Support (Complete List)
+
+### Built-in Channels (10)
+1. WhatsApp (via Baileys)
+2. Telegram (via grammY)
+3. Discord (via discord.js)
+4. Slack (via Bolt)
+5. Signal
+6. iMessage (legacy)
+7. BlueBubbles (iMessage modern)
+8. Google Chat
+9. IRC
+10. WebChat
+
+### Plugin/Extension Channels (12)
+11. Microsoft Teams
+12. Matrix
+13. Feishu
+14. LINE
+15. Mattermost
+16. Nextcloud Talk
+17. Nostr
+18. Synology Chat
+19. Tlon
+20. Twitch
+21. Zalo
+22. Zalo Personal
+
+### Channel Marketing
+- **22 total channels** -- by far the broadest multi-channel AI assistant
+- Telegram marketed as "quickest setup" (bot token only)
+- WhatsApp requires QR auth, more complex
+- Text works universally; media/reaction support varies by channel
+- Group chat support with allowlists and mention rules
+
+---
+
+## 4. How OpenClaw Handles Memory (Default)
+
+### Architecture: Markdown-First
+OpenClaw's default memory is **plain Markdown files as the source of truth**:
+- `memory/YYYY-MM-DD.md` -- daily append-only logs
+- `MEMORY.md` -- curated long-term memory (human-authored)
+- Located in agent workspace (`~/.openclaw/workspace`)
+
+### Memory Tools
+- `memory_search` -- semantic recall over indexed snippets
+- `memory_get` -- targeted file/line-range reads
+
+### Storage Backend: SQLite
+- **Primary storage**: SQLite at `~/.openclaw/memory/<agentId>.sqlite`
+- Uses `sqlite-vec` extension for vector acceleration
+- BM25 keyword + vector similarity hybrid search
+- MMR (Maximal Marginal Relevance) for diversity ranking
+- Recency weighting with configurable half-life decay
+
+### QMD (Experimental)
+- **"Local-first search sidecar combining BM25 + vectors + reranking"**
+- Uses its own SQLite with extensions
+- Separate from main SQLite backend
+- Has its own search modes: `search`, `vsearch`, `query`
+- Configurable collection paths, update intervals, timeouts
+
+### Embedding Providers (auto-selected order)
+1. Local (if `modelPath` exists)
+2. OpenAI
+3. Gemini
+4. Voyage
+5. Mistral
+6. Ollama (manual config only)
+
+### Memory Limitations (Why ClawMongo Exists)
+- Recall quality drops as corpus grows (flat file indexing)
+- No real database backend -- SQLite is the ceiling
+- Sync/consistency hard across multiple runtimes
+- No operational visibility or retrieval diagnostics
+- No structured knowledge base ingestion pipeline
+- No graph traversal or entity relationships
+- No event-sourcing or canonical data model
+
+---
+
+## 5. Installation Experience
+
+### One-liner Install
+```bash
+# macOS/Linux
+curl -fsSL https://openclaw.ai/install.sh | bash
+
+# Windows (PowerShell)
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+### Also Available Via
+```bash
+npm install -g openclaw@latest
+```
+
+### Onboarding Flow (approx. 2 minutes)
+1. `openclaw onboard --install-daemon`
+2. Select model provider (Anthropic, OpenAI, Google, etc.)
+3. Enter API key
+4. Gateway auto-configures on port 18789
+5. `openclaw gateway status` to verify
+6. `openclaw dashboard` opens Control UI in browser
+7. Send first message via Control UI
+8. Optionally connect a channel (Telegram is quickest)
+
+### Prerequisites
+- Node.js 24 (recommended) or Node 22.16+
+- API key from any supported model provider
+
+### Companion Apps
+- macOS menubar app (beta)
+- iOS app
+- Android app
+
+---
+
+## 6. GitHub Positioning
+
+### Metrics (March 2026)
+- **Stars**: 329,000 (329k) -- extremely popular
+- **Forks**: 63,900 (63.9k)
+- **License**: MIT
+- **Primary Language**: TypeScript/JavaScript
+- **Release format**: vYYYY.M.D (date-based versioning)
+
+### README Structure
+- Hero image with lobster branding
+- "EXFOLIATE! EXFOLIATE!" tagline
+- One-paragraph product description
+- Quick links (docs, Discord, getting started, FAQ, showcase)
+- Feature sections with details
+- Installation instructions
+- Architecture overview
+
+### GitHub Topics/Tags
+- Personal AI assistant
+- Local-first
+- Multi-channel
+- Open source
+
+### Community Signals
+- Very high star count (329k) puts it in top-tier GitHub projects
+- 63.9k forks indicates massive developer interest
+- Active release cadence (date-based versioning with frequent releases)
+- Discord community linked prominently
+
+---
+
+## 7. npm Positioning
+
+### Package Details
+- **Name**: `openclaw`
+- **Version**: 2026.3.13 (at time of research)
+- **Weekly Downloads**: 1,109,169 (1.1M+)
+- **License**: MIT
+- **Maintainer**: steipete
+- **Dependencies**: 55 direct (Discord.js, Slack Bolt, Anthropic Claude, AI/agent frameworks)
+
+### npm Description
+"Personal AI assistant you run on your own devices" with multi-channel integration and local-first control.
+
+### Download Significance
+1.1M weekly downloads is very high -- indicates broad adoption and/or CI pipeline inclusion. This is enterprise-grade download volume for an open-source tool.
+
+---
+
+## 8. Documentation Quality
+
+### Site: docs.openclaw.ai (Mintlify-hosted)
+
+### Structure (key sections)
+- **Getting Started**: install, onboard, first message
+- **Channels**: 22 individual channel setup guides
+- **Concepts**: memory, context engine, agent runtime, session management, compaction, streaming, multi-agent routing, delegate architecture
+- **Gateway**: architecture, configuration, remote setup, multiple gateways
+- **Reference**: memory config, session management deep dive, configuration reference
+- **Install**: Docker, Kubernetes, Node.js, Podman, Railway, Render, DigitalOcean, Azure, GCP, Fly.io, Hetzner
+- **Help**: FAQ, troubleshooting, testing
+
+### Documentation Quality Assessment
+- Comprehensive and well-organized
+- Covers 11+ deployment targets (Docker, K8s, cloud providers)
+- Individual guides for all 22 channels
+- Deep technical reference for memory, sessions, context
+- `llms.txt` available for LLM consumption of docs
+- Architecture docs explain gateway, agent loop, context engine
+
+---
+
+## 9. Competitive Positioning
+
+### Implicit Comparisons (from website)
+- Positioned as **"a better version of Siri"** built outside corporate constraints
+- Contrasted with cloud-dependent AI services (ChatGPT, Gemini, etc.)
+- Differentiator: local execution, data sovereignty, multi-channel reach
+
+### No Explicit Comparison Page Found
+- No "OpenClaw vs X" page found in docs
+- No formal competitor comparison matrix
+- Positioning is aspirational/unique rather than comparative
+
+### Key Differentiators vs Competitors
+| vs | OpenClaw Advantage |
+|---|---|
+| ChatGPT/Claude apps | Runs locally, multi-channel, persistent memory, tool access |
+| Siri/Alexa | Open source, customizable, real task execution |
+| LangChain/CrewAI | Complete product (not just framework), built-in channels |
+| Custom agent builds | Turnkey install, 22 channels, companion apps, community |
+
+---
+
+## 10. Community Presence
+
+### Discord
+- Active Discord server (discord.gg/clawd)
+- Badge displayed prominently on GitHub and README
+- Primary community hub
+
+### GitHub
+- 329k stars, 63.9k forks
+- Active issue tracker and PR flow
+- Multiple maintainers contributing
+
+### Social/Web Presence
+- openclaw.ai website (product marketing)
+- docs.openclaw.ai (comprehensive documentation)
+- DeepWiki page (deepwiki.com/openclaw/openclaw)
+- NPM presence with 1.1M+ weekly downloads
+
+### Community Health Signals
+- Very active development (frequent releases)
+- Multiple deployment guides for different platforms
+- Extensive channel integration ecosystem (22 channels)
+- Plugin/extension system allows community contributions
+- Maintained by steipete (primary) with contributor community
+
+---
+
+## What Changed the Recommendation
+
+The single highest-signal finding is that **OpenClaw is NOT an agent framework or memory library -- it is a complete, turnkey personal AI assistant product with 329k GitHub stars and 1.1M+ weekly npm downloads**. ClawMongo's positioning should reflect this: it is not "a MongoDB memory backend" but rather "OpenClaw (the most popular open-source personal AI assistant) with a production-grade MongoDB memory system that replaces the default SQLite/Markdown approach." The product IS the assistant. The memory upgrade is what makes it enterprise/team-ready.
+
+Key implication: ClawMongo should position as "OpenClaw for production" or "OpenClaw for teams" rather than as a memory library or database integration.
+
+---
+
+## Gotchas / Warnings
+
+- OpenClaw's default memory (Markdown + SQLite) is intentionally simple and local-first. ClawMongo adds complexity. Positioning must address when that complexity is worth it vs. when default memory is sufficient.
+- OpenClaw has 329k stars. ClawMongo must be careful not to position as a "competitor" but as a "distribution" or "flavor" of the same product.
+- The upstream has pivoted to QMD as its experimental advanced memory backend. ClawMongo's MongoDB approach diverges from upstream's direction.
+- OpenClaw's 22-channel support is a massive differentiator. ClawMongo inherits ALL of this. This should be front-and-center in positioning.
+- The product is marketed as single-user/personal. ClawMongo's "team-scale" positioning extends beyond upstream's intended use case.
+- npm downloads at 1.1M+/week means OpenClaw has significant market presence. ClawMongo benefits from this ecosystem.
+- steipete is the primary npm maintainer -- important to acknowledge upstream authorship.
+
+---
+
+## References
+
+- https://openclaw.ai (product website)
+- https://docs.openclaw.ai (documentation hub)
+- https://docs.openclaw.ai/concepts/memory (memory architecture)
+- https://docs.openclaw.ai/reference/memory-config (memory configuration)
+- https://docs.openclaw.ai/concepts/architecture (gateway architecture)
+- https://docs.openclaw.ai/concepts/context-engine (context engine)
+- https://docs.openclaw.ai/concepts/agent (agent runtime)
+- https://docs.openclaw.ai/channels (channel list)
+- https://docs.openclaw.ai/start/getting-started (installation)
+- https://docs.openclaw.ai/gateway (gateway docs)
+- https://docs.openclaw.ai/llms.txt (documentation index)
+- https://github.com/openclaw/openclaw (GitHub repository)
+- https://www.npmjs.com/package/openclaw (npm package)
+
+---
+Web research complete.

package/docs/start/clawmongo-getting-started.md

@@ -0,0 +1,287 @@
+# Getting Started with ClawMongo
+
+ClawMongo is the MongoDB edition of OpenClaw. This guide gets you from zero to a working personal AI assistant with MongoDB-native memory in about 10 minutes.
+
+---
+
+## Prerequisites
+
+### Required
+
+- **Node.js 22+** (24 recommended)
+- **MongoDB 7.0+** with mongot (MongoDB Community Search)
+- **Voyage AI API key** (for automated embeddings via mongot)
+- **LLM API key** (Anthropic Claude recommended, or OpenAI, Google, Mistral, etc.)
+
+### MongoDB Setup Options
+
+#### Option A: Docker (Quickest)
+
+Use the MongoDB Community image with mongot. Create a `docker-compose.yml`:
+
+```yaml
+version: "3.8"
+services:
+  mongodb:
+    image: mongodb/mongodb-community-server:latest
+    ports:
+      - "27017:27017"
+    volumes:
+      - mongodb_data:/data/db
+    command: ["--replSet", "rs0", "--bind_ip_all"]
+    environment:
+      - MONGODB_INIT_REPLICA_SET=true
+
+  mongot:
+    image: mongodb/mongodb-atlas-search:latest
+    depends_on:
+      - mongodb
+    environment:
+      - MONGOD_HOST=mongodb
+      - MONGOD_PORT=27017
+      - VOYAGE_API_KEY=${VOYAGE_API_KEY}
+
+volumes:
+  mongodb_data:
+```
+
+Start the services:
+
+```bash
+export VOYAGE_API_KEY="your-voyage-ai-key"
+docker compose up -d
+```
+
+Initialize the replica set (required for change streams):
+
+```bash
+docker exec -it $(docker compose ps -q mongodb) mongosh --eval "rs.initiate()"
+```
+
+#### Option B: Local Install (macOS/Linux)
+
+Install MongoDB Community and mongot using Homebrew (macOS) or your package manager:
+
+```bash
+# macOS
+brew tap mongodb/brew
+brew install mongodb-community
+brew install mongodb-atlas-cli
+
+# Start as a replica set (required for change streams)
+mongod --replSet rs0 --dbpath /usr/local/var/mongodb --logpath /usr/local/var/log/mongodb/mongod.log --fork
+mongosh --eval "rs.initiate()"
+```
+
+Install and configure mongot separately. See [MongoDB Community Search documentation](https://www.mongodb.com/docs/atlas/atlas-search/) for platform-specific instructions.
+
+#### Option C: MongoDB Atlas
+
+Create a free or paid cluster on [MongoDB Atlas](https://www.mongodb.com/atlas):
+
+1. Create a cluster (M0 free tier works for development)
+2. Enable Atlas Search on the cluster
+3. Configure the Voyage AI integration in Atlas Search settings
+4. Get the connection string from the Atlas dashboard
+
+---
+
+### Voyage AI Setup
+
+1. Sign up at [voyageai.com](https://www.voyageai.com)
+2. Generate an API key from the dashboard
+3. Configure the key in your mongot deployment (Docker env var, Atlas Search settings, or local config)
+
+ClawMongo uses `voyage-4-large` (1024 dimensions) for all embeddings. This is configured in the search index definitions, not in application code.
+
+---
+
+## Install ClawMongo
+
+```bash
+npm install -g @romiluz/clawmongo@latest
+# or
+pnpm add -g @romiluz/clawmongo@latest
+```
+
+Verify installation:
+
+```bash
+clawmongo --version
+```
+
+The `openclaw` command is also available as an alias for compatibility.
+
+---
+
+## Configure MongoDB Connection
+
+```bash
+# Set the MongoDB connection URI
+clawmongo config set memory.mongodb.uri "mongodb://localhost:27017/clawmongo?replicaSet=rs0"
+
+# Enable automated embeddings via mongot
+clawmongo config set memory.mongodb.embeddingMode "automated"
+```
+
+For Atlas, use the full connection string:
+
+```bash
+clawmongo config set memory.mongodb.uri "mongodb+srv://user:password@cluster.mongodb.net/clawmongo"
+```
+
+---
+
+## Run Onboarding
+
+```bash
+clawmongo onboard --install-daemon
+```
+
+The onboarding wizard walks you through:
+
+1. **Model provider selection** -- choose Anthropic, OpenAI, Google, or another supported provider
+2. **API key entry** -- enter your LLM provider API key
+3. **Gateway setup** -- configures the gateway daemon on port 18789
+4. **Collection bootstrap** -- creates all 20 MongoDB collections and 53 standard indexes
+5. **Search index creation** -- creates text and vector search indexes (requires mongot)
+
+The `--install-daemon` flag installs the gateway as a system service (launchd on macOS, systemd on Linux) so it stays running.
+
+---
+
+## Verify the Setup
+
+### Check gateway status
+
+```bash
+clawmongo gateway status
+```
+
+### Check channel connectivity
+
+```bash
+clawmongo channels status --probe
+```
+
+### Check MongoDB connection and memory health
+
+```bash
+clawmongo doctor
+```
+
+The doctor command verifies MongoDB connectivity, collection existence, index counts, and mongot availability.
+
+### Send a test message
+
+```bash
+clawmongo agent --message "Hello, remember that my name is Alice" --thinking low
+```
+
+Then verify memory was written:
+
+```bash
+clawmongo agent --message "What is my name?" --thinking low
+```
+
+---
+
+## Connect a Channel (Optional)
+
+Telegram is the quickest channel to set up:
+
+1. Create a bot via [@BotFather](https://t.me/BotFather) on Telegram
+2. Copy the bot token
+3. Configure it:
+
+```bash
+clawmongo config set channels.telegram.botToken "YOUR_BOT_TOKEN"
+```
+
+4. Restart the gateway:
+
+```bash
+clawmongo gateway restart
+```
+
+5. Send a message to your bot on Telegram
+
+For other channels (WhatsApp, Slack, Discord, etc.), see the [channel setup guides](https://docs.openclaw.ai/channels).
+
+---
+
+## Configuration Reference
+
+Minimal `~/.openclaw/openclaw.json` for ClawMongo:
+
+```json5
+{
+  agent: {
+    model: "anthropic/claude-opus-4-6"
+  },
+  memory: {
+    mongodb: {
+      uri: "mongodb://localhost:27017/clawmongo?replicaSet=rs0",
+      embeddingMode: "automated"
+    }
+  }
+}
+```
+
+For the full configuration reference: [docs.openclaw.ai/gateway/configuration](https://docs.openclaw.ai/gateway/configuration)
+
+For MongoDB-specific memory configuration: [docs/reference/memory-config.md](../reference/memory-config.md)
+
+---
+
+## Next Steps
+
+- **Import knowledge base documents**: Use `clawmongo kb import` to add reference material
+- **Configure structured memory**: The agent writes structured facts automatically during conversations
+- **Read the MongoDB capability deep-dive**: [docs/reference/mongodb-capabilities.md](../reference/mongodb-capabilities.md)
+- **Understand the architecture**: [docs/reference/heart-brain-boundary.md](../reference/heart-brain-boundary.md)
+- **Compare with default memory**: [docs/reference/clawmongo-vs-default-memory.md](../reference/clawmongo-vs-default-memory.md)
+- **Set up additional channels**: [docs.openclaw.ai/channels](https://docs.openclaw.ai/channels)
+
+---
+
+## Troubleshooting
+
+### MongoDB connection refused
+
+Verify MongoDB is running and accessible:
+
+```bash
+mongosh "mongodb://localhost:27017" --eval "db.runCommand({ ping: 1 })"
+```
+
+### Replica set not initialized
+
+Change streams require a replica set. Initialize it:
+
+```bash
+mongosh --eval "rs.initiate()"
+```
+
+### mongot not available
+
+If search index creation fails, verify mongot is running and connected to your MongoDB instance. ClawMongo falls back to BSON `$text` indexes when mongot is unavailable, but vector search requires mongot.
+
+### Voyage AI embedding errors
+
+Verify your Voyage AI API key is correctly configured in mongot. Test embedding generation:
+
+```bash
+curl -X POST "https://api.voyageai.com/v1/embeddings" \
+  -H "Authorization: Bearer YOUR_VOYAGE_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"input": "test", "model": "voyage-4-large"}'
+```
+
+### Run the doctor
+
+```bash
+clawmongo doctor
+```
+
+The doctor command checks for common configuration issues and provides actionable fix suggestions.

package/package.json

@@ -1,14 +1,35 @@
 {
   "name": "@romiluz/clawmongo",
-  "version": "2026.3.22",
-  "description": "MongoDB-first multi-channel agent runtime built on OpenClaw",
-  "keywords": [],
+  "version": "2026.3.24",
+  "description": "OpenClaw, but it remembers. Full AI assistant (22 channels, 78 extensions, voice, apps) with MongoDB memory - vector search, knowledge graph, event-sourcing, KB, and 8 retrieval paths. Nothing is ever lost.",
+  "keywords": [
+    "mongodb",
+    "ai-assistant",
+    "personal-ai",
+    "openclaw",
+    "agent-memory",
+    "vector-search",
+    "knowledge-graph",
+    "voyage-ai",
+    "multi-channel",
+    "whatsapp",
+    "telegram",
+    "discord",
+    "slack",
+    "event-sourcing",
+    "graphlookup",
+    "mongot",
+    "hybrid-search",
+    "episode-materialization",
+    "retrieval-planner",
+    "typescript"
+  ],
   "homepage": "https://github.com/romiluz13/ClawMongo#readme",
   "bugs": {
     "url": "https://github.com/romiluz13/ClawMongo/issues"
   },
   "license": "MIT",
-  "author": "",
+  "author": "Rom Iluz <rom@iluz.net>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/romiluz13/ClawMongo.git"