agentmemory-mcp

Persistent cross-session memory for OpenClaw via agentmemory. Use when: User asks to install/configure agentmemory for OpenClaw Agent needs to remember project context, decisions, or workflows across sessions Setting up long-term memory for OpenClaw (MCP mode) Integrating agentmemory with existing MEMORY.md system Troubleshooting agentmemory connection issues Upgrading or removing agentmemory ─────────────────────────────── 基于 agentmemory 的跨会话持久化记忆系统，适用于 OpenClaw。适用场景：用户要求安装/配置 agentmemory Agent 需要记住项目背景、决策或工作流程为 OpenClaw 设置长期记忆（MCP 模式）与现有 MEMORY.md 系统集成排查 agentmemory 连接问题升级或移除 agentmemory

刘士江@lufei4

Install

openclaw skills install @lufei4/agentmemory-mcp

agentmemory Integration for OpenClaw

Status: ✅ Verified working with OpenClaw v2026.5.4 Version: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6 MCP Tools: 107 REST + 51 MCP tools available

Persistent memory server giving OpenClaw agents cross-session semantic recall via BM25+Vector+Graph RRF hybrid search.

Architecture

text

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

bash

# 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:

json

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

Step 3: Restart Gateway

bash

openclaw gateway restart

Step 4: Verify

bash

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

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

systemd Service (Production)

For auto-start and reliable background operation:

Install service

bash

mkdir -p ~/.config/systemd/user
cp ./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

bash

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

Service environment variables

Variable	Value	Purpose
`NODE_ENV`	`production`	Production mode
`AGENTMEMORY_PORT`	`3111`	MCP API port
`AGENTMEMORY_VIEWER_PORT`	`3113`	Dashboard port
`AGENTMEMORY_III_VERSION`	`latest`	iii-engine Docker image tag

Important: AGENTMEMORY_III_VERSION=latest overrides the npm CLI's hardcoded IIPINNED_VERSION=0.11.2, ensuring the latest stable iii-engine (v0.11.6) is used instead of the older pinned version.

Docker socket

The service uses the system Docker socket at /var/run/docker.sock (owned by root:docker). Do NOT set DOCKER_HOST — the default socket path is correct.

Search Mode: BM25 vs Vector

agentmemory supports two search modes:

Mode	Description	Use when
BM25-only	Keyword-based full-text search	Default, no API key needed
Hybrid (BM25+Vector)	BM25 + semantic embeddings	Need semantic/synonym search

Default: BM25-only (no configuration needed)

BM25 covers 90%+ of searches for known terms (skill names, config keys, decision labels). Current status after setup:

text

[agentmemory] Embedding provider: none (BM25-only mode)

Want vector search? Choose your embedding provider

When you're ready to upgrade, choose from these free-tier options:

Provider	Free tier	Chinese	Setup
VoyageAI	50k tokens/month	✅ Good	`VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai`
Cohere	50k tokens/month	✅ Good	`COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere`
阿里云百炼 Qwen/E5	~$0.1/1M tokens	✅ Excellent	`OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai`

When user wants vector search, ask them to choose one of the three, then configure accordingly:

Option A: VoyageAI

ini

Environment=EMBEDDING_PROVIDER=voyageai
Environment=VOYAGE_API_KEY=your_voyage_key

Option B: Cohere

ini

Environment=EMBEDDING_PROVIDER=cohere
Environment=COHERE_API_KEY=your_cohere_key

Option C: 阿里云百炼 (Bailian)

ini

Environment=EMBEDDING_PROVIDER=openai
Environment=OPENAI_API_KEY=your_bailian_key
Environment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
Environment=OPENAI_EMBEDDING_MODEL=text-embedding-v4
Environment=OPENAI_EMBEDDING_DIMENSIONS=1024

After configuring, reload and restart:

bash

systemctl --user daemon-reload
systemctl --user restart agentmemory

Verify embedding is active:

bash

journalctl --user -u agentmemory -n 5 --no-pager | grep "Embedding provider"
# → [agentmemory] Embedding provider: openai (1024 dims)  ← example for Bailian

Integration with MEMORY.md

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

Layer	System	Purpose	Management
Experience	agentmemory	Manual save, semantic recall, cross-agent	`memory_save` (manual)
Knowledge	MEMORY.md	Curated decisions, preferences, rules	Manual

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, migrate MEMORY.md content into agentmemory:

Open the dashboard to view current state
bash
```
open http://localhost:3113
```
Initially empty — migration populates it with searchable data.

