openclaw · howlonghasitBen · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -28,6 +28,10 @@ Feature/ops docs (already present):
 - `docs/diffing.md`: version-to-version diff UI spec.
 - `docs/manual-testing.md`: CLI smoke scripts.
 
+Integration guides:
+
+- `docs/claude-mem-integration.md`: using claude-mem with OpenClaw for token savings.
+
 Docs tooling:
 
 - `docs/mintlify.md`: publish these docs with Mintlify.
diff --git a/docs/claude-mem-integration.md b/docs/claude-mem-integration.md
@@ -0,0 +1,118 @@
+# Using claude-mem with OpenClaw
+
+This guide explains how to integrate [claude-mem](https://github.com/thedotmack/claude-mem) with OpenClaw to reduce token usage through persistent memory compression.
+
+## Overview
+
+claude-mem is a Claude Code plugin that:
+- Captures everything Claude does during coding sessions
+- Compresses context with AI
+- Injects relevant history into future sessions
+- Reduces token usage ~10x via progressive disclosure
+
+When combined with OpenClaw's agent capabilities, this creates a powerful memory system that persists across sessions.
+
+## Installation
+
+### As an OpenClaw Skill
+
+```bash
+# Install via ClawHub (when available)
+clawhub install claude-mem
+
+# Or manually - creates ~/.claude/plugins/marketplaces/thedotmack/
+cd ~/.claude/plugins/marketplaces
+git clone https://github.com/thedotmack/claude-mem.git thedotmack
+cd thedotmack
+npm install
+```
+
+> **Note:** The `thedotmack` directory name is the marketplace namespace. The plugin code lives inside it.
+
+### Configuration
+
+Settings at `~/.claude-mem/settings.json`:
+
+```json
+{
+  "model": "claude-sonnet-4-latest",
+  "workerPort": 37777,
+  "dataDir": "~/.claude-mem/data",
+  "logLevel": "info",
+  "contextInjection": {
+    "enabled": true,
+    "maxTokens": 4000
+  }
+}
+```
+
+> **Note:** Replace `claude-sonnet-4-latest` with your preferred model identifier (e.g., `claude-sonnet-4-20250514`).
+
+## How It Works with OpenClaw
+
+### Token Savings Pattern
+
+claude-mem uses a 3-layer search pattern that integrates well with OpenClaw's session management:
+
+```
+1. search         → Compact index (~50-100 tokens/result)
+2. timeline       → Chronological context around results  
+3. get_observations → Full details ONLY for filtered IDs (~500-1000 tokens/result)
+```
+
+This is ~10x more efficient than loading full context every time.
+
+### Integration Points
+
+| Component | claude-mem | OpenClaw |
+|-----------|------------|----------|
+| Memory Storage | SQLite + Chroma | MEMORY.md + memory/*.md |
+| Session Context | Lifecycle hooks | Workspace files |
+| Search | MCP tools | memory_search |
+| Token Optimization | Progressive disclosure | Conversation compaction |
+
+### Complementary Use
+
+1. **claude-mem** handles Claude Code session memory (tool calls, code changes)
+2. **OpenClaw** handles conversational memory (MEMORY.md, daily logs)
+3. Together they provide comprehensive context without token bloat
+
+## SKILL.md Template
+
+For skill authors who want to package claude-mem for ClawHub:
+
+```markdown
+---
+name: claude-mem
+description: Persistent memory compression for Claude Code. Automatically captures session context, compresses with AI, and injects relevant history into future sessions.
+homepage: https://github.com/thedotmack/claude-mem
+metadata:
+  openclaw:
+    emoji: "🧠"  # Emoji supported in SKILL.md frontmatter
+    requires:
+      bins: ["node", "npm", "claude"]
+---
+
+# claude-mem
+
+[Skill documentation here...]
+```
+
+## Web Viewer
+
+Access the memory stream at `http://localhost:37777` to:
+- View real-time observations
+- Browse session history
+- Search past context
+- Configure settings
+
+## Resources
+
+- [claude-mem GitHub](https://github.com/thedotmack/claude-mem)
+- [claude-mem Documentation](https://docs.claude-mem.ai)
+- [OpenClaw Documentation](https://docs.openclaw.ai) — Official OpenClaw docs
+- [OpenClaw Discord](https://discord.com/invite/clawd) — Community support
+
+## License
+
+claude-mem is AGPL-3.0 licensed. See the [LICENSE](https://github.com/thedotmack/claude-mem/blob/main/LICENSE) for details.
diff --git a/skills/claude-mem/SKILL.md b/skills/claude-mem/SKILL.md
@@ -0,0 +1,141 @@
+---
+name: claude-mem
+description: Persistent memory compression for Claude Code. Automatically captures session context, compresses with AI, and injects relevant history into future sessions. Reduces token usage ~10x via progressive disclosure search pattern.
+homepage: https://github.com/thedotmack/claude-mem
+metadata:
+  openclaw:
+    emoji: "🧠"
+    requires:
+      bins: ["node", "npm", "claude"]
+---
+
+# claude-mem
+
+Persistent memory compression system for Claude Code. Captures everything Claude does, compresses it with AI, and injects relevant context back into future sessions.
+
+## Features
+
+- 🧠 **Persistent Memory** - Context survives across sessions
+- 📊 **Progressive Disclosure** - Layered retrieval saves ~10x tokens
+- 🔍 **Semantic Search** - Query project history with natural language
+- 🖥️ **Web Viewer** - Real-time memory stream at http://localhost:37777
+- 🔒 **Privacy Control** - Tag-based exclusion from storage
+
+## Install
+
+### Via Claude Code Plugin (Recommended)
+
+```bash
+# In Claude Code session:
+/plugin marketplace add thedotmack/claude-mem
+/plugin install claude-mem
+```
+
+Then restart Claude Code.
+
+### Manual Install
+
+```bash
+cd ~/.claude/plugins/marketplaces
+git clone https://github.com/thedotmack/claude-mem.git thedotmack
+cd thedotmack && npm install
+```
+
+### Register with Claude Code (Required!)
+
+After install, register the marketplace so Claude Code recognizes the plugin:
+
+```bash
+# Run the install script (does this automatically)
+~/.openclaw/skills/claude-mem/scripts/install.sh
+
+# Or manually add to ~/.claude/plugins/known_marketplaces.json:
+# "thedotmack": {"source": {"source": "github", "repo": "thedotmack/claude-mem"}, ...}
+```
+
+This ensures all Claude Code sessions (including OpenClaw-spawned coding agents) use claude-mem.
+
+## How It Works
+
+1. **5 Lifecycle Hooks** capture tool usage, prompts, and session events
+2. **Worker Service** (port 37777) provides HTTP API and web viewer
+3. **SQLite + Chroma** store sessions, observations, and vector embeddings
+4. **MCP Search Tools** enable intelligent context retrieval
+
+## Search Pattern (Token Efficient)
+
+The 3-layer workflow saves ~10x tokens:
+
+```
+1. search      → Get compact index (~50-100 tokens/result)
+2. timeline    → Get chronological context around results
+3. get_observations → Fetch full details ONLY for filtered IDs
+```
+
+Example:
+```javascript
+// Step 1: Search index
+search(query="authentication bug", type="bugfix", limit=10)
+
+// Step 2: Review, identify relevant IDs (#123, #456)
+
+// Step 3: Fetch full details
+get_observations(ids=[123, 456])
+```
+
+## Configuration
+
+Settings at `~/.claude-mem/settings.json`:
+
+```json
+{
+  "model": "claude-sonnet-4-20250514",
+  "workerPort": 37777,
+  "dataDir": "~/.claude-mem/data",
+  "logLevel": "info"
+}
+```
+
+## Web Viewer
+
+Access at http://localhost:37777 to:
+- View real-time memory stream
+- Browse sessions and observations
+- Search history
+- Configure settings
+- Switch between stable/beta versions
+
+## MCP Tools
+
+| Tool | Purpose | Tokens |
+|------|---------|--------|
+| `search` | Query memory index | ~50-100/result |
+| `timeline` | Chronological context | ~100-200/result |
+| `get_observations` | Full observation details | ~500-1000/result |
+
+## Troubleshooting
+
+Describe issues to Claude - the `troubleshoot` skill auto-diagnoses.
+
+Common fixes:
+```bash
+# Restart worker
+curl http://localhost:37777/api/restart
+
+# Check status
+curl http://localhost:37777/api/status
+
+# View logs
+tail -f ~/.claude-mem/logs/worker.log
+```
+
+## Resources
+
+- [Documentation](https://docs.claude-mem.ai)
+- [GitHub](https://github.com/thedotmack/claude-mem)
+- [Discord](https://discord.com/invite/J4wttp9vDu)
+- [@Claude_Memory](https://x.com/Claude_Memory)
+
+## License
+
+AGPL-3.0 - See [LICENSE](https://github.com/thedotmack/claude-mem/blob/main/LICENSE)
diff --git a/skills/claude-mem/scripts/install.sh b/skills/claude-mem/scripts/install.sh
@@ -0,0 +1,106 @@
+#!/bin/bash
+# claude-mem installer for OpenClaw
+
+set -e
+
+echo "🧠 Installing claude-mem..."
+
+# Check dependencies
+command -v node >/dev/null 2>&1 || { echo "❌ Node.js required"; exit 1; }
+command -v npm >/dev/null 2>&1 || { echo "❌ npm required"; exit 1; }
+command -v claude >/dev/null 2>&1 || { echo "⚠️ Claude Code CLI not found - install manually"; }
+
+# Create plugins directory
+PLUGINS_DIR="$HOME/.claude/plugins/marketplaces"
+mkdir -p "$PLUGINS_DIR"
+
+# Clone or update repo
+if [ -d "$PLUGINS_DIR/thedotmack" ]; then
+  echo "📦 Updating existing installation..."
+  cd "$PLUGINS_DIR/thedotmack"
+  git pull
+else
+  echo "📦 Cloning claude-mem..."
+  cd "$PLUGINS_DIR"
+  git clone https://github.com/thedotmack/claude-mem.git thedotmack
+fi
+
+# Install dependencies
+cd "$PLUGINS_DIR/thedotmack"
+echo "📦 Installing npm dependencies..."
+npm install
+
+# Register marketplace with Claude Code so it recognizes the plugin
+echo "📝 Registering marketplace with Claude Code..."
+KNOWN_MARKETPLACES="$HOME/.claude/plugins/known_marketplaces.json"
+
+# Create or update known_marketplaces.json
+if [ -f "$KNOWN_MARKETPLACES" ]; then
+  # Check if thedotmack already registered using jq for proper JSON parsing
+  if command -v jq >/dev/null 2>&1 && jq -e '.thedotmack' "$KNOWN_MARKETPLACES" >/dev/null 2>&1; then
+    echo "  ✓ Marketplace already registered"
+  elif grep -q '"thedotmack"' "$KNOWN_MARKETPLACES" 2>/dev/null; then
+    echo "  ✓ Marketplace already registered"
+  else
+    # Add thedotmack to existing file using jq or fallback
+    if command -v jq >/dev/null 2>&1; then
+      jq '. + {"thedotmack": {"source": {"source": "github", "repo": "thedotmack/claude-mem"}, "installLocation": "'"$PLUGINS_DIR/thedotmack"'", "lastUpdated": "'"$(date -Iseconds)"'"}}' "$KNOWN_MARKETPLACES" > "$KNOWN_MARKETPLACES.tmp"
+      mv "$KNOWN_MARKETPLACES.tmp" "$KNOWN_MARKETPLACES"
+      echo "  ✓ Added to existing marketplaces"
+    else
+      echo "  ⚠️ jq not found - creating fresh marketplaces file"
+      cat > "$KNOWN_MARKETPLACES" << EOF
+{
+  "thedotmack": {
+    "source": {"source": "github", "repo": "thedotmack/claude-mem"},
+    "installLocation": "$PLUGINS_DIR/thedotmack",
+    "lastUpdated": "$(date -Iseconds)"
+  }
+}
+EOF
+    fi
+  fi
+else
+  # Create new file
+  cat > "$KNOWN_MARKETPLACES" << EOF
+{
+  "thedotmack": {
+    "source": {"source": "github", "repo": "thedotmack/claude-mem"},
+    "installLocation": "$PLUGINS_DIR/thedotmack",
+    "lastUpdated": "$(date -Iseconds)"
+  }
+}
+EOF
+  echo "  ✓ Created marketplaces registry"
+fi
+
+# Create default config if not exists
+CONFIG_DIR="$HOME/.claude-mem"
+mkdir -p "$CONFIG_DIR"
+
+if [ ! -f "$CONFIG_DIR/settings.json" ]; then
+  echo "⚙️ Creating default config..."
+  cat > "$CONFIG_DIR/settings.json" << 'EOF'
+{
+  "model": "claude-sonnet-4-20250514",
+  "workerPort": 37777,
+  "dataDir": "~/.claude-mem/data",
+  "logLevel": "info",
+  "contextInjection": {
+    "enabled": true,
+    "maxTokens": 4000
+  }
+}
+EOF
+fi
+
+echo ""
+echo "✅ claude-mem installed and registered!"
+echo ""
+echo "Next steps:"
+echo "  1. Restart Claude Code"
+echo "  2. Web viewer: http://localhost:37777"
+echo "  3. Config: ~/.claude-mem/settings.json"
+echo ""
+echo "All new Claude Code sessions (including OpenClaw-spawned) will use claude-mem automatically."
+echo ""