agentmemory Integration for OpenClaw

Status: ✅ Verified working with OpenClaw v2026.5.4 Version: agentmemory v0.9.9 (iii-engine v0.11.6) MCP Tools: 107 REST + 51 MCP tools available

Persistent memory server giving OpenClaw agents 95.2% R@5 semantic recall across sessions via BM25+Vector+Graph RRF hybrid search.

Architecture

OpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)
                                              ↓
                                         SQLite/KV Store
                                              ↓
                                      Viewer (localhost:3113)

Quick Start (MCP Mode — 5 minutes)

Step 1: Install and start memory server

# Server runs on localhost:3111, viewer at localhost:3113
npx @agentmemory/agentmemory

Step 2: Configure OpenClaw MCP

Add to ~/.openclaw/openclaw.json under mcp.servers:

{
  "mcp": {
    "servers": {
      "agentmemory": {
        "command": "npx",
        "args": ["-y", "@agentmemory/mcp"]
      }
    }
  }
}

Step 3: Restart Gateway

openclaw gateway restart

Step 4: Verify

curl http://localhost:3111/agentmemory/health
# → {"status":"healthy","version":"0.9.9"}

# View memory dashboard
open http://localhost:3113

MCP Tools (Key ones for OpenClaw)

See references/mcp-tools.md for full list of 51 tools.

systemd Service (Production)

For auto-start and reliable background operation:

Install service

mkdir -p ~/.config/systemd/user
cp /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/agentmemory.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable agentmemory
systemctl --user start agentmemory

# Enable linger (boot without login)
loginctl enable-linger $(whoami)

Service commands

systemctl --user status agentmemory   # Check status
journalctl --user -u agentmemory -f   # View logs
systemctl --user restart agentmemory  # Restart

Integration with MEMORY.md

agentmemory and MEMORY.md serve different purposes — they coexist:

Coordination rules

• Before major tasks: Call memory_recall to retrieve relevant experiences
• After important decisions: Call memory_save with result
• Curated knowledge: Stays in MEMORY.md (survives compaction)
• Session start: Both systems loaded; no conflicts

After installation: migrate MEMORY.md (important!)

After completing installation, strongly recommend migrating MEMORY.md content into agentmemory:

1. Open the dashboard to view current state

   open http://localhost:3113
   

   Initially empty — migration populates it with searchable data.

2. Migrate MEMORY.md content Since migrate --from-file CLI is not yet available, migrate by:

   • Asking the lobster agent to migrate content for you
   • Or manually calling memory_save for key entries from MEMORY.md

3. Verify migration results After migration, reopen http://localhost:3113 to confirm data is stored.

Note: MEMORY.md stays intact — both systems coexist. agentmemory handles semantic search; MEMORY.md holds curated knowledge.

Verification

Run the verification script:

bash /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/verify.sh

Expected output:

• ✅ Memory server on port 3111
• ✅ Health endpoint responding
• ✅ Viewer available on port 3113
• ✅ OpenClaw MCP configured
• ✅ systemd service active

Uninstall

MCP mode removal

1. Remove from openclaw.json mcp.servers section
2. openclaw gateway restart

Full removal

systemctl --user stop agentmemory
systemctl --user disable agentmemory
rm ~/.config/systemd/user/agentmemory.service
pkill -f "agentmemory"

Troubleshooting

"Connection refused on port 3111"

Memory server not running. Start it:

systemctl --user start agentmemory
# Or manually: npx @agentmemory/agentmemory

"Config invalid" after editing openclaw.json

Ensure mcp.servers path (not mcpServers). Run:

openclaw status  # Should show "Config valid"

View real-time logs

journalctl --user -u agentmemory -f --since "1 hour ago"

中文版 Chinese Version

agentmemory × OpenClaw 集成

状态: ✅ 已验证兼容 OpenClaw v2026.5.4 版本: agentmemory v0.9.9（引擎 iii v0.11.6） MCP 工具: 107 个 REST + 51 个 MCP 工具

