docs: add claude-mem integration setup guide
Full setup guide covering: - Clawdbot installation (quick install + manual) - Claude-Mem installation (plugin + standalone) - Plugin configuration - Testing and verification - Troubleshooting Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alex Newman
parent
f07fa66019
commit
8753360b5c
390
docs/guides/claude-mem-setup.md
Normal file
390
docs/guides/claude-mem-setup.md
Normal file
@ -0,0 +1,390 @@
|
||||
# Clawdbot + Claude-Mem Setup Guide
|
||||
|
||||
Complete setup guide for integrating Clawdbot with Claude-Mem persistent memory.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide walks you through:
|
||||
1. Installing Clawdbot (AI messaging gateway)
|
||||
2. Installing Claude-Mem (persistent memory system)
|
||||
3. Connecting them via the `memory-claudemem` plugin
|
||||
|
||||
**What you get:**
|
||||
- Clawdbot routes messages between you and AI across multiple channels (Telegram, Discord, WhatsApp, etc.)
|
||||
- Claude-Mem captures observations from every tool call and injects relevant context into future sessions
|
||||
- Progressive disclosure memory tools (`memory_search`, `memory_observations`)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Node.js 22+** (required for both Clawdbot and Claude-Mem)
|
||||
- **macOS, Linux, or Windows (WSL2)**
|
||||
- **Git** (for installing from source)
|
||||
|
||||
Check your Node version:
|
||||
```bash
|
||||
node -v
|
||||
# Should show v22.x.x or higher
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 1: Install Clawdbot
|
||||
|
||||
### Option A: Quick Install (Recommended)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://clawd.bot/install.sh | bash
|
||||
```
|
||||
|
||||
Windows (PowerShell):
|
||||
```powershell
|
||||
iwr -useb https://clawd.bot/install.ps1 | iex
|
||||
```
|
||||
|
||||
This:
|
||||
- Installs Node 22+ if needed
|
||||
- Installs `clawdbot` globally via npm
|
||||
- Runs the onboarding wizard
|
||||
|
||||
### Option B: Manual Install
|
||||
|
||||
If you already have Node 22+:
|
||||
|
||||
```bash
|
||||
npm install -g clawdbot@latest
|
||||
```
|
||||
|
||||
Then run onboarding:
|
||||
|
||||
```bash
|
||||
clawdbot onboard --install-daemon
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
|
||||
```bash
|
||||
clawdbot --version
|
||||
clawdbot doctor
|
||||
```
|
||||
|
||||
### Common Issue: "clawdbot not found"
|
||||
|
||||
If your shell can't find `clawdbot`, add npm's global bin to your PATH:
|
||||
|
||||
```bash
|
||||
# Add to ~/.zshrc or ~/.bashrc
|
||||
export PATH="$(npm prefix -g)/bin:$PATH"
|
||||
```
|
||||
|
||||
Then restart your terminal or run `source ~/.zshrc`.
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Install Claude-Mem
|
||||
|
||||
Claude-Mem is a separate system that provides persistent memory. You need to install it independently.
|
||||
|
||||
### Option A: Via Claude Code Plugin (if using Claude Code)
|
||||
|
||||
If you use Claude Code (Anthropic's CLI), install claude-mem as a plugin:
|
||||
|
||||
```bash
|
||||
# In a Claude Code session:
|
||||
/plugin marketplace add thedotmack/claude-mem
|
||||
/plugin install claude-mem
|
||||
```
|
||||
|
||||
Restart Claude Code. The worker starts automatically.
|
||||
|
||||
### Option B: Manual Installation (Standalone)
|
||||
|
||||
Clone the repository:
|
||||
|
||||
```bash
|
||||
cd ~/Scripts # or wherever you keep projects
|
||||
git clone https://github.com/thedotmack/claude-mem.git
|
||||
cd claude-mem
|
||||
```
|
||||
|
||||
Install dependencies and build:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
Start the worker:
|
||||
|
||||
```bash
|
||||
npm run worker
|
||||
# Or run in background:
|
||||
nohup npm run worker > /tmp/claude-mem-worker.log 2>&1 &
|
||||
```
|
||||
|
||||
### Verify Claude-Mem is Running
|
||||
|
||||
The worker runs on port 37777 by default.
|
||||
|
||||
```bash
|
||||
curl http://localhost:37777/api/health
|
||||
# Should return: OK or {"status":"ok"}
|
||||
```
|
||||
|
||||
Open the web viewer:
|
||||
```bash
|
||||
open http://localhost:37777
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 3: Enable the Memory-Claudemem Plugin
|
||||
|
||||
The `memory-claudemem` plugin connects Clawdbot to the Claude-Mem worker.
|
||||
|
||||
### Step 1: Disable Built-in Memory (Optional but Recommended)
|
||||
|
||||
Clawdbot has its own memory system. To avoid conflicts, disable it:
|
||||
|
||||
```bash
|
||||
clawdbot config set agents.defaults.memorySearch.enabled false
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
clawdbot config get agents.defaults.memorySearch.enabled
|
||||
# Should return: false
|
||||
```
|
||||
|
||||
### Step 2: Enable the Claude-Mem Plugin
|
||||
|
||||
The plugin is bundled in the `extensions/memory-claudemem` directory. Enable it:
|
||||
|
||||
```bash
|
||||
clawdbot config set plugins.memory-claudemem.workerUrl "http://localhost:37777"
|
||||
```
|
||||
|
||||
Optional: Adjust timeout (default 10 seconds):
|
||||
```bash
|
||||
clawdbot config set plugins.memory-claudemem.workerTimeout 15000
|
||||
```
|
||||
|
||||
### Step 3: Verify Plugin Status
|
||||
|
||||
Check the worker connection:
|
||||
|
||||
```bash
|
||||
clawdbot claude-mem status
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
✓ Worker running at http://localhost:37777
|
||||
```
|
||||
|
||||
If you see `✗ Worker not responding`, make sure Claude-Mem is running (see Part 2).
|
||||
|
||||
---
|
||||
|
||||
## Part 4: Test the Integration
|
||||
|
||||
### Test 1: Search Memories
|
||||
|
||||
```bash
|
||||
clawdbot claude-mem search "authentication"
|
||||
```
|
||||
|
||||
This queries Claude-Mem for observations matching "authentication".
|
||||
|
||||
### Test 2: Run an Agent with Memory
|
||||
|
||||
Send a test message through Clawdbot:
|
||||
|
||||
```bash
|
||||
clawdbot agent --message "List files in the current directory"
|
||||
```
|
||||
|
||||
This should:
|
||||
1. Execute the task
|
||||
2. Record the observation to Claude-Mem (fire-and-forget)
|
||||
3. Future queries will have this context injected
|
||||
|
||||
### Test 3: Verify Observation Recording
|
||||
|
||||
Open the Claude-Mem web viewer:
|
||||
```bash
|
||||
open http://localhost:37777
|
||||
```
|
||||
|
||||
You should see new observations for tool calls made by Clawdbot.
|
||||
|
||||
---
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### Full Config Example
|
||||
|
||||
Edit `~/.clawdbot/config.yml`:
|
||||
|
||||
```yaml
|
||||
# Disable built-in memory (use claude-mem instead)
|
||||
agents:
|
||||
defaults:
|
||||
memorySearch:
|
||||
enabled: false
|
||||
|
||||
# Enable claude-mem plugin
|
||||
plugins:
|
||||
memory-claudemem:
|
||||
workerUrl: http://localhost:37777
|
||||
workerTimeout: 10000
|
||||
```
|
||||
|
||||
### Rollback to Built-in Memory
|
||||
|
||||
If you want to switch back to Clawdbot's built-in memory:
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
defaults:
|
||||
memorySearch:
|
||||
enabled: true
|
||||
|
||||
plugins:
|
||||
memory-claudemem:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Available Tools
|
||||
|
||||
When the plugin is active, these tools are available to the AI agent:
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `memory_search` | Search past observations. Returns compact results with IDs. |
|
||||
| `memory_observations` | Get full details for specific observation IDs. |
|
||||
|
||||
### 3-Layer Workflow
|
||||
|
||||
1. **Search** (`memory_search`): Get index with IDs (~50-100 tokens/result)
|
||||
2. **Filter**: Review results, identify relevant IDs
|
||||
3. **Fetch** (`memory_observations`): Get full details (~500-1000 tokens/result)
|
||||
|
||||
This pattern saves ~10x tokens compared to fetching everything.
|
||||
|
||||
---
|
||||
|
||||
## CLI Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `clawdbot claude-mem status` | Check if the worker is responding |
|
||||
| `clawdbot claude-mem search <query>` | Search memories (JSON output) |
|
||||
|
||||
Options for search:
|
||||
```bash
|
||||
clawdbot claude-mem search "authentication" --limit 20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Worker Not Responding
|
||||
|
||||
1. Check if Claude-Mem is running:
|
||||
```bash
|
||||
curl http://localhost:37777/api/health
|
||||
```
|
||||
|
||||
2. If not running, start it:
|
||||
```bash
|
||||
cd ~/Scripts/claude-mem
|
||||
npm run worker
|
||||
```
|
||||
|
||||
3. Check logs:
|
||||
```bash
|
||||
tail -f /tmp/claude-mem-worker.log
|
||||
```
|
||||
|
||||
### Plugin Not Loading
|
||||
|
||||
1. Check plugin list:
|
||||
```bash
|
||||
clawdbot plugins list
|
||||
```
|
||||
|
||||
2. Look for `memory-claudemem` in the output.
|
||||
|
||||
3. If missing, check the config:
|
||||
```bash
|
||||
clawdbot config get plugins.memory-claudemem
|
||||
```
|
||||
|
||||
### No Observations Being Recorded
|
||||
|
||||
1. Enable debug logging:
|
||||
```bash
|
||||
clawdbot config set logging.level debug
|
||||
```
|
||||
|
||||
2. Run a command and check logs:
|
||||
```bash
|
||||
clawdbot agent --message "test"
|
||||
tail -f ~/.clawdbot/logs/gateway.log | grep claude-mem
|
||||
```
|
||||
|
||||
### Context Not Being Injected
|
||||
|
||||
1. Check that there are observations in Claude-Mem (via web UI at http://localhost:37777)
|
||||
2. Ensure the prompt is longer than 5 characters (short prompts skip injection)
|
||||
3. Check logs for "injecting X memories into context"
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ Clawdbot │ │ Claude-Mem │
|
||||
│ Gateway │ │ Worker │
|
||||
├──────────────────┤ ├──────────────────┤
|
||||
│ │ │ │
|
||||
│ before_agent │────▶│ context inject │
|
||||
│ after_tool_call │────▶│ POST /observe │
|
||||
│ │ │ │
|
||||
│ memory_search │────▶│ GET /search │
|
||||
│ memory_observations──▶│ POST /batch │
|
||||
│ │ │ │
|
||||
└──────────────────┘ └──────────────────┘
|
||||
│ │
|
||||
└────────────────────────┘
|
||||
http://localhost:37777
|
||||
```
|
||||
|
||||
**Hooks:**
|
||||
- `before_agent_start`: Injects relevant memories as context
|
||||
- `after_tool_call`: Records observations (fire-and-forget)
|
||||
|
||||
**Tools:**
|
||||
- `memory_search`: Queries Claude-Mem's search API
|
||||
- `memory_observations`: Fetches full observation details
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Set up messaging channels**: `clawdbot channels add telegram` (or discord, slack, etc.)
|
||||
- **Configure the AI model**: `clawdbot config set agents.defaults.model claude-sonnet-4-20250514`
|
||||
- **Start the gateway**: `clawdbot gateway run`
|
||||
- **Open the dashboard**: `clawdbot dashboard`
|
||||
|
||||
For more information:
|
||||
- Clawdbot docs: https://docs.clawd.bot
|
||||
- Claude-Mem docs: https://docs.claude-mem.ai
|
||||
Loading…
Reference in New Issue
Block a user