Migrate MEMORY.md content Use the CLI migrate command:

bash

agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md --verbose

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

bash ./scripts/verify.sh

Expected output:

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

Manual health check

bash

curl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool

Healthy response shows: {"status":"healthy","uptimeSeconds":...,"workers":[...]}

MCP Tools (Key ones for OpenClaw)

Tool	Purpose
`memory_recall`	Semantic search across all memories
`memory_save`	Store new memories with type/tags
`memory_smart_search`	Hybrid BM25+vector search
`memory_timeline`	View memories chronologically
`memory_profile`	Agent's memory usage stats
`memory_snapshot`	Full memory export as JSON
`memory_forget`	Delete specific memories
`memory_context`	Get context for current session
`memory_lesson_save`	Record lessons learned from errors
`memory_reflect`	Cluster knowledge graph for insights

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

Uninstall

MCP mode removal

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

Full removal

bash

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:

bash

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

"Config invalid" after editing openclaw.json

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

bash

openclaw status  # Should show "Config valid"

View real-time logs

bash

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

iii-engine version mismatch

If api::graph-stats and other v0.11.6 functions are not registered:

bash

# Check current iii-engine version
curl -s http://127.0.0.1:3111/agentmemory/health | python3 -c "
import json,sys; d=json.load(sys.stdin)
for w in d['health']['workers']:
    print(w['name'], '→', w['version'])
"

# Ensure AGENTMEMORY_III_VERSION=latest is set in systemd service
systemctl --user status agentmemory
grep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service

WebSocket disconnected (1006)

This is typically a client-side event (browser tab switch, network glitch), not a Gateway failure. Check:

bash

journalctl --user -u openclaw-gateway --since "5 minutes ago" | grep -E "connected|disconnected"

If Gateway shows webchat connected after the disconnect, the service is fine.

中文版 Chinese Version

agentmemory × OpenClaw 集成

状态: ✅ 已验证兼容 OpenClaw v2026.5.4 版本: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6 MCP 工具: 107 个 REST + 51 个 MCP 工具

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

系统架构

text

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

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

第一步：启动记忆服务器

bash

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

第二步：配置 OpenClaw MCP

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

json

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

第三步：重启 Gateway

bash

openclaw gateway restart

第四步：验证

bash

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

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

搜索模式：BM25 vs 向量

agentmemory 支持两种搜索模式：

模式	说明	适用场景
仅 BM25	基于关键词的全文搜索	默认，无需 API key
混合搜索 (BM25+向量)	BM25 + 语义 embeddings	需要同义词/语义搜索时

默认：仅 BM25（无需配置）

BM25 对已知术语（技能名、配置键、决策标签）的搜索已覆盖 90%+ 需求。安装后的状态：

text

[agentmemory] Embedding provider: none (BM25-only mode)

需要向量搜索？从三个免费选项中选择

准备好后再升级，从以下免费额度选项中选择：

提供商	免费额度	中文支持	配置方式
VoyageAI	50k tokens/月	✅ 良好	`VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai`
Cohere	50k tokens/月	✅ 良好	`COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere`
阿里云百炼 Qwen/E5	~$0.1/1M tokens	✅ 优秀	`OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai`

当用户需要向量搜索时，先让他们从三个选项中选择，然后再配置：

选项 A: VoyageAI

ini

Environment=EMBEDDING_PROVIDER=voyageai
Environment=VOYAGE_API_KEY=your_voyage_key

选项 B: Cohere

ini

Environment=EMBEDDING_PROVIDER=cohere
Environment=COHERE_API_KEY=your_cohere_key

选项 C: 阿里云百炼 (Bailian)

ini

Environment=EMBEDDING_PROVIDER=openai
Environment=OPENAI_API_KEY=your_bailian_key
Environment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
Environment=OPENAI_EMBEDDING_MODEL=text-embedding-v4
Environment=OPENAI_EMBEDDING_DIMENSIONS=1024

配置完成后，重载并重启服务：

bash

systemctl --user daemon-reload
systemctl --user restart agentmemory

验证 embedding 已启用：

bash

journalctl --user -u agentmemory -n 5 --no-pager | grep "Embedding provider"
# → [agentmemory] Embedding provider: openai (1024 dims)  ← Bailian 配置示例

systemd 服务（生产环境推荐）

安装服务：

bash

mkdir -p ~/.config/systemd/user
cp ./scripts/agentmemory.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable agentmemory
systemctl --user start agentmemory

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

服务环境变量：