持久化记忆服务，为 OpenClaw Agent 提供跨会话语义召回能力（R@5 95.2%），基于 BM25+向量+图谱混合搜索。

系统架构

OpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP 服务器 (localhost:3111)
                                              ↓
                                          SQLite/KV 存储
                                              ↓
                                        浏览器仪表板 (localhost:3113)

快速开始（MCP 模式 — 5 分钟）

第一步：启动记忆服务器

npx @agentmemory/agentmemory
# 服务器端口：3111（API）、3113（浏览器仪表板）

第二步：配置 OpenClaw MCP

在 ~/.openclaw/openclaw.json 中加入：

{
  "mcp": {
    "servers": {
      "agentmemory": {
        "command": "npx",
        "args": ["-y", "@agentmemory/mcp"]
      }
    }
  }
}

第三步：重启 Gateway

openclaw gateway restart

第四步：验证

curl http://localhost:3111/agentmemory/health
# → {"status":"healthy","version":"0.9.9"}

# 打开记忆仪表板
open http://localhost:3113

核心 MCP 工具

完整 51 个工具列表见 references/mcp-tools.md。

systemd 服务（生产环境推荐）

安装服务：

mkdir -p ~/.config/systemd/user
cp /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/agentmemory.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable agentmemory
systemctl --user start agentmemory

# 启用 linger（开机免登录自动启动）
loginctl enable-linger $(whoami)

常用命令：

systemctl --user status agentmemory   # 查看状态
journalctl --user -u agentmemory -f  # 实时日志
systemctl --user restart agentmemory  # 重启

与 MEMORY.md 的协同

两个系统分工不同，共存互补：

协调规则：

• 任务开始前 → 调用 memory_recall 检索相关经验
• 重要决策后 → 调用 memory_save 保存结果
• 精选知识 → 留在 MEMORY.md（不受会话压缩影响）
• 会话启动时 → 两个系统同时加载，无冲突

首次安装后：迁移 MEMORY.md（重要！）

安装完成后，强烈建议将 MEMORY.md 的核心内容迁移到 agentmemory：

1. 打开仪表板查看当前状态

   open http://localhost:3113
   

   初始是空的，迁移后才有数据可搜。

2. 手动迁移 MEMORY.md 内容 由于 migrate --from-file CLI 命令暂不可用，请通过以下方式迁移核心内容：

   • 在 OpenClaw 对话中让龙虾帮你迁移
   • 或手动调 memory_save 保存 MEMORY.md 中的重要条目

3. 验证迁移结果 迁移完成后，再次打开 http://localhost:3113 查看记忆仪表板，确认数据已入库。

注意：MEMORY.md 本身保留不动，两套系统共存 — agentmemory 负责语义搜索，MEMORY.md 负责手工精修知识。

验证

bash /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/verify.sh

预期结果：

• ✅ 记忆服务器在 3111 端口运行
• ✅ Health 端点正常响应
• ✅ 仪表板在 3113 端口可访问
• ✅ OpenClaw MCP 已配置
• ✅ systemd 服务已激活

卸载

仅移除 MCP 模式：

1. 从 openclaw.json 的 mcp.servers 中删除 agentmemory 条目
2. 执行 openclaw gateway restart

完全移除：

systemctl --user stop agentmemory
systemctl --user disable agentmemory
rm ~/.config/systemd/user/agentmemory.service
pkill -f "agentmemory"

故障排查

"Connection refused on port 3111" 服务器未启动，启动它：

systemctl --user start agentmemory
# 或手动：npx @agentmemory/agentmemory

修改 openclaw.json 后提示 "Config invalid" 确保路径是 mcp.servers（不是 mcpServers）：

openclaw status  # 应显示 "Config valid"

查看实时日志：

journalctl --user -u agentmemory -f --since "1 hour ago"

实际带来的好处

🦞 Skill by 龙虾 — agentmemory-mcp on ClawHub: https://clawhub.ai/lufei4/agentmemory-mcp