# AgentMemory Installation Prompt for OpenClaw
**Updated: May 2026** — iii 0.12.0, agentmemory 0.9.21+
---
## Install AgentMemory MCP Server
Install agentmemory — a persistent cross-session memory server. Follow these steps **exactly in order**. Do NOT edit `openclaw.json` manually at any point.
### Step 1: Install the iii engine (required dependency)
```bash
mkdir -p ~/.local/bin
curl -fsSL "https://github.com/iii-hq/iii/releases/download/iii/v0.12.0/iii-x86_64-unknown-linux-gnu.tar.gz" | tar -xz -C ~/.local/bin
chmod +x ~/.local/bin/iii
~/.local/bin/iii --version
```
Expected output: `0.12.0`
> **Note:** agentmemory internally pins `
[email protected]` regardless of the engine version. The iii engine 0.12.0 is backward-compatible.
### Step 2: Create a systemd service for the memory server
**Check how OpenClaw runs first:**
```bash
ls ~/.config/systemd/user/openclaw-gateway.service 2>/dev/null && echo "USER-LEVEL" || echo "SYSTEM-LEVEL"
```
#### Option A: User-level systemd (recommended if OpenClaw uses user systemd)
```bash
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/agentmemory.service << 'EOF'
[Unit]
Description=AgentMemory Server
After=network.target
[Service]
Type=simple
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
Environment=HOME=%h
Environment=NODE_ENV=production
ExecStart=/usr/bin/npx @agentmemory/agentmemory
Restart=on-failure
RestartSec=15
KillMode=mixed
TimeoutStopSec=10
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable agentmemory.service
systemctl --user start agentmemory.service
# CRITICAL: Enable linger so service survives SSH disconnect + reboot
sudo loginctl enable-linger $(whoami)
```
> **Why `KillMode=mixed` and `TimeoutStopSec=10`:** agentmemory spawns iii-engine as a child process. Default systemd kill behavior can leave orphan iii processes that reconnect forever and eat CPU.
#### Option B: System-level systemd
```bash
sudo tee /etc/systemd/system/agentmemory.service > /dev/null << 'EOF'
[Unit]
Description=AgentMemory Server
After=network.target
[Service]
Type=simple
User=REPLACE_WITH_YOUR_USER
WorkingDirectory=/home/REPLACE_WITH_YOUR_USER
Environment=PATH=/home/REPLACE_WITH_YOUR_USER/.local/bin:/usr/local/bin:/usr/bin:/bin
Environment=NODE_ENV=production
ExecStart=/usr/bin/npx @agentmemory/agentmemory
Restart=on-failure
RestartSec=15
KillMode=mixed
TimeoutStopSec=10
[Install]
WantedBy=multi-user.target
EOF
```
**Replace `REPLACE_WITH_YOUR_USER` with actual username** (run `whoami`).
```bash
sudo systemctl daemon-reload
sudo systemctl enable agentmemory
sudo systemctl start agentmemory
```
#### Verify (both options):
Wait 5 seconds, then:
```bash
curl -s http://localhost:3111/agentmemory/health | python3 -c "import json,sys; d=json.load(sys.stdin); print('Status:', d['status'], '| Version:', d['version'])"
```
Expected: `Status: healthy | Version: 0.9.21`
### Step 3: Register MCP server in OpenClaw
⚠️ **CRITICAL: Use the CLI command ONLY. NEVER edit openclaw.json manually!**
```bash
openclaw mcp set agentmemory '{"command":"npx","args":["-y","@agentmemory/mcp"]}'
```
Verify:
```bash
openclaw mcp list
```
Expected: `- agentmemory`
⚠️ **Do NOT use the plugins integration** (`integrations/openclaw` folder). It requires `plugins.slots.memory` and `plugins.entries` in `openclaw.json`, which triggers config clobber on restart. The MCP-only approach works perfectly.
### Step 4: Restart gateway
```bash
openclaw gateway restart
```
Wait 10 seconds, then verify only ONE gateway process:
```bash
ps aux | grep "openclaw.*gateway" | grep -v grep | wc -l
```
Expected: `1`
If you see `2` or more — duplicate processes. Fix:
```bash
pkill -f openclaw-gateway
sleep 5
openclaw gateway start
```
### Step 5: Final verification
```bash
echo "=== Memory server ==="
curl -s http://localhost:3111/agentmemory/health | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['status'])"
echo "=== MCP registered ==="
openclaw mcp list 2>&1 | grep agentmemory
echo "=== Gateway (should be 1) ==="
ps aux | grep "openclaw.*gateway" | grep -v grep | wc -l
```
All three should show: `healthy`, `agentmemory`, `1`
### Viewer
Open `http://localhost:3113` in browser to see stored memories.
---
## 🚨 IMPORTANT: Two Modes (Don't Get Confused)
AgentMemory has TWO modes:
1. **MCP standalone shim** (`npx @agentmemory/mcp`) — lightweight, writes to `~/.agentmemory/standalone.json`, NO session indexing, NO compression, NO consolidation
2. **Full REST server** (`npx @agentmemory/agentmemory`) — runs on port 3111, has session indexing, compression, consolidation, knowledge graph, embeddings
OpenClaw's MCP config runs the **shim** by default. The systemd service in Step 2 runs the **full server**. Both must be running.
If `memory_save` works but memories don't persist across sessions, add `AGENTMEMORY_URL` to MCP config:
```bash
openclaw mcp set agentmemory '{"command":"npx","args":["-y","@agentmemory/mcp"],"env":{"AGENTMEMORY_URL":"http://localhost:3111"}}'
```
---
## 🔧 First-Run Wizard
On first run, `npx @agentmemory/agentmemory` shows an interactive wizard. In a non-interactive systemd context, it exits immediately.
**Fix:** Run manually once via tmux:
```bash
tmux new-session -d -s agentmemory 'npx @agentmemory/agentmemory'
tmux attach -t agentmemory
# Complete the wizard, then Ctrl-C
# Creates ~/.agentmemory/preferences.json — prevents future wizard
```
> ℹ️ **v0.9.21+ fix:** CLI now skips onboarding prompts in non-TTY contexts automatically.
---
## 🔧 LLM Provider Config
**Without LLM key:** BM25-only mode (keyword search, no compression/consolidation).
**With LLM key:** Full semantic search, compression, consolidation, knowledge graph.
Edit `~/.agentmemory/.env`:
```bash
# Anthropic (direct or Azure)
ANTHROPIC_API_KEY=***
ANTHROPIC_BASE_URL=https://your-endpoint.openai.azure.com/anthropic
ANTHROPIC_MODEL=claude-sonnet-4-20250514
# Local embeddings (no external API needed)
EMBEDDING_PROVIDER=local
# Enable all features
AGENTMEMORY_AUTO_COMPRESS=true
CONSOLIDATION_ENABLED=true
AGENTMEMORY_INJECT_CONTEXT=true
GRAPH_EXTRACTION_ENABLED=true
AGENTMEMORY_TOOLS=all
```
Then restart:
```bash
systemctl --user restart agentmemory.service
```
---
## 📊 Ports
| Port | Service | Purpose |
|------|---------|---------|
| 3111 | iii REST API | Memory CRUD, search |
| 3112 | iii Streams | WebSocket live events |
| 3113 | Viewer | Web dashboard UI |
All listen on localhost only. Access remotely via SSH tunnel:
```bash
ssh -L 3111:127.0.0.1:3111 -L 3112:127.0.0.1:3112 -L 3113:127.0.0.1:3113 user@server
```
---
## ⚠️ Known Viewer Issues (v0.9.20–0.9.21)
When you open the Viewer (port 3113), you'll see these console errors:
1. **`POST /agentmemory/graph/build` 404** — Viewer has a "Rebuild Graph" button but the REST endpoint doesn't exist yet. Graph extraction works internally on new observations. PR #533 open.
2. **WebSocket `mem-live/viewer` 404** — Viewer tries to open a live-stream WebSocket on port 3112. The stream path isn't registered. Status shows "■ CONNECTING..." — it retries forever but never connects.
3. **`agentmemory connect` writes wrong config key** — It writes `mcpServers` at root instead of `mcp.servers`. This **crashes the gateway**. Always use `openclaw mcp set` instead.
**Impact:** Zero on core functionality. These are cosmetic Viewer UI issues only.
---
## ⛔ LESSONS LEARNED
1. **NEVER add `mcpServers` or `mcp.servers` directly to `openclaw.json`** — schema validation clobbers unknown keys on restart.
2. **NEVER edit `openclaw.json` manually for MCP** — always `openclaw mcp set/unset`.
3. **NEVER add `plugins.allow` manually** — let OpenClaw manage it.
4. **After gateway restart, ALWAYS check process count** — duplicates break Telegram/channels.
5. **Install `iii` engine BEFORE starting agentmemory**.
6. **ClawHub has a DIFFERENT "agentmemory"** — `clawhub install agentmemory` = agentmemory.cloud (paid). The GitHub repo (`rohitg00/agentmemory`) is self-hosted and free.
7. **iii-engine crashes silently** — systemd says "active" but health endpoint dies. Fix: restart the service.
8. **Config clobber creates `.clobbered` files** — check `ls ~/.openclaw/*.clobbered*` if changes vanish.
9. **iii-sdk version mismatch** — `
[email protected]` introduced a routing regression (all `/agentmemory/*` routes returned 404). agentmemory 0.9.22+ pins `iii-sdk` to exact `0.11.2`. If you hit 404s on health endpoint, check `npm ls iii-sdk` inside the agentmemory package.
10. **Large corpora boot delay** — Fixed in 0.9.21+. `rebuildIndex` now runs in background (was blocking boot for 25h+ on 250k observations). If stuck on older version, upgrade.
---
## 🗑️ Full Uninstall
```bash
# User-level
systemctl --user stop agentmemory
systemctl --user disable agentmemory
rm ~/.config/systemd/user/agentmemory.service
systemctl --user daemon-reload
# OR system-level
sudo systemctl stop agentmemory
sudo systemctl disable agentmemory
sudo rm /etc/systemd/system/agentmemory.service
sudo systemctl daemon-reload
# Remove MCP (via CLI!)
openclaw mcp unset agentmemory
# Cleanup
rm -rf ~/.openclaw/extensions/agentmemory
rm -f ~/.local/bin/iii
pkill -f agentmemory 2>/dev/null
pkill -f iii 2>/dev/null
# Restart gateway
pkill -f openclaw-gateway
sleep 5
openclaw gateway start
```