变量	值	说明
`NODE_ENV`	`production`	生产模式
`AGENTMEMORY_PORT`	`3111`	MCP API 端口
`AGENTMEMORY_VIEWER_PORT`	`3113`	仪表板端口
`AGENTMEMORY_III_VERSION`	`latest`	iii-engine Docker 镜像标签

重要：AGENTMEMORY_III_VERSION=latest 用于绕过 npm CLI 硬编码的 IIPINNED_VERSION=0.11.2，确保使用最新的稳定版 iii-engine（v0.11.6）。

Docker socket：服务使用系统 Docker socket /var/run/docker.sock（属于 root:docker 组）。不要设置 DOCKER_HOST 环境变量，默认 socket 路径已正确。

与 MEMORY.md 的协同

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

层级	系统	用途	管理方式
经验层	agentmemory	手动保存重要内容、语义召回、跨 Agent 共享	`memory_save`（手动调用）
知识层	MEMORY.md	精心整理的决策、偏好、规则	手工维护

协调规则：

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

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

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

打开仪表板查看当前状态
bash
```
open http://localhost:3113
```
初始是空的，迁移后才有数据可搜。

迁移 MEMORY.md 内容 使用 CLI migrate 命令：

bash

agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md --verbose

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

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

核心 MCP 工具

工具	用途
`memory_recall`	跨所有记忆的语义搜索
`memory_save`	以类型/标签存储新记忆
`memory_smart_search`	BM25+向量混合搜索
`memory_timeline`	按时间线查看记忆
`memory_profile`	Agent 记忆使用统计
`memory_snapshot`	完整记忆导出 JSON
`memory_forget`	删除指定记忆
`memory_context`	获取当前会话上下文
`memory_lesson_save`	记录从错误中学到的教训
`memory_reflect`	聚类知识图谱提炼洞察

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

验证

bash

bash ./scripts/verify.sh

预期结果：

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

手动健康检查

bash

curl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool

健康响应包含：{"status":"healthy","uptimeSeconds":...,"workers":[...]}

卸载

仅移除 MCP 模式：

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

完全移除：

bash

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

故障排查

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

bash

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

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

bash

openclaw status  # 应显示 "Config valid"

查看实时日志：

bash

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

iii-engine 版本不匹配 如果 api::graph-stats 等 v0.11.6 函数未注册：

bash

# 检查当前 iii-engine 版本
curl -s http://127.0.0.1:3111/agentmemory/health | python3 -c "
import json,sys; d=json.load(sys.stdin)
for w in d['health']['workers']:
    print(w['name'], '→', w['version'])
"

# 确认 systemd service 中设置了 AGENTMEMORY_III_VERSION=latest
systemctl --user status agentmemory
grep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service

**WebSocket 断连 (1006)**
这通常是客户端事件（浏览器切页、网络抖动），非 Gateway 故障。检查：
```bash
journalctl --user -u openclaw-gateway --since "5 minutes ago" | grep -E "connected|disconnected"

如果 Gateway 在断连后显示 webchat connected，说明服务正常。

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

agentmemory-mcp

Install

agentmemory Integration for OpenClaw

Architecture

Quick Start (MCP Mode — 5 minutes)

Step 1: Install and start memory server

Step 2: Configure OpenClaw MCP

Step 3: Restart Gateway

Step 4: Verify

systemd Service (Production)

Install service

Service commands

Service environment variables

Docker socket

Search Mode: BM25 vs Vector

Default: BM25-only (no configuration needed)

Want vector search? Choose your embedding provider

Option A: VoyageAI

Option B: Cohere

Option C: 阿里云百炼 (Bailian)

Integration with MEMORY.md

Coordination rules

After installation: migrate MEMORY.md (important!)

Verification

Manual health check

MCP Tools (Key ones for OpenClaw)

Uninstall

MCP mode removal

Full removal

Troubleshooting

"Connection refused on port 3111"

"Config invalid" after editing openclaw.json

View real-time logs

iii-engine version mismatch

WebSocket disconnected (1006)

中文版 Chinese Version

agentmemory × OpenClaw 集成

系统架构

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

搜索模式：BM25 vs 向量

默认：仅 BM25（无需配置）

需要向量搜索？从三个免费选项中选择

选项 A: VoyageAI

选项 B: Cohere

选项 C: 阿里云百炼 (Bailian)

systemd 服务（生产环境推荐）

与 MEMORY.md 的协同

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

核心 MCP 工具

验证

手动健康检查

卸载

故障排查

Related skills