{"id":"025c7062-d650-44b0-9110-9a41135736dd","entityType":"agent","slug":"clawhub-lufei4-agentmemory-mcp","name":"agentmemory-mcp","canonicalUrl":"https://www.xpersona.co/agent/clawhub-lufei4-agentmemory-mcp","canonicalPath":"/agent/clawhub-lufei4-agentmemory-mcp","generatedAt":"2026-10-12T15:57:03.534Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T20:35:20.775Z","emptyReason":null},"description":"Persistent cross-session memory for OpenClaw via agentmemory. Use when: - User asks to install/configure agentmemory for OpenClaw - Agent needs to remember p... Skill: agentmemory-mcp Owner: lufei4 Summary: Persistent cross-session memory for OpenClaw via agentmemory. Use when: - User asks to install/configure agentmemory for OpenClaw - Agent needs to remember p... Tags: agentmemory:1.1.0, latest:1.3.0, mcp:1.1.0, memory:1.1.0, openclauw:1.1.0, persistent:1.1.0 Version history: v1.3.0 | 2026-05-13T07:47:38.658Z | user Major: Full Search Mode guide (BM25 vs Vector embedding p","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 996 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s179k729rb0rtr2tvxk90h5pxs859fyv:agentmemory-mcp","sourceUrl":"https://clawhub.ai/lufei4/agentmemory-mcp","homepage":"https://clawhub.ai/lufei4/skills/agentmemory-mcp","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/lufei4/agentmemory-mcp","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/lufei4/skills/agentmemory-mcp","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Persistent cross-session memory for OpenClaw via agentmemory. Use when: - User asks to install/configure agentmemory for OpenClaw - Agent needs to remember p..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:35:20.775Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:35:20.775Z","emptyReason":null},"stars":null,"forks":null,"downloads":996,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.3.0","tractionLabel":"996 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:35:20.702Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T20:35:20.775Z","lastCrawledAt":"2026-10-11T20:35:20.702Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T20:35:20.702Z","lastVerifiedAt":null,"highlights":[{"version":"1.3.0","createdAt":"2026-05-13T07:47:38.658Z","changelog":"Major: Full Search Mode guide (BM25 vs Vector embedding provider choice); fix absolute paths; align with latest agentmemory v0.9.14 / iii-engine v0.11.6","fileCount":9,"zipByteSize":15070},{"version":"0.9.15","createdAt":"2026-05-13T07:40:51.673Z","changelog":"Fix absolute paths in install commands; add Search Mode: BM25 vs Vector section with embedding provider choice (VoyageAI/Cohere/阿里云百炼)","fileCount":8,"zipByteSize":13663},{"version":"0.9.14","createdAt":"2026-05-13T07:13:08.041Z","changelog":"v0.9.14 (2026-05-13) - 修复：所有 /home/lufei 绝对路径改为相对路径（./scripts/、~/.config/） - 改进：embedding 配置从 EnvironmentFile 加载，支持 .env 和 environment.d/ 两种方式 - 说明：sender metadata (label/id) 为非信任数据，仅用于路由 - 配置：阿里云百炼 text-embedding-v4 (1024 dims) BM25+Vector+Graph 三路混合","fileCount":8,"zipByteSize":13663},{"version":"0.9.13","createdAt":"2026-05-13T06:55:31.519Z","changelog":"v0.9.13 (2026-05-13) - 安全修复：移除所有明文 API Key，改为占位符示例 - 流程改进：BM25-only 默认完成，用户需向量搜索时才引导配置 - 新增：三个免费 embedding 选项（VoyageAI/Cohere/阿里云百炼）供用户选择","fileCount":8,"zipByteSize":13681},{"version":"0.9.12","createdAt":"2026-05-13T06:38:06.890Z","changelog":"v0.9.12 (2026-05-13) - 新增：阿里云百炼 text-embedding-v4 embedding 配置说明 - 配置 OPENAI_BASE_URL 为 dashscope 兼容端点 - 设置 OPENAI_EMBEDDING_DIMENSIONS=1024（text-embedding-v4 实际维度） - 添加验证和测试命令到文档 - 修复：BM25-only 说明移动到独立章节（原在 Search Mode: BM25-only）","fileCount":8,"zipByteSize":13954},{"version":"0.9.11","createdAt":"2026-05-13T06:02:55.650Z","changelog":"v0.9.11 (2026-05-13) - 升级 iii-engine Docker 镜像至 v0.11.6（SHA b0cdb0d） - 新增环境变量 AGENTMEMORY_III_VERSION=latest 说明（绕过 npm CLI 硬编码版本） - 新增 BM25-only 搜索模式说明（已知限制，非故障） - 新增 Docker socket 配置说明（/var/run/docker.sock，勿设置 DOCKER_HOST） - 新增 iii-engine 版本检查和 WebSocket 1006 故障排查章节 - 更新 MEMORY.md 迁移命令（migrate --from-file 现已可用） - 修复版本号：agentmemory npm v0.9.11（非旧版的 0.9.9） - 中英文 description 段落分隔整理","fileCount":8,"zipByteSize":13391},{"version":"1.2.0","createdAt":"2026-05-12T09:32:31.196Z","changelog":"Bilingual EN/CN description added to frontmatter","fileCount":8,"zipByteSize":11647},{"version":"1.1.0","createdAt":"2026-05-12T07:37:28.736Z","changelog":"Bilingual EN/CN skill - added full Chinese section, benefits table, coordination rules","fileCount":8,"zipByteSize":10904}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s179k729rb0rtr2tvxk90h5pxs859fyv:agentmemory-mcp","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T15:57:03.532Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-lufei4-agentmemory-mcp/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T20:35:20.775Z","emptyReason":null},"readme":"Skill: agentmemory-mcp\n\nOwner: lufei4\n\nSummary: Persistent cross-session memory for OpenClaw via agentmemory. Use when: - User asks to install/configure agentmemory for OpenClaw - Agent needs to remember p...\n\nTags: agentmemory:1.1.0, latest:1.3.0, mcp:1.1.0, memory:1.1.0, openclauw:1.1.0, persistent:1.1.0\n\nVersion history:\n\nv1.3.0 | 2026-05-13T07:47:38.658Z | user\n\nMajor: Full Search Mode guide (BM25 vs Vector embedding provider choice); fix absolute paths; align with latest agentmemory v0.9.14 / iii-engine v0.11.6\n\nv0.9.15 | 2026-05-13T07:40:51.673Z | user\n\nFix absolute paths in install commands; add Search Mode: BM25 vs Vector section with embedding provider choice (VoyageAI/Cohere/阿里云百炼)\n\nv0.9.14 | 2026-05-13T07:13:08.041Z | user\n\nv0.9.14 (2026-05-13)\n- 修复：所有 /home/lufei 绝对路径改为相对路径（./scripts/、~/.config/）\n- 改进：embedding 配置从 EnvironmentFile 加载，支持 .env 和 environment.d/ 两种方式\n- 说明：sender metadata (label/id) 为非信任数据，仅用于路由\n- 配置：阿里云百炼 text-embedding-v4 (1024 dims) BM25+Vector+Graph 三路混合\n\nv0.9.13 | 2026-05-13T06:55:31.519Z | user\n\nv0.9.13 (2026-05-13)\n- 安全修复：移除所有明文 API Key，改为占位符示例\n- 流程改进：BM25-only 默认完成，用户需向量搜索时才引导配置\n- 新增：三个免费 embedding 选项（VoyageAI/Cohere/阿里云百炼）供用户选择\n\nv0.9.12 | 2026-05-13T06:38:06.890Z | user\n\nv0.9.12 (2026-05-13)\n- 新增：阿里云百炼 text-embedding-v4 embedding 配置说明\n- 配置 OPENAI_BASE_URL 为 dashscope 兼容端点\n- 设置 OPENAI_EMBEDDING_DIMENSIONS=1024（text-embedding-v4 实际维度）\n- 添加验证和测试命令到文档\n- 修复：BM25-only 说明移动到独立章节（原在 Search Mode: BM25-only）\n\nv0.9.11 | 2026-05-13T06:02:55.650Z | user\n\nv0.9.11 (2026-05-13)\n- 升级 iii-engine Docker 镜像至 v0.11.6（SHA b0cdb0d）\n- 新增环境变量 AGENTMEMORY_III_VERSION=latest 说明（绕过 npm CLI 硬编码版本）\n- 新增 BM25-only 搜索模式说明（已知限制，非故障）\n- 新增 Docker socket 配置说明（/var/run/docker.sock，勿设置 DOCKER_HOST）\n- 新增 iii-engine 版本检查和 WebSocket 1006 故障排查章节\n- 更新 MEMORY.md 迁移命令（migrate --from-file 现已可用）\n- 修复版本号：agentmemory npm v0.9.11（非旧版的 0.9.9）\n- 中英文 description 段落分隔整理\n\nv1.2.0 | 2026-05-12T09:32:31.196Z | user\n\nBilingual EN/CN description added to frontmatter\n\nv1.1.0 | 2026-05-12T07:37:28.736Z | user\n\nBilingual EN/CN skill - added full Chinese section, benefits table, coordination rules\n\nv1.0.0 | 2026-05-12T06:35:41.965Z | user\n\nInitial release: MCP mode, systemd service, MEMORY.md coordination, 95.2% R@5 semantic recall, 51 MCP tools\n\nArchive index:\n\nArchive v1.3.0: 9 files, 15070 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), skill-card.md (2741b), SKILL.md (18248b), _meta.json (134b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: agentmemory\ndescription: |\n Persistent cross-session memory for OpenClaw via agentmemory.\n \n Use when:\n - User asks to install/configure agentmemory for OpenClaw\n - Agent needs to remember project context, decisions, or workflows across sessions\n - Setting up long-term memory for OpenClaw (MCP mode)\n - Integrating agentmemory with existing MEMORY.md system\n - Troubleshooting agentmemory connection issues\n - Upgrading or removing agentmemory\n\n ───────────────────────────────\n \n 基于 agentmemory 的跨会话持久化记忆系统，适用于 OpenClaw。\n \n 适用场景：\n - 用户要求安装/配置 agentmemory\n - Agent 需要记住项目背景、决策或工作流程\n - 为 OpenClaw 设置长期记忆（MCP 模式）\n - 与现有 MEMORY.md 系统集成\n - 排查 agentmemory 连接问题\n - 升级或移除 agentmemory\n---\n\n# agentmemory Integration for OpenClaw\n\n> **Status**: ✅ Verified working with OpenClaw v2026.5.4\n> **Version**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP Tools**: 107 REST + 51 MCP tools available\n\nPersistent memory server giving OpenClaw agents cross-session semantic recall via BM25+Vector+Graph RRF hybrid search.\n\n## Architecture\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)\n ↓\n SQLite/KV Store\n ↓\n Viewer (localhost:3113)\n```\n\n## Quick Start (MCP Mode — 5 minutes)\n\n### Step 1: Install and start memory server\n\n```bash\n# Server runs on localhost:3111, viewer at localhost:3113\nnpx @agentmemory/agentmemory\n```\n\n### Step 2: Configure OpenClaw MCP\n\nAdd to `~/.openclaw/openclaw.json` under `mcp.servers`:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n### Step 3: Restart Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n### Step 4: Verify\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# View memory dashboard\nopen http://localhost:3113\n```\n\n---\n\n## systemd Service (Production)\n\nFor auto-start and reliable background operation:\n\n### Install service\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp ./scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# Enable linger (boot without login)\nloginctl enable-linger $(whoami)\n```\n\n### Service commands\n\n```bash\nsystemctl --user status agentmemory # Check status\njournalctl --user -u agentmemory -f # View logs\nsystemctl --user restart agentmemory # Restart\n```\n\n### Service environment variables\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `NODE_ENV` | `production` | Production mode |\n| `AGENTMEMORY_PORT` | `3111` | MCP API port |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | Dashboard port |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker image tag |\n\n> **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.\n\n### Docker socket\n\nThe 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.\n\n---\n\n## Search Mode: BM25 vs Vector\n\nagentmemory supports two search modes:\n\n| Mode | Description | Use when |\n|------|-------------|----------|\n| **BM25-only** | Keyword-based full-text search | Default, no API key needed |\n| **Hybrid (BM25+Vector)** | BM25 + semantic embeddings | Need semantic/synonym search |\n\n### Default: BM25-only (no configuration needed)\n\nBM25 covers 90%+ of searches for known terms (skill names, config keys, decision labels). Current status after setup:\n\n```\n[agentmemory] Embedding provider: none (BM25-only mode)\n```\n\n### Want vector search? Choose your embedding provider\n\nWhen you're ready to upgrade, choose from these free-tier options:\n\n| Provider | Free tier | Chinese | Setup |\n|----------|-----------|---------|-------|\n| **VoyageAI** | 50k tokens/month | ✅ Good | `VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai` |\n| **Cohere** | 50k tokens/month | ✅ Good | `COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere` |\n| **阿里云百炼 Qwen/E5** | ~$0.1/1M tokens | ✅ Excellent | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai` |\n\n**When user wants vector search**, ask them to choose one of the three, then configure accordingly:\n\n#### Option A: VoyageAI\n```ini\nEnvironment=EMBEDDING_PROVIDER=voyageai\nEnvironment=VOYAGE_API_KEY=your_voyage_key\n```\n\n#### Option B: Cohere\n```ini\nEnvironment=EMBEDDING_PROVIDER=cohere\nEnvironment=COHERE_API_KEY=your_cohere_key\n```\n\n#### Option C: 阿里云百炼 (Bailian)\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=your_bailian_key\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\nAfter configuring, reload and restart:\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\nVerify embedding is active:\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims) ← example for Bailian\n```\n\n---\n\n## Integration with MEMORY.md\n\nagentmemory and MEMORY.md serve different purposes — they coexist:\n\n| Layer | System | Purpose | Management |\n|-------|--------|---------|------------|\n| **Experience** | agentmemory | Manual save, semantic recall, cross-agent | `memory_save` (manual) |\n| **Knowledge** | MEMORY.md | Curated decisions, preferences, rules | Manual |\n\n### Coordination rules\n\n- **Before major tasks**: Call `memory_recall` to retrieve relevant experiences\n- **After important decisions**: Call `memory_save` with result\n- **Curated knowledge**: Stays in MEMORY.md (survives compaction)\n- **Session start**: Both systems loaded; no conflicts\n\n### After installation: migrate MEMORY.md (important!)\n\nAfter completing installation, migrate MEMORY.md content into agentmemory:\n\n1. **Open the dashboard to view current state**\n ```bash\n open http://localhost:3113\n ```\n Initially empty — migration populates it with searchable data.\n\n2. **Migrate MEMORY.md content**\n Use the CLI migrate command:\n ```bash\n agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **Verify migration results**\n After migration, reopen http://localhost:3113 to confirm data is stored.\n\n> Note: MEMORY.md stays intact — both systems coexist. agentmemory handles semantic search; MEMORY.md holds curated knowledge.\n\n---\n\n## Verification\n\nRun the verification script:\n```bash\nbash ./scripts/verify.sh\n```\n\nExpected output:\n- ✅ Memory server on port 3111\n- ✅ Health endpoint responding\n- ✅ Viewer available on port 3113\n- ✅ OpenClaw MCP configured\n- ✅ systemd service active\n\n### Manual health check\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\nHealthy response shows: `{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n## MCP Tools (Key ones for OpenClaw)\n\n| Tool | Purpose |\n|------|---------|\n| `memory_recall` | Semantic search across all memories |\n| `memory_save` | Store new memories with type/tags |\n| `memory_smart_search` | Hybrid BM25+vector search |\n| `memory_timeline` | View memories chronologically |\n| `memory_profile` | Agent's memory usage stats |\n| `memory_snapshot` | Full memory export as JSON |\n| `memory_forget` | Delete specific memories |\n| `memory_context` | Get context for current session |\n| `memory_lesson_save` | Record lessons learned from errors |\n| `memory_reflect` | Cluster knowledge graph for insights |\n\nSee `references/mcp-tools.md` for full list of 51 tools.\n\n---\n\n## Uninstall\n\n### MCP mode removal\n\n1. Remove from `openclaw.json` mcp.servers section\n2. `openclaw gateway restart`\n\n### Full removal\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Connection refused on port 3111\"\nMemory server not running. Start it:\n```bash\nsystemctl --user start agentmemory\n# Or manually: npx @agentmemory/agentmemory\n```\n\n### \"Config invalid\" after editing openclaw.json\nEnsure `mcp.servers` path (not `mcpServers`). Run:\n```bash\nopenclaw status # Should show \"Config valid\"\n```\n\n### View real-time logs\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n### iii-engine version mismatch\nIf `api::graph-stats` and other v0.11.6 functions are not registered:\n```bash\n# Check current iii-engine version\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# Ensure AGENTMEMORY_III_VERSION=latest is set in systemd service\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n```\n\n### WebSocket disconnected (1006)\nThis is typically a client-side event (browser tab switch, network glitch), not a Gateway failure. Check:\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\nIf Gateway shows `webchat connected` after the disconnect, the service is fine.\n\n---\n\n---\n\n## 中文版 Chinese Version\n\n### agentmemory × OpenClaw 集成\n\n> **状态**: ✅ 已验证兼容 OpenClaw v2026.5.4\n> **版本**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP 工具**: 107 个 REST + 51 个 MCP 工具\n\n持久化记忆服务，为 OpenClaw Agent 提供跨会话语义召回能力，基于 BM25+向量+图谱混合搜索。\n\n### 系统架构\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP 服务器 (localhost:3111)\n ↓\n SQLite/KV 存储\n ↓\n 浏览器仪表板 (localhost:3113)\n```\n\n### 快速开始（MCP 模式 — 5 分钟）\n\n**第一步：启动记忆服务器**\n\n```bash\nnpx @agentmemory/agentmemory\n# 服务器端口：3111（API）、3113（浏览器仪表板）\n```\n\n**第二步：配置 OpenClaw MCP**\n\n在 `~/.openclaw/openclaw.json` 中加入：\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n**第三步：重启 Gateway**\n\n```bash\nopenclaw gateway restart\n```\n\n**第四步：验证**\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# 打开记忆仪表板\nopen http://localhost:3113\n```\n\n---\n\n### 搜索模式：BM25 vs 向量\n\nagentmemory 支持两种搜索模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| **仅 BM25** | 基于关键词的全文搜索 | 默认，无需 API key |\n| **混合搜索 (BM25+向量)** | BM25 + 语义 embeddings | 需要同义词/语义搜索时 |\n\n### 默认：仅 BM25（无需配置）\n\nBM25 对已知术语（技能名、配置键、决策标签）的搜索已覆盖 90%+ 需求。安装后的状态：\n\n```\n[agentmemory] Embedding provider: none (BM25-only mode)\n```\n\n### 需要向量搜索？从三个免费选项中选择\n\n准备好后再升级，从以下免费额度选项中选择：\n\n| 提供商 | 免费额度 | 中文支持 | 配置方式 |\n|--------|----------|----------|----------|\n| **VoyageAI** | 50k tokens/月 | ✅ 良好 | `VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai` |\n| **Cohere** | 50k tokens/月 | ✅ 良好 | `COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere` |\n| **阿里云百炼 Qwen/E5** | ~$0.1/1M tokens | ✅ 优秀 | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai` |\n\n**当用户需要向量搜索时**，先让他们从三个选项中选择，然后再配置：\n\n#### 选项 A: VoyageAI\n```ini\nEnvironment=EMBEDDING_PROVIDER=voyageai\nEnvironment=VOYAGE_API_KEY=your_voyage_key\n```\n\n#### 选项 B: Cohere\n```ini\nEnvironment=EMBEDDING_PROVIDER=cohere\nEnvironment=COHERE_API_KEY=your_cohere_key\n```\n\n#### 选项 C: 阿里云百炼 (Bailian)\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=your_bailian_key\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\n配置完成后，重载并重启服务：\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\n验证 embedding 已启用：\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims) ← Bailian 配置示例\n```\n\n---\n\n### systemd 服务（生产环境推荐）\n\n**安装服务：**\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp ./scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# 启用 linger（开机免登录自动启动）\nloginctl enable-linger $(whoami)\n```\n\n**服务环境变量：**\n\n| 变量 | 值 | 说明 |\n|------|-----|------|\n| `NODE_ENV` | `production` | 生产模式 |\n| `AGENTMEMORY_PORT` | `3111` | MCP API 端口 |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | 仪表板端口 |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker 镜像标签 |\n\n> **重要**：`AGENTMEMORY_III_VERSION=latest` 用于绕过 npm CLI 硬编码的 `IIPINNED_VERSION=0.11.2`，确保使用最新的稳定版 iii-engine（v0.11.6）。\n\n**Docker socket**：服务使用系统 Docker socket `/var/run/docker.sock`（属于 `root:docker` 组）。不要设置 `DOCKER_HOST` 环境变量，默认 socket 路径已正确。\n\n---\n\n### 与 MEMORY.md 的协同\n\n两个系统分工不同，共存互补：\n\n| 层级 | 系统 | 用途 | 管理方式 |\n|------|------|------|----------|\n| **经验层** | agentmemory | 手动保存重要内容、语义召回、跨 Agent 共享 | `memory_save`（手动调用） |\n| **知识层** | MEMORY.md | 精心整理的决策、偏好、规则 | 手工维护 |\n\n**协调规则：**\n\n- **任务开始前** → 调用 `memory_recall` 检索相关经验\n- **重要决策后** → 调用 `memory_save` 保存结果\n- **精选知识** → 留在 MEMORY.md（不受会话压缩影响）\n- **会话启动时** → 两个系统同时加载，无冲突\n\n### 首次安装后：迁移 MEMORY.md（重要！）\n\n安装完成后，将 MEMORY.md 的核心内容迁移到 agentmemory：\n\n1. **打开仪表板查看当前状态**\n ```bash\n open http://localhost:3113\n ```\n 初始是空的，迁移后才有数据可搜。\n\n2. **迁移 MEMORY.md 内容**\n 使用 CLI migrate 命令：\n ```bash\n agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **验证迁移结果**\n 迁移完成后，再次打开 http://localhost:3113 查看记忆仪表板，确认数据已入库。\n\n> 注意：MEMORY.md 本身保留不动，两套系统共存 — agentmemory 负责语义搜索，MEMORY.md 负责手工精修知识。\n\n---\n\n### 核心 MCP 工具\n\n| 工具 | 用途 |\n|------|------|\n| `memory_recall` | 跨所有记忆的语义搜索 |\n| `memory_save` | 以类型/标签存储新记忆 |\n| `memory_smart_search` | BM25+向量混合搜索 |\n| `memory_timeline` | 按时间线查看记忆 |\n| `memory_profile` | Agent 记忆使用统计 |\n| `memory_snapshot` | 完整记忆导出 JSON |\n| `memory_forget` | 删除指定记忆 |\n| `memory_context` | 获取当前会话上下文 |\n| `memory_lesson_save` | 记录从错误中学到的教训 |\n| `memory_reflect` | 聚类知识图谱提炼洞察 |\n\n完整 51 个工具列表见 `references/mcp-tools.md`。\n\n---\n\n### 验证\n\n```bash\nbash ./scripts/verify.sh\n```\n\n预期结果：\n- ✅ 记忆服务器在 3111 端口运行\n- ✅ Health 端点正常响应\n- ✅ 仪表板在 3113 端口可访问\n- ✅ OpenClaw MCP 已配置\n- ✅ systemd 服务已激活\n\n### 手动健康检查\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\n健康响应包含：`{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n### 卸载\n\n**仅移除 MCP 模式：**\n\n1. 从 `openclaw.json` 的 `mcp.servers` 中删除 agentmemory 条目\n2. 执行 `openclaw gateway restart`\n\n**完全移除：**\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n### 故障排查\n\n**\"Connection refused on port 3111\"**\n服务器未启动，启动它：\n```bash\nsystemctl --user start agentmemory\n# 或手动：npx @agentmemory/agentmemory\n```\n\n**修改 openclaw.json 后提示 \"Config invalid\"**\n确保路径是 `mcp.servers`（不是 `mcpServers`）：\n```bash\nopenclaw status # 应显示 \"Config valid\"\n```\n\n**查看实时日志：**\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n**iii-engine 版本不匹配**\n如果 `api::graph-stats` 等 v0.11.6 函数未注册：\n```bash\n# 检查当前 iii-engine 版本\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# 确认 systemd service 中设置了 AGENTMEMORY_III_VERSION=latest\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n\n**WebSocket 断连 (1006)**\n这通常是客户端事件（浏览器切页、网络抖动），非 Gateway 故障。检查：\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\n如果 Gateway 在断连后显示 `webchat connected`，说明服务正常。\n\n---\n\n*🦞 Skill by 龙虾 — agentmemory-mcp on ClawHub: https://clawhub.ai/lufei4/agentmemory-mcp*\n\nFile v1.3.0:_meta.json\n\n{\n \"ownerId\": \"kn73p7swcakp5x33a5x0sf7yes859vh8\",\n \"slug\": \"agentmemory-mcp\",\n \"version\": \"1.3.0\",\n \"publishedAt\": 1778658458658\n}\n\nFile v1.3.0:references/coordination.md\n\n# agentmemory + MEMORY.md Coordination Guide\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ OpenClaw Memory System │\n├─────────────────────────────────────────────────────────┤\n│ │\n│ ┌───────────────────────┐ ┌────────────────────────┐ │\n│ │ agentmemory (MCP) │ │ MEMORY.md / AGENTS │ │\n│ │ │ │ │ │\n│ │ • Auto-capture │ │ • Curated rules │ │\n│ │ • Semantic search │ │ • Preferences │ │\n│ │ • 95.2% R@5 │ │ • Manual updates │ │\n│ │ • Cross-agent │ │ • Human-readable │ │\n│ │ • Session sync │ │ • Survives compaction │ │\n│ └───────────────────────┘ └────────────────────────┘ │\n│ │ │ │\n│ └────────┬───────────────┘ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ OpenClaw Agent │ │\n│ └─────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Layer Responsibilities\n\n| Layer | Tool | What's stored | Management |\n|-------|------|--------------|------------|\n| **Experience** | agentmemory | Tasks, decisions, results, observations | Automatic |\n| **Knowledge** | MEMORY.md | Rules, preferences, long-term facts | Manual |\n| **Daily** | memory/YYYY-MM-DD.md | Session logs, events | Automatic |\n\n---\n\n## Agent Behavior Guidelines\n\n### Session Start\n\n1. **MEMORY.md + daily logs** → loaded automatically by OpenClaw\n2. **agentmemory** → agent can call `memory_recall` for additional context\n3. No conflict — both systems serve different purposes\n\n### During Work\n\n- **Task decision**: Call `memory_smart_search` to check if similar task was done\n- **Success**: Call `memory_save` with result, e.g.:\n ```\n memory_save(\"Deployed backend to Railway, took 8 minutes\", \n type=\"observation\", tags=[\"deployment\"])\n ```\n- **Failure**: Call `memory_save` noting what didn't work\n\n### Session End\n\n- OpenClaw auto-captures conversation via `plugins.slots.memory`\n- Critical learnings → also write to MEMORY.md (persists beyond compaction)\n\n---\n\n## Migration from Existing MEMORY.md\n\nIf MEMORY.md has valuable content, migrate selectively:\n\n```bash\n# Start server first\nnpx @agentmemory/agentmemory\n\n# In another terminal, import MEMORY.md\nnpx @agentmemory/agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md\n```\n\nOr use `memory_import` in batches:\n\n```javascript\n// Example: Migrate section by section\nmemory_import([\n { content: \"Backend deployed via Railway CLI\", type: \"observation\", tags: [\"deployment\"] },\n { content: \"User prefers brief responses\", type: \"preference\", tags: [\"communication\"] }\n], strategy: \"merge\")\n```\n\n---\n\n## Conflict Resolution\n\n**Q: What if agentmemory says something different from MEMORY.md?**\n\n| Scenario | Resolution |\n|----------|------------|\n| MEMORY.md has rule, agentmemory has conflicting experience | Trust MEMORY.md (curated), log conflict in agentmemory |\n| agentmemory has newer info | Update MEMORY.md if verified |\n| Uncertainty | Log to agentmemory, keep both until resolved |\n\n**Principle**: MEMORY.md is source of truth for rules; agentmemory is evidence of experience.\n\n---\n\n## Maintenance\n\n### Periodic (monthly)\n\n1. Read `memory_stats()` output\n2. Check for gaps with `memory_analyze(\"gaps\")`\n3. Review MEMORY.md for outdated entries\n\n### When Conflicting\n\n```bash\n# View memory for specific topic\nmemory_timeline(tag=\"deployment\", limit=10)\n\n# Check provenance\nmemory_trace(id=\"\")\n\n# Update or correct\nmemory_update(id=\"\", content=\"corrected information\")\n```\n\n---\n\n## Optimal Configuration\n\nFor maximum capability, run both systems:\n\n1. **agentmemory MCP** — handles automatic capture, semantic search, cross-agent sharing\n2. **MEMORY.md** — handles curated rules, preferences, compliance requirements\n\nThe agent uses whichever is appropriate for the situation — no forced preference.\n\nFile v1.3.0:references/mcp-tools.md\n\n# agentmemory MCP Tools Reference\n\nComplete list of 43 MCP tools available via `agentmemory` MCP server.\n\n## Core Memory Operations\n\n### memory_recall\nRetrieve semantically relevant memories.\n```\nmemory_recall(query: string, limit?: number, threshold?: number)\n```\n\n### memory_save\nStore new memories with optional metadata.\n```\nmemory_save(content: string, type?: \"observation\" | \"decision\" | \"fact\" | \"preference\", tags?: string[])\n```\n\n### memory_smart_search\nHybrid BM25 + vector search.\n```\nmemory_smart_search(query: string, limit?: number)\n```\n\n### memory_forget\nDelete memories by ID or pattern.\n```\nmemory_forget(pattern?: string, id?: string)\n```\n\n### memory_update\nUpdate existing memory content or metadata.\n```\nmemory_update(id: string, content?: string, tags?: string[])\n```\n\n---\n\n## Navigation & Exploration\n\n### memory_timeline\nView memories chronologically.\n```\nmemory_timeline(start?: date, end?: date, limit?: number)\n```\n\n### memory_tree\nHierarchical view of knowledge graph.\n```\nmemory_tree(root?: string, depth?: number)\n```\n\n### memory_trace\nView provenance/derivation chain of a memory.\n```\nmemory_trace(id: string)\n```\n\n### memory_stats\nMemory usage statistics.\n```\nmemory_stats()\n```\n\n---\n\n## Agent Integration\n\n### memory_profile\nDetailed agent memory profile.\n```\nmemory_profile(agent_id?: string)\n```\n\n### memory_snapshot\nExport all memories as JSON.\n```\nmemory_snapshot(format?: \"json\" | \"markdown\")\n```\n\n### memory_import\nBulk import memories.\n```\nmemory_import(memory: Memory[], strategy?: \"merge\" | \"replace\")\n```\n\n### memory_compact\nCompress and consolidate memories.\n```\nmemory_compact(threshold?: number)\n```\n\n---\n\n## Knowledge Graph\n\n### memory_relate\nCreate relationships between memories.\n```\nmemory_relate(from_id: string, to_id: string, relationship?: string)\n```\n\n### memory_graph_query\nQuery knowledge graph.\n```\nmemory_graph_query(query: string, depth?: number)\n```\n\n### memory_entities\nList all entities in knowledge graph.\n```\nmemory_entities(type?: string)\n```\n\n### memory_paths\nFind paths between two memories.\n```\nmemory_paths(from_id: string, to_id: string)\n```\n\n---\n\n## Context & Sessions\n\n### memory_context\nGet context for current session.\n```\nmemory_context(include_recent?: number)\n```\n\n### memory_inject\nInject memories into current context.\n```\nmemory_inject(limit?: number, match?: string)\n```\n\n### memory_session\nSession-specific memory operations.\n```\nmemory_session(op: \"save\" | \"load\" | \"clear\", data?: any)\n```\n\n---\n\n## Configuration\n\n### memory_config\nView/update agentmemory configuration.\n```\nmemory_config(op: \"get\" | \"set\", key?: string, value?: any)\n```\n\n### memory_channels\nList available memory channels.\n```\nmemory_channels()\n```\n\n---\n\n## Advanced\n\n### memory_analyze\nAnalyze memory patterns.\n```\nmemory_analyze(analysis_type?: \"coverage\" | \"gaps\" | \"redundancy\")\n```\n\n### memory_consolidate\nConsolidate fragmented memories.\n```\nmemory_consolidate(strategy?: \"simple\" | \"semantic\")\n```\n\n### memory_evict\nEvict low-value memories.\n```\nmemory_evict(threshold?: number, dry_run?: boolean)\n```\n\n---\n\n## Usage in OpenClaw\n\n### Before starting a task\n```\nAgent can call: memory_recall(\"project architecture decisions\")\n→ Returns relevant past decisions, avoiding re-explaining\n```\n\n### After completing a task\n```\nAgent can call: memory_save(\"Deployed backend to production via railway\", \n type=\"decision\", tags=[\"deployment\", \"backend\"])\n→ Stores experience for future reference\n```\n\n### Check task deduplication\n```\nAgent can call: memory_smart_search(\"deploy backend production\")\n→ If match found, agent can reuse previous workflow\n```\n\nFile v1.3.0:references/openclaw-plugin/openclaw.plugin.json\n\n{\n \"schema_version\": 1,\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"Persistent cross-session memory with semantic search\",\n \"slots\": [\"memory\"],\n \"config\": {\n \"base_url\": {\n \"type\": \"string\",\n \"default\": \"http://localhost:3111\",\n \"description\": \"agentmemory server URL\"\n },\n \"token_budget\": {\n \"type\": \"number\",\n \"default\": 2000,\n \"description\": \"Max tokens per recall injection\"\n },\n \"min_confidence\": {\n \"type\": \"number\",\n \"default\": 0.5,\n \"description\": \"Minimum confidence threshold for recall\"\n },\n \"fallback_on_error\": {\n \"type\": \"boolean\",\n \"default\": true,\n \"description\": \"Continue without memory if server unavailable\"\n },\n \"timeout_ms\": {\n \"type\": \"number\",\n \"default\": 5000,\n \"description\": \"Request timeout in milliseconds\"\n }\n },\n \"hooks\": {\n \"beforeAgent\": \"onBeforeAgent\",\n \"afterAgent\": \"onAfterAgent\"\n },\n \"requirements\": {\n \"server\": \"agentmemory\",\n \"min_openclaw_version\": \"1.0.0\"\n }\n}\n\nFile v1.3.0:references/openclaw-plugin/package.json\n\n{\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"agentmemory plugin for OpenClaw - persistent cross-session memory\",\n \"main\": \"plugin.mjs\",\n \"openclaw\": {\n \"slots\": [\"memory\"],\n \"version\": \">=1.0.0\"\n },\n \"dependencies\": {\n \"axios\": \"^1.6.0\"\n }\n}\n\nFile v1.3.0:skill-card.md\n\n## Description:\n\nPersistent cross-session memory for OpenClaw agents through an agentmemory MCP server.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[lufei4](https://clawhub.ai/user/lufei4)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and OpenClaw users use this skill to install, configure, verify, troubleshoot, upgrade, or remove agentmemory-backed long-term memory. Agents can use the guidance to enable recall, saving, migration from MEMORY.md, and hybrid memory search workflows.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Persistent background execution and automatic conversation capture can store sensitive or unintended session content.\n\nMitigation: Keep the service local, review captured memories regularly, and disable or restrict automatic capture when handling sensitive work.\n\nRisk: Docker-level access increases the impact of a compromised or misconfigured memory service.\n\nMitigation: Avoid Docker socket access unless the service is fully trusted, and use pinned package and image versions for installation.\n\nRisk: Recalled or imported memories may contain stale, incorrect, or instruction-like content.\n\nMitigation: Treat recalled memories as untrusted reference material, review MEMORY.md before import, and verify memory-derived claims before acting on them.\n\nRisk: Network-facing memory endpoints could expose stored context if bound beyond localhost.\n\nMitigation: Keep the memory server bound to localhost and avoid exposing ports 3111 or 3113 to untrusted networks.\n\n## Reference(s):\n\n- [agentmemory MCP Tools Reference](references/mcp-tools.md)\n- [agentmemory and MEMORY.md Coordination Guide](references/coordination.md)\n- [OpenClaw Plugin Manifest](references/openclaw-plugin/openclaw.plugin.json)\n- [OpenClaw Plugin Package Metadata](references/openclaw-plugin/package.json)\n- [OpenClaw Plugin Source](references/openclaw-plugin/plugin.mjs)\n- [ClawHub skill page](https://clawhub.ai/lufei4/skills/agentmemory-mcp)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown with inline shell, JSON, and JavaScript snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Includes installation, configuration, verification, troubleshooting, migration, and removal guidance for an OpenClaw memory integration.]\n\n## Skill Version(s):\n\n1.3.0 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.9.15: 8 files, 13663 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), SKILL.md (18248b), _meta.json (135b)\n\nFile v0.9.15:SKILL.md\n\n---\nname: agentmemory\ndescription: |\n Persistent cross-session memory for OpenClaw via agentmemory.\n \n Use when:\n - User asks to install/configure agentmemory for OpenClaw\n - Agent needs to remember project context, decisions, or workflows across sessions\n - Setting up long-term memory for OpenClaw (MCP mode)\n - Integrating agentmemory with existing MEMORY.md system\n - Troubleshooting agentmemory connection issues\n - Upgrading or removing agentmemory\n\n ───────────────────────────────\n \n 基于 agentmemory 的跨会话持久化记忆系统，适用于 OpenClaw。\n \n 适用场景：\n - 用户要求安装/配置 agentmemory\n - Agent 需要记住项目背景、决策或工作流程\n - 为 OpenClaw 设置长期记忆（MCP 模式）\n - 与现有 MEMORY.md 系统集成\n - 排查 agentmemory 连接问题\n - 升级或移除 agentmemory\n---\n\n# agentmemory Integration for OpenClaw\n\n> **Status**: ✅ Verified working with OpenClaw v2026.5.4\n> **Version**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP Tools**: 107 REST + 51 MCP tools available\n\nPersistent memory server giving OpenClaw agents cross-session semantic recall via BM25+Vector+Graph RRF hybrid search.\n\n## Architecture\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)\n ↓\n SQLite/KV Store\n ↓\n Viewer (localhost:3113)\n```\n\n## Quick Start (MCP Mode — 5 minutes)\n\n### Step 1: Install and start memory server\n\n```bash\n# Server runs on localhost:3111, viewer at localhost:3113\nnpx @agentmemory/agentmemory\n```\n\n### Step 2: Configure OpenClaw MCP\n\nAdd to `~/.openclaw/openclaw.json` under `mcp.servers`:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n### Step 3: Restart Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n### Step 4: Verify\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# View memory dashboard\nopen http://localhost:3113\n```\n\n---\n\n## systemd Service (Production)\n\nFor auto-start and reliable background operation:\n\n### Install service\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp ./scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# Enable linger (boot without login)\nloginctl enable-linger $(whoami)\n```\n\n### Service commands\n\n```bash\nsystemctl --user status agentmemory # Check status\njournalctl --user -u agentmemory -f # View logs\nsystemctl --user restart agentmemory # Restart\n```\n\n### Service environment variables\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `NODE_ENV` | `production` | Production mode |\n| `AGENTMEMORY_PORT` | `3111` | MCP API port |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | Dashboard port |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker image tag |\n\n> **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.\n\n### Docker socket\n\nThe 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.\n\n---\n\n## Search Mode: BM25 vs Vector\n\nagentmemory supports two search modes:\n\n| Mode | Description | Use when |\n|------|-------------|----------|\n| **BM25-only** | Keyword-based full-text search | Default, no API key needed |\n| **Hybrid (BM25+Vector)** | BM25 + semantic embeddings | Need semantic/synonym search |\n\n### Default: BM25-only (no configuration needed)\n\nBM25 covers 90%+ of searches for known terms (skill names, config keys, decision labels). Current status after setup:\n\n```\n[agentmemory] Embedding provider: none (BM25-only mode)\n```\n\n### Want vector search? Choose your embedding provider\n\nWhen you're ready to upgrade, choose from these free-tier options:\n\n| Provider | Free tier | Chinese | Setup |\n|----------|-----------|---------|-------|\n| **VoyageAI** | 50k tokens/month | ✅ Good | `VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai` |\n| **Cohere** | 50k tokens/month | ✅ Good | `COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere` |\n| **阿里云百炼 Qwen/E5** | ~$0.1/1M tokens | ✅ Excellent | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai` |\n\n**When user wants vector search**, ask them to choose one of the three, then configure accordingly:\n\n#### Option A: VoyageAI\n```ini\nEnvironment=EMBEDDING_PROVIDER=voyageai\nEnvironment=VOYAGE_API_KEY=your_voyage_key\n```\n\n#### Option B: Cohere\n```ini\nEnvironment=EMBEDDING_PROVIDER=cohere\nEnvironment=COHERE_API_KEY=your_cohere_key\n```\n\n#### Option C: 阿里云百炼 (Bailian)\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=your_bailian_key\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\nAfter configuring, reload and restart:\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\nVerify embedding is active:\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims) ← example for Bailian\n```\n\n---\n\n## Integration with MEMORY.md\n\nagentmemory and MEMORY.md serve different purposes — they coexist:\n\n| Layer | System | Purpose | Management |\n|-------|--------|---------|------------|\n| **Experience** | agentmemory | Manual save, semantic recall, cross-agent | `memory_save` (manual) |\n| **Knowledge** | MEMORY.md | Curated decisions, preferences, rules | Manual |\n\n### Coordination rules\n\n- **Before major tasks**: Call `memory_recall` to retrieve relevant experiences\n- **After important decisions**: Call `memory_save` with result\n- **Curated knowledge**: Stays in MEMORY.md (survives compaction)\n- **Session start**: Both systems loaded; no conflicts\n\n### After installation: migrate MEMORY.md (important!)\n\nAfter completing installation, migrate MEMORY.md content into agentmemory:\n\n1. **Open the dashboard to view current state**\n ```bash\n open http://localhost:3113\n ```\n Initially empty — migration populates it with searchable data.\n\n2. **Migrate MEMORY.md content**\n Use the CLI migrate command:\n ```bash\n agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **Verify migration results**\n After migration, reopen http://localhost:3113 to confirm data is stored.\n\n> Note: MEMORY.md stays intact — both systems coexist. agentmemory handles semantic search; MEMORY.md holds curated knowledge.\n\n---\n\n## Verification\n\nRun the verification script:\n```bash\nbash ./scripts/verify.sh\n```\n\nExpected output:\n- ✅ Memory server on port 3111\n- ✅ Health endpoint responding\n- ✅ Viewer available on port 3113\n- ✅ OpenClaw MCP configured\n- ✅ systemd service active\n\n### Manual health check\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\nHealthy response shows: `{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n## MCP Tools (Key ones for OpenClaw)\n\n| Tool | Purpose |\n|------|---------|\n| `memory_recall` | Semantic search across all memories |\n| `memory_save` | Store new memories with type/tags |\n| `memory_smart_search` | Hybrid BM25+vector search |\n| `memory_timeline` | View memories chronologically |\n| `memory_profile` | Agent's memory usage stats |\n| `memory_snapshot` | Full memory export as JSON |\n| `memory_forget` | Delete specific memories |\n| `memory_context` | Get context for current session |\n| `memory_lesson_save` | Record lessons learned from errors |\n| `memory_reflect` | Cluster knowledge graph for insights |\n\nSee `references/mcp-tools.md` for full list of 51 tools.\n\n---\n\n## Uninstall\n\n### MCP mode removal\n\n1. Remove from `openclaw.json` mcp.servers section\n2. `openclaw gateway restart`\n\n### Full removal\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Connection refused on port 3111\"\nMemory server not running. Start it:\n```bash\nsystemctl --user start agentmemory\n# Or manually: npx @agentmemory/agentmemory\n```\n\n### \"Config invalid\" after editing openclaw.json\nEnsure `mcp.servers` path (not `mcpServers`). Run:\n```bash\nopenclaw status # Should show \"Config valid\"\n```\n\n### View real-time logs\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n### iii-engine version mismatch\nIf `api::graph-stats` and other v0.11.6 functions are not registered:\n```bash\n# Check current iii-engine version\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# Ensure AGENTMEMORY_III_VERSION=latest is set in systemd service\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n```\n\n### WebSocket disconnected (1006)\nThis is typically a client-side event (browser tab switch, network glitch), not a Gateway failure. Check:\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\nIf Gateway shows `webchat connected` after the disconnect, the service is fine.\n\n---\n\n---\n\n## 中文版 Chinese Version\n\n### agentmemory × OpenClaw 集成\n\n> **状态**: ✅ 已验证兼容 OpenClaw v2026.5.4\n> **版本**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP 工具**: 107 个 REST + 51 个 MCP 工具\n\n持久化记忆服务，为 OpenClaw Agent 提供跨会话语义召回能力，基于 BM25+向量+图谱混合搜索。\n\n### 系统架构\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP 服务器 (localhost:3111)\n ↓\n SQLite/KV 存储\n ↓\n 浏览器仪表板 (localhost:3113)\n```\n\n### 快速开始（MCP 模式 — 5 分钟）\n\n**第一步：启动记忆服务器**\n\n```bash\nnpx @agentmemory/agentmemory\n# 服务器端口：3111（API）、3113（浏览器仪表板）\n```\n\n**第二步：配置 OpenClaw MCP**\n\n在 `~/.openclaw/openclaw.json` 中加入：\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n**第三步：重启 Gateway**\n\n```bash\nopenclaw gateway restart\n```\n\n**第四步：验证**\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# 打开记忆仪表板\nopen http://localhost:3113\n```\n\n---\n\n### 搜索模式：BM25 vs 向量\n\nagentmemory 支持两种搜索模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| **仅 BM25** | 基于关键词的全文搜索 | 默认，无需 API key |\n| **混合搜索 (BM25+向量)** | BM25 + 语义 embeddings | 需要同义词/语义搜索时 |\n\n### 默认：仅 BM25（无需配置）\n\nBM25 对已知术语（技能名、配置键、决策标签）的搜索已覆盖 90%+ 需求。安装后的状态：\n\n```\n[agentmemory] Embedding provider: none (BM25-only mode)\n```\n\n### 需要向量搜索？从三个免费选项中选择\n\n准备好后再升级，从以下免费额度选项中选择：\n\n| 提供商 | 免费额度 | 中文支持 | 配置方式 |\n|--------|----------|----------|----------|\n| **VoyageAI** | 50k tokens/月 | ✅ 良好 | `VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai` |\n| **Cohere** | 50k tokens/月 | ✅ 良好 | `COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere` |\n| **阿里云百炼 Qwen/E5** | ~$0.1/1M tokens | ✅ 优秀 | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai` |\n\n**当用户需要向量搜索时**，先让他们从三个选项中选择，然后再配置：\n\n#### 选项 A: VoyageAI\n```ini\nEnvironment=EMBEDDING_PROVIDER=voyageai\nEnvironment=VOYAGE_API_KEY=your_voyage_key\n```\n\n#### 选项 B: Cohere\n```ini\nEnvironment=EMBEDDING_PROVIDER=cohere\nEnvironment=COHERE_API_KEY=your_cohere_key\n```\n\n#### 选项 C: 阿里云百炼 (Bailian)\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=your_bailian_key\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\n配置完成后，重载并重启服务：\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\n验证 embedding 已启用：\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims) ← Bailian 配置示例\n```\n\n---\n\n### systemd 服务（生产环境推荐）\n\n**安装服务：**\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp ./scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# 启用 linger（开机免登录自动启动）\nloginctl enable-linger $(whoami)\n```\n\n**服务环境变量：**\n\n| 变量 | 值 | 说明 |\n|------|-----|------|\n| `NODE_ENV` | `production` | 生产模式 |\n| `AGENTMEMORY_PORT` | `3111` | MCP API 端口 |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | 仪表板端口 |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker 镜像标签 |\n\n> **重要**：`AGENTMEMORY_III_VERSION=latest` 用于绕过 npm CLI 硬编码的 `IIPINNED_VERSION=0.11.2`，确保使用最新的稳定版 iii-engine（v0.11.6）。\n\n**Docker socket**：服务使用系统 Docker socket `/var/run/docker.sock`（属于 `root:docker` 组）。不要设置 `DOCKER_HOST` 环境变量，默认 socket 路径已正确。\n\n---\n\n### 与 MEMORY.md 的协同\n\n两个系统分工不同，共存互补：\n\n| 层级 | 系统 | 用途 | 管理方式 |\n|------|------|------|----------|\n| **经验层** | agentmemory | 手动保存重要内容、语义召回、跨 Agent 共享 | `memory_save`（手动调用） |\n| **知识层** | MEMORY.md | 精心整理的决策、偏好、规则 | 手工维护 |\n\n**协调规则：**\n\n- **任务开始前** → 调用 `memory_recall` 检索相关经验\n- **重要决策后** → 调用 `memory_save` 保存结果\n- **精选知识** → 留在 MEMORY.md（不受会话压缩影响）\n- **会话启动时** → 两个系统同时加载，无冲突\n\n### 首次安装后：迁移 MEMORY.md（重要！）\n\n安装完成后，将 MEMORY.md 的核心内容迁移到 agentmemory：\n\n1. **打开仪表板查看当前状态**\n ```bash\n open http://localhost:3113\n ```\n 初始是空的，迁移后才有数据可搜。\n\n2. **迁移 MEMORY.md 内容**\n 使用 CLI migrate 命令：\n ```bash\n agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **验证迁移结果**\n 迁移完成后，再次打开 http://localhost:3113 查看记忆仪表板，确认数据已入库。\n\n> 注意：MEMORY.md 本身保留不动，两套系统共存 — agentmemory 负责语义搜索，MEMORY.md 负责手工精修知识。\n\n---\n\n### 核心 MCP 工具\n\n| 工具 | 用途 |\n|------|------|\n| `memory_recall` | 跨所有记忆的语义搜索 |\n| `memory_save` | 以类型/标签存储新记忆 |\n| `memory_smart_search` | BM25+向量混合搜索 |\n| `memory_timeline` | 按时间线查看记忆 |\n| `memory_profile` | Agent 记忆使用统计 |\n| `memory_snapshot` | 完整记忆导出 JSON |\n| `memory_forget` | 删除指定记忆 |\n| `memory_context` | 获取当前会话上下文 |\n| `memory_lesson_save` | 记录从错误中学到的教训 |\n| `memory_reflect` | 聚类知识图谱提炼洞察 |\n\n完整 51 个工具列表见 `references/mcp-tools.md`。\n\n---\n\n### 验证\n\n```bash\nbash ./scripts/verify.sh\n```\n\n预期结果：\n- ✅ 记忆服务器在 3111 端口运行\n- ✅ Health 端点正常响应\n- ✅ 仪表板在 3113 端口可访问\n- ✅ OpenClaw MCP 已配置\n- ✅ systemd 服务已激活\n\n### 手动健康检查\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\n健康响应包含：`{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n### 卸载\n\n**仅移除 MCP 模式：**\n\n1. 从 `openclaw.json` 的 `mcp.servers` 中删除 agentmemory 条目\n2. 执行 `openclaw gateway restart`\n\n**完全移除：**\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n### 故障排查\n\n**\"Connection refused on port 3111\"**\n服务器未启动，启动它：\n```bash\nsystemctl --user start agentmemory\n# 或手动：npx @agentmemory/agentmemory\n```\n\n**修改 openclaw.json 后提示 \"Config invalid\"**\n确保路径是 `mcp.servers`（不是 `mcpServers`）：\n```bash\nopenclaw status # 应显示 \"Config valid\"\n```\n\n**查看实时日志：**\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n**iii-engine 版本不匹配**\n如果 `api::graph-stats` 等 v0.11.6 函数未注册：\n```bash\n# 检查当前 iii-engine 版本\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# 确认 systemd service 中设置了 AGENTMEMORY_III_VERSION=latest\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n\n**WebSocket 断连 (1006)**\n这通常是客户端事件（浏览器切页、网络抖动），非 Gateway 故障。检查：\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\n如果 Gateway 在断连后显示 `webchat connected`，说明服务正常。\n\n---\n\n*🦞 Skill by 龙虾 — agentmemory-mcp on ClawHub: https://clawhub.ai/lufei4/agentmemory-mcp*\n\nFile v0.9.15:_meta.json\n\n{\n \"ownerId\": \"kn73p7swcakp5x33a5x0sf7yes859vh8\",\n \"slug\": \"agentmemory-mcp\",\n \"version\": \"0.9.15\",\n \"publishedAt\": 1778658051673\n}\n\nFile v0.9.15:references/coordination.md\n\n# agentmemory + MEMORY.md Coordination Guide\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ OpenClaw Memory System │\n├─────────────────────────────────────────────────────────┤\n│ │\n│ ┌───────────────────────┐ ┌────────────────────────┐ │\n│ │ agentmemory (MCP) │ │ MEMORY.md / AGENTS │ │\n│ │ │ │ │ │\n│ │ • Auto-capture │ │ • Curated rules │ │\n│ │ • Semantic search │ │ • Preferences │ │\n│ │ • 95.2% R@5 │ │ • Manual updates │ │\n│ │ • Cross-agent │ │ • Human-readable │ │\n│ │ • Session sync │ │ • Survives compaction │ │\n│ └───────────────────────┘ └────────────────────────┘ │\n│ │ │ │\n│ └────────┬───────────────┘ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ OpenClaw Agent │ │\n│ └─────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Layer Responsibilities\n\n| Layer | Tool | What's stored | Management |\n|-------|------|--------------|------------|\n| **Experience** | agentmemory | Tasks, decisions, results, observations | Automatic |\n| **Knowledge** | MEMORY.md | Rules, preferences, long-term facts | Manual |\n| **Daily** | memory/YYYY-MM-DD.md | Session logs, events | Automatic |\n\n---\n\n## Agent Behavior Guidelines\n\n### Session Start\n\n1. **MEMORY.md + daily logs** → loaded automatically by OpenClaw\n2. **agentmemory** → agent can call `memory_recall` for additional context\n3. No conflict — both systems serve different purposes\n\n### During Work\n\n- **Task decision**: Call `memory_smart_search` to check if similar task was done\n- **Success**: Call `memory_save` with result, e.g.:\n ```\n memory_save(\"Deployed backend to Railway, took 8 minutes\", \n type=\"observation\", tags=[\"deployment\"])\n ```\n- **Failure**: Call `memory_save` noting what didn't work\n\n### Session End\n\n- OpenClaw auto-captures conversation via `plugins.slots.memory`\n- Critical learnings → also write to MEMORY.md (persists beyond compaction)\n\n---\n\n## Migration from Existing MEMORY.md\n\nIf MEMORY.md has valuable content, migrate selectively:\n\n```bash\n# Start server first\nnpx @agentmemory/agentmemory\n\n# In another terminal, import MEMORY.md\nnpx @agentmemory/agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md\n```\n\nOr use `memory_import` in batches:\n\n```javascript\n// Example: Migrate section by section\nmemory_import([\n { content: \"Backend deployed via Railway CLI\", type: \"observation\", tags: [\"deployment\"] },\n { content: \"User prefers brief responses\", type: \"preference\", tags: [\"communication\"] }\n], strategy: \"merge\")\n```\n\n---\n\n## Conflict Resolution\n\n**Q: What if agentmemory says something different from MEMORY.md?**\n\n| Scenario | Resolution |\n|----------|------------|\n| MEMORY.md has rule, agentmemory has conflicting experience | Trust MEMORY.md (curated), log conflict in agentmemory |\n| agentmemory has newer info | Update MEMORY.md if verified |\n| Uncertainty | Log to agentmemory, keep both until resolved |\n\n**Principle**: MEMORY.md is source of truth for rules; agentmemory is evidence of experience.\n\n---\n\n## Maintenance\n\n### Periodic (monthly)\n\n1. Read `memory_stats()` output\n2. Check for gaps with `memory_analyze(\"gaps\")`\n3. Review MEMORY.md for outdated entries\n\n### When Conflicting\n\n```bash\n# View memory for specific topic\nmemory_timeline(tag=\"deployment\", limit=10)\n\n# Check provenance\nmemory_trace(id=\"\")\n\n# Update or correct\nmemory_update(id=\"\", content=\"corrected information\")\n```\n\n---\n\n## Optimal Configuration\n\nFor maximum capability, run both systems:\n\n1. **agentmemory MCP** — handles automatic capture, semantic search, cross-agent sharing\n2. **MEMORY.md** — handles curated rules, preferences, compliance requirements\n\nThe agent uses whichever is appropriate for the situation — no forced preference.\n\nFile v0.9.15:references/mcp-tools.md\n\n# agentmemory MCP Tools Reference\n\nComplete list of 43 MCP tools available via `agentmemory` MCP server.\n\n## Core Memory Operations\n\n### memory_recall\nRetrieve semantically relevant memories.\n```\nmemory_recall(query: string, limit?: number, threshold?: number)\n```\n\n### memory_save\nStore new memories with optional metadata.\n```\nmemory_save(content: string, type?: \"observation\" | \"decision\" | \"fact\" | \"preference\", tags?: string[])\n```\n\n### memory_smart_search\nHybrid BM25 + vector search.\n```\nmemory_smart_search(query: string, limit?: number)\n```\n\n### memory_forget\nDelete memories by ID or pattern.\n```\nmemory_forget(pattern?: string, id?: string)\n```\n\n### memory_update\nUpdate existing memory content or metadata.\n```\nmemory_update(id: string, content?: string, tags?: string[])\n```\n\n---\n\n## Navigation & Exploration\n\n### memory_timeline\nView memories chronologically.\n```\nmemory_timeline(start?: date, end?: date, limit?: number)\n```\n\n### memory_tree\nHierarchical view of knowledge graph.\n```\nmemory_tree(root?: string, depth?: number)\n```\n\n### memory_trace\nView provenance/derivation chain of a memory.\n```\nmemory_trace(id: string)\n```\n\n### memory_stats\nMemory usage statistics.\n```\nmemory_stats()\n```\n\n---\n\n## Agent Integration\n\n### memory_profile\nDetailed agent memory profile.\n```\nmemory_profile(agent_id?: string)\n```\n\n### memory_snapshot\nExport all memories as JSON.\n```\nmemory_snapshot(format?: \"json\" | \"markdown\")\n```\n\n### memory_import\nBulk import memories.\n```\nmemory_import(memory: Memory[], strategy?: \"merge\" | \"replace\")\n```\n\n### memory_compact\nCompress and consolidate memories.\n```\nmemory_compact(threshold?: number)\n```\n\n---\n\n## Knowledge Graph\n\n### memory_relate\nCreate relationships between memories.\n```\nmemory_relate(from_id: string, to_id: string, relationship?: string)\n```\n\n### memory_graph_query\nQuery knowledge graph.\n```\nmemory_graph_query(query: string, depth?: number)\n```\n\n### memory_entities\nList all entities in knowledge graph.\n```\nmemory_entities(type?: string)\n```\n\n### memory_paths\nFind paths between two memories.\n```\nmemory_paths(from_id: string, to_id: string)\n```\n\n---\n\n## Context & Sessions\n\n### memory_context\nGet context for current session.\n```\nmemory_context(include_recent?: number)\n```\n\n### memory_inject\nInject memories into current context.\n```\nmemory_inject(limit?: number, match?: string)\n```\n\n### memory_session\nSession-specific memory operations.\n```\nmemory_session(op: \"save\" | \"load\" | \"clear\", data?: any)\n```\n\n---\n\n## Configuration\n\n### memory_config\nView/update agentmemory configuration.\n```\nmemory_config(op: \"get\" | \"set\", key?: string, value?: any)\n```\n\n### memory_channels\nList available memory channels.\n```\nmemory_channels()\n```\n\n---\n\n## Advanced\n\n### memory_analyze\nAnalyze memory patterns.\n```\nmemory_analyze(analysis_type?: \"coverage\" | \"gaps\" | \"redundancy\")\n```\n\n### memory_consolidate\nConsolidate fragmented memories.\n```\nmemory_consolidate(strategy?: \"simple\" | \"semantic\")\n```\n\n### memory_evict\nEvict low-value memories.\n```\nmemory_evict(threshold?: number, dry_run?: boolean)\n```\n\n---\n\n## Usage in OpenClaw\n\n### Before starting a task\n```\nAgent can call: memory_recall(\"project architecture decisions\")\n→ Returns relevant past decisions, avoiding re-explaining\n```\n\n### After completing a task\n```\nAgent can call: memory_save(\"Deployed backend to production via railway\", \n type=\"decision\", tags=[\"deployment\", \"backend\"])\n→ Stores experience for future reference\n```\n\n### Check task deduplication\n```\nAgent can call: memory_smart_search(\"deploy backend production\")\n→ If match found, agent can reuse previous workflow\n```\n\nFile v0.9.15:references/openclaw-plugin/openclaw.plugin.json\n\n{\n \"schema_version\": 1,\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"Persistent cross-session memory with semantic search\",\n \"slots\": [\"memory\"],\n \"config\": {\n \"base_url\": {\n \"type\": \"string\",\n \"default\": \"http://localhost:3111\",\n \"description\": \"agentmemory server URL\"\n },\n \"token_budget\": {\n \"type\": \"number\",\n \"default\": 2000,\n \"description\": \"Max tokens per recall injection\"\n },\n \"min_confidence\": {\n \"type\": \"number\",\n \"default\": 0.5,\n \"description\": \"Minimum confidence threshold for recall\"\n },\n \"fallback_on_error\": {\n \"type\": \"boolean\",\n \"default\": true,\n \"description\": \"Continue without memory if server unavailable\"\n },\n \"timeout_ms\": {\n \"type\": \"number\",\n \"default\": 5000,\n \"description\": \"Request timeout in milliseconds\"\n }\n },\n \"hooks\": {\n \"beforeAgent\": \"onBeforeAgent\",\n \"afterAgent\": \"onAfterAgent\"\n },\n \"requirements\": {\n \"server\": \"agentmemory\",\n \"min_openclaw_version\": \"1.0.0\"\n }\n}\n\nFile v0.9.15:references/openclaw-plugin/package.json\n\n{\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"agentmemory plugin for OpenClaw - persistent cross-session memory\",\n \"main\": \"plugin.mjs\",\n \"openclaw\": {\n \"slots\": [\"memory\"],\n \"version\": \">=1.0.0\"\n },\n \"dependencies\": {\n \"axios\": \"^1.6.0\"\n }\n}\n\nArchive v0.9.14: 8 files, 13663 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), SKILL.md (18248b), _meta.json (135b)\n\nFile v0.9.14:SKILL.md\n\n---\nname: agentmemory\ndescription: |\n Persistent cross-session memory for OpenClaw via agentmemory.\n \n Use when:\n - User asks to install/configure agentmemory for OpenClaw\n - Agent needs to remember project context, decisions, or workflows across sessions\n - Setting up long-term memory for OpenClaw (MCP mode)\n - Integrating agentmemory with existing MEMORY.md system\n - Troubleshooting agentmemory connection issues\n - Upgrading or removing agentmemory\n\n ───────────────────────────────\n \n 基于 agentmemory 的跨会话持久化记忆系统，适用于 OpenClaw。\n \n 适用场景：\n - 用户要求安装/配置 agentmemory\n - Agent 需要记住项目背景、决策或工作流程\n - 为 OpenClaw 设置长期记忆（MCP 模式）\n - 与现有 MEMORY.md 系统集成\n - 排查 agentmemory 连接问题\n - 升级或移除 agentmemory\n---\n\n# agentmemory Integration for OpenClaw\n\n> **Status**: ✅ Verified working with OpenClaw v2026.5.4\n> **Version**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP Tools**: 107 REST + 51 MCP tools available\n\nPersistent memory server giving OpenClaw agents cross-session semantic recall via BM25+Vector+Graph RRF hybrid search.\n\n## Architecture\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)\n ↓\n SQLite/KV Store\n ↓\n Viewer (localhost:3113)\n```\n\n## Quick Start (MCP Mode — 5 minutes)\n\n### Step 1: Install and start memory server\n\n```bash\n# Server runs on localhost:3111, viewer at localhost:3113\nnpx @agentmemory/agentmemory\n```\n\n### Step 2: Configure OpenClaw MCP\n\nAdd to `~/.openclaw/openclaw.json` under `mcp.servers`:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n### Step 3: Restart Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n### Step 4: Verify\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# View memory dashboard\nopen http://localhost:3113\n```\n\n---\n\n## systemd Service (Production)\n\nFor auto-start and reliable background operation:\n\n### Install service\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp ./scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# Enable linger (boot without login)\nloginctl enable-linger $(whoami)\n```\n\n### Service commands\n\n```bash\nsystemctl --user status agentmemory # Check status\njournalctl --user -u agentmemory -f # View logs\nsystemctl --user restart agentmemory # Restart\n```\n\n### Service environment variables\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `NODE_ENV` | `production` | Production mode |\n| `AGENTMEMORY_PORT` | `3111` | MCP API port |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | Dashboard port |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker image tag |\n\n> **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.\n\n### Docker socket\n\nThe 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.\n\n---\n\n## Search Mode: BM25 vs Vector\n\nagentmemory supports two search modes:\n\n| Mode | Description | Use when |\n|------|-------------|----------|\n| **BM25-only** | Keyword-based full-text search | Default, no API key needed |\n| **Hybrid (BM25+Vector)** | BM25 + semantic embeddings | Need semantic/synonym search |\n\n### Default: BM25-only (no configuration needed)\n\nBM25 covers 90%+ of searches for known terms (skill names, config keys, decision labels). Current status after setup:\n\n```\n[agentmemory] Embedding provider: none (BM25-only mode)\n```\n\n### Want vector search? Choose your embedding provider\n\nWhen you're ready to upgrade, choose from these free-tier options:\n\n| Provider | Free tier | Chinese | Setup |\n|----------|-----------|---------|-------|\n| **VoyageAI** | 50k tokens/month | ✅ Good | `VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai` |\n| **Cohere** | 50k tokens/month | ✅ Good | `COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere` |\n| **阿里云百炼 Qwen/E5** | ~$0.1/1M tokens | ✅ Excellent | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai` |\n\n**When user wants vector search**, ask them to choose one of the three, then configure accordingly:\n\n#### Option A: VoyageAI\n```ini\nEnvironment=EMBEDDING_PROVIDER=voyageai\nEnvironment=VOYAGE_API_KEY=your_voyage_key\n```\n\n#### Option B: Cohere\n```ini\nEnvironment=EMBEDDING_PROVIDER=cohere\nEnvironment=COHERE_API_KEY=your_cohere_key\n```\n\n#### Option C: 阿里云百炼 (Bailian)\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=your_bailian_key\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\nAfter configuring, reload and restart:\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\nVerify embedding is active:\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims) ← example for Bailian\n```\n\n---\n\n## Integration with MEMORY.md\n\nagentmemory and MEMORY.md serve different purposes — they coexist:\n\n| Layer | System | Purpose | Management |\n|-------|--------|---------|------------|\n| **Experience** | agentmemory | Manual save, semantic recall, cross-agent | `memory_save` (manual) |\n| **Knowledge** | MEMORY.md | Curated decisions, preferences, rules | Manual |\n\n### Coordination rules\n\n- **Before major tasks**: Call `memory_recall` to retrieve relevant experiences\n- **After important decisions**: Call `memory_save` with result\n- **Curated knowledge**: Stays in MEMORY.md (survives compaction)\n- **Session start**: Both systems loaded; no conflicts\n\n### After installation: migrate MEMORY.md (important!)\n\nAfter completing installation, migrate MEMORY.md content into agentmemory:\n\n1. **Open the dashboard to view current state**\n ```bash\n open http://localhost:3113\n ```\n Initially empty — migration populates it with searchable data.\n\n2. **Migrate MEMORY.md content**\n Use the CLI migrate command:\n ```bash\n agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **Verify migration results**\n After migration, reopen http://localhost:3113 to confirm data is stored.\n\n> Note: MEMORY.md stays intact — both systems coexist. agentmemory handles semantic search; MEMORY.md holds curated knowledge.\n\n---\n\n## Verification\n\nRun the verification script:\n```bash\nbash ./scripts/verify.sh\n```\n\nExpected output:\n- ✅ Memory server on port 3111\n- ✅ Health endpoint responding\n- ✅ Viewer available on port 3113\n- ✅ OpenClaw MCP configured\n- ✅ systemd service active\n\n### Manual health check\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\nHealthy response shows: `{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n## MCP Tools (Key ones for OpenClaw)\n\n| Tool | Purpose |\n|------|---------|\n| `memory_recall` | Semantic search across all memories |\n| `memory_save` | Store new memories with type/tags |\n| `memory_smart_search` | Hybrid BM25+vector search |\n| `memory_timeline` | View memories chronologically |\n| `memory_profile` | Agent's memory usage stats |\n| `memory_snapshot` | Full memory export as JSON |\n| `memory_forget` | Delete specific memories |\n| `memory_context` | Get context for current session |\n| `memory_lesson_save` | Record lessons learned from errors |\n| `memory_reflect` | Cluster knowledge graph for insights |\n\nSee `references/mcp-tools.md` for full list of 51 tools.\n\n---\n\n## Uninstall\n\n### MCP mode removal\n\n1. Remove from `openclaw.json` mcp.servers section\n2. `openclaw gateway restart`\n\n### Full removal\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Connection refused on port 3111\"\nMemory server not running. Start it:\n```bash\nsystemctl --user start agentmemory\n# Or manually: npx @agentmemory/agentmemory\n```\n\n### \"Config invalid\" after editing openclaw.json\nEnsure `mcp.servers` path (not `mcpServers`). Run:\n```bash\nopenclaw status # Should show \"Config valid\"\n```\n\n### View real-time logs\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n### iii-engine version mismatch\nIf `api::graph-stats` and other v0.11.6 functions are not registered:\n```bash\n# Check current iii-engine version\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# Ensure AGENTMEMORY_III_VERSION=latest is set in systemd service\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n```\n\n### WebSocket disconnected (1006)\nThis is typically a client-side event (browser tab switch, network glitch), not a Gateway failure. Check:\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\nIf Gateway shows `webchat connected` after the disconnect, the service is fine.\n\n---\n\n---\n\n## 中文版 Chinese Version\n\n### agentmemory × OpenClaw 集成\n\n> **状态**: ✅ 已验证兼容 OpenClaw v2026.5.4\n> **版本**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP 工具**: 107 个 REST + 51 个 MCP 工具\n\n持久化记忆服务，为 OpenClaw Agent 提供跨会话语义召回能力，基于 BM25+向量+图谱混合搜索。\n\n### 系统架构\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP 服务器 (localhost:3111)\n ↓\n SQLite/KV 存储\n ↓\n 浏览器仪表板 (localhost:3113)\n```\n\n### 快速开始（MCP 模式 — 5 分钟）\n\n**第一步：启动记忆服务器**\n\n```bash\nnpx @agentmemory/agentmemory\n# 服务器端口：3111（API）、3113（浏览器仪表板）\n```\n\n**第二步：配置 OpenClaw MCP**\n\n在 `~/.openclaw/openclaw.json` 中加入：\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n**第三步：重启 Gateway**\n\n```bash\nopenclaw gateway restart\n```\n\n**第四步：验证**\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# 打开记忆仪表板\nopen http://localhost:3113\n```\n\n---\n\n### 搜索模式：BM25 vs 向量\n\nagentmemory 支持两种搜索模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| **仅 BM25** | 基于关键词的全文搜索 | 默认，无需 API key |\n| **混合搜索 (BM25+向量)** | BM25 + 语义 embeddings | 需要同义词/语义搜索时 |\n\n### 默认：仅 BM25（无需配置）\n\nBM25 对已知术语（技能名、配置键、决策标签）的搜索已覆盖 90%+ 需求。安装后的状态：\n\n```\n[agentmemory] Embedding provider: none (BM25-only mode)\n```\n\n### 需要向量搜索？从三个免费选项中选择\n\n准备好后再升级，从以下免费额度选项中选择：\n\n| 提供商 | 免费额度 | 中文支持 | 配置方式 |\n|--------|----------|----------|----------|\n| **VoyageAI** | 50k tokens/月 | ✅ 良好 | `VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai` |\n| **Cohere** | 50k tokens/月 | ✅ 良好 | `COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere` |\n| **阿里云百炼 Qwen/E5** | ~$0.1/1M tokens | ✅ 优秀 | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai` |\n\n**当用户需要向量搜索时**，先让他们从三个选项中选择，然后再配置：\n\n#### 选项 A: VoyageAI\n```ini\nEnvironment=EMBEDDING_PROVIDER=voyageai\nEnvironment=VOYAGE_API_KEY=your_voyage_key\n```\n\n#### 选项 B: Cohere\n```ini\nEnvironment=EMBEDDING_PROVIDER=cohere\nEnvironment=COHERE_API_KEY=your_cohere_key\n```\n\n#### 选项 C: 阿里云百炼 (Bailian)\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=your_bailian_key\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\n配置完成后，重载并重启服务：\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\n验证 embedding 已启用：\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims) ← Bailian 配置示例\n```\n\n---\n\n### systemd 服务（生产环境推荐）\n\n**安装服务：**\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp ./scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# 启用 linger（开机免登录自动启动）\nloginctl enable-linger $(whoami)\n```\n\n**服务环境变量：**\n\n| 变量 | 值 | 说明 |\n|------|-----|------|\n| `NODE_ENV` | `production` | 生产模式 |\n| `AGENTMEMORY_PORT` | `3111` | MCP API 端口 |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | 仪表板端口 |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker 镜像标签 |\n\n> **重要**：`AGENTMEMORY_III_VERSION=latest` 用于绕过 npm CLI 硬编码的 `IIPINNED_VERSION=0.11.2`，确保使用最新的稳定版 iii-engine（v0.11.6）。\n\n**Docker socket**：服务使用系统 Docker socket `/var/run/docker.sock`（属于 `root:docker` 组）。不要设置 `DOCKER_HOST` 环境变量，默认 socket 路径已正确。\n\n---\n\n### 与 MEMORY.md 的协同\n\n两个系统分工不同，共存互补：\n\n| 层级 | 系统 | 用途 | 管理方式 |\n|------|------|------|----------|\n| **经验层** | agentmemory | 手动保存重要内容、语义召回、跨 Agent 共享 | `memory_save`（手动调用） |\n| **知识层** | MEMORY.md | 精心整理的决策、偏好、规则 | 手工维护 |\n\n**协调规则：**\n\n- **任务开始前** → 调用 `memory_recall` 检索相关经验\n- **重要决策后** → 调用 `memory_save` 保存结果\n- **精选知识** → 留在 MEMORY.md（不受会话压缩影响）\n- **会话启动时** → 两个系统同时加载，无冲突\n\n### 首次安装后：迁移 MEMORY.md（重要！）\n\n安装完成后，将 MEMORY.md 的核心内容迁移到 agentmemory：\n\n1. **打开仪表板查看当前状态**\n ```bash\n open http://localhost:3113\n ```\n 初始是空的，迁移后才有数据可搜。\n\n2. **迁移 MEMORY.md 内容**\n 使用 CLI migrate 命令：\n ```bash\n agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **验证迁移结果**\n 迁移完成后，再次打开 http://localhost:3113 查看记忆仪表板，确认数据已入库。\n\n> 注意：MEMORY.md 本身保留不动，两套系统共存 — agentmemory 负责语义搜索，MEMORY.md 负责手工精修知识。\n\n---\n\n### 核心 MCP 工具\n\n| 工具 | 用途 |\n|------|------|\n| `memory_recall` | 跨所有记忆的语义搜索 |\n| `memory_save` | 以类型/标签存储新记忆 |\n| `memory_smart_search` | BM25+向量混合搜索 |\n| `memory_timeline` | 按时间线查看记忆 |\n| `memory_profile` | Agent 记忆使用统计 |\n| `memory_snapshot` | 完整记忆导出 JSON |\n| `memory_forget` | 删除指定记忆 |\n| `memory_context` | 获取当前会话上下文 |\n| `memory_lesson_save` | 记录从错误中学到的教训 |\n| `memory_reflect` | 聚类知识图谱提炼洞察 |\n\n完整 51 个工具列表见 `references/mcp-tools.md`。\n\n---\n\n### 验证\n\n```bash\nbash ./scripts/verify.sh\n```\n\n预期结果：\n- ✅ 记忆服务器在 3111 端口运行\n- ✅ Health 端点正常响应\n- ✅ 仪表板在 3113 端口可访问\n- ✅ OpenClaw MCP 已配置\n- ✅ systemd 服务已激活\n\n### 手动健康检查\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\n健康响应包含：`{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n### 卸载\n\n**仅移除 MCP 模式：**\n\n1. 从 `openclaw.json` 的 `mcp.servers` 中删除 agentmemory 条目\n2. 执行 `openclaw gateway restart`\n\n**完全移除：**\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n### 故障排查\n\n**\"Connection refused on port 3111\"**\n服务器未启动，启动它：\n```bash\nsystemctl --user start agentmemory\n# 或手动：npx @agentmemory/agentmemory\n```\n\n**修改 openclaw.json 后提示 \"Config invalid\"**\n确保路径是 `mcp.servers`（不是 `mcpServers`）：\n```bash\nopenclaw status # 应显示 \"Config valid\"\n```\n\n**查看实时日志：**\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n**iii-engine 版本不匹配**\n如果 `api::graph-stats` 等 v0.11.6 函数未注册：\n```bash\n# 检查当前 iii-engine 版本\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# 确认 systemd service 中设置了 AGENTMEMORY_III_VERSION=latest\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n\n**WebSocket 断连 (1006)**\n这通常是客户端事件（浏览器切页、网络抖动），非 Gateway 故障。检查：\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\n如果 Gateway 在断连后显示 `webchat connected`，说明服务正常。\n\n---\n\n*🦞 Skill by 龙虾 — agentmemory-mcp on ClawHub: https://clawhub.ai/lufei4/agentmemory-mcp*\n\nFile v0.9.14:_meta.json\n\n{\n \"ownerId\": \"kn73p7swcakp5x33a5x0sf7yes859vh8\",\n \"slug\": \"agentmemory-mcp\",\n \"version\": \"0.9.14\",\n \"publishedAt\": 1778656388041\n}\n\nFile v0.9.14:references/coordination.md\n\n# agentmemory + MEMORY.md Coordination Guide\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ OpenClaw Memory System │\n├─────────────────────────────────────────────────────────┤\n│ │\n│ ┌───────────────────────┐ ┌────────────────────────┐ │\n│ │ agentmemory (MCP) │ │ MEMORY.md / AGENTS │ │\n│ │ │ │ │ │\n│ │ • Auto-capture │ │ • Curated rules │ │\n│ │ • Semantic search │ │ • Preferences │ │\n│ │ • 95.2% R@5 │ │ • Manual updates │ │\n│ │ • Cross-agent │ │ • Human-readable │ │\n│ │ • Session sync │ │ • Survives compaction │ │\n│ └───────────────────────┘ └────────────────────────┘ │\n│ │ │ │\n│ └────────┬───────────────┘ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ OpenClaw Agent │ │\n│ └─────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Layer Responsibilities\n\n| Layer | Tool | What's stored | Management |\n|-------|------|--------------|------------|\n| **Experience** | agentmemory | Tasks, decisions, results, observations | Automatic |\n| **Knowledge** | MEMORY.md | Rules, preferences, long-term facts | Manual |\n| **Daily** | memory/YYYY-MM-DD.md | Session logs, events | Automatic |\n\n---\n\n## Agent Behavior Guidelines\n\n### Session Start\n\n1. **MEMORY.md + daily logs** → loaded automatically by OpenClaw\n2. **agentmemory** → agent can call `memory_recall` for additional context\n3. No conflict — both systems serve different purposes\n\n### During Work\n\n- **Task decision**: Call `memory_smart_search` to check if similar task was done\n- **Success**: Call `memory_save` with result, e.g.:\n ```\n memory_save(\"Deployed backend to Railway, took 8 minutes\", \n type=\"observation\", tags=[\"deployment\"])\n ```\n- **Failure**: Call `memory_save` noting what didn't work\n\n### Session End\n\n- OpenClaw auto-captures conversation via `plugins.slots.memory`\n- Critical learnings → also write to MEMORY.md (persists beyond compaction)\n\n---\n\n## Migration from Existing MEMORY.md\n\nIf MEMORY.md has valuable content, migrate selectively:\n\n```bash\n# Start server first\nnpx @agentmemory/agentmemory\n\n# In another terminal, import MEMORY.md\nnpx @agentmemory/agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md\n```\n\nOr use `memory_import` in batches:\n\n```javascript\n// Example: Migrate section by section\nmemory_import([\n { content: \"Backend deployed via Railway CLI\", type: \"observation\", tags: [\"deployment\"] },\n { content: \"User prefers brief responses\", type: \"preference\", tags: [\"communication\"] }\n], strategy: \"merge\")\n```\n\n---\n\n## Conflict Resolution\n\n**Q: What if agentmemory says something different from MEMORY.md?**\n\n| Scenario | Resolution |\n|----------|------------|\n| MEMORY.md has rule, agentmemory has conflicting experience | Trust MEMORY.md (curated), log conflict in agentmemory |\n| agentmemory has newer info | Update MEMORY.md if verified |\n| Uncertainty | Log to agentmemory, keep both until resolved |\n\n**Principle**: MEMORY.md is source of truth for rules; agentmemory is evidence of experience.\n\n---\n\n## Maintenance\n\n### Periodic (monthly)\n\n1. Read `memory_stats()` output\n2. Check for gaps with `memory_analyze(\"gaps\")`\n3. Review MEMORY.md for outdated entries\n\n### When Conflicting\n\n```bash\n# View memory for specific topic\nmemory_timeline(tag=\"deployment\", limit=10)\n\n# Check provenance\nmemory_trace(id=\"\")\n\n# Update or correct\nmemory_update(id=\"\", content=\"corrected information\")\n```\n\n---\n\n## Optimal Configuration\n\nFor maximum capability, run both systems:\n\n1. **agentmemory MCP** — handles automatic capture, semantic search, cross-agent sharing\n2. **MEMORY.md** — handles curated rules, preferences, compliance requirements\n\nThe agent uses whichever is appropriate for the situation — no forced preference.\n\nFile v0.9.14:references/mcp-tools.md\n\n# agentmemory MCP Tools Reference\n\nComplete list of 43 MCP tools available via `agentmemory` MCP server.\n\n## Core Memory Operations\n\n### memory_recall\nRetrieve semantically relevant memories.\n```\nmemory_recall(query: string, limit?: number, threshold?: number)\n```\n\n### memory_save\nStore new memories with optional metadata.\n```\nmemory_save(content: string, type?: \"observation\" | \"decision\" | \"fact\" | \"preference\", tags?: string[])\n```\n\n### memory_smart_search\nHybrid BM25 + vector search.\n```\nmemory_smart_search(query: string, limit?: number)\n```\n\n### memory_forget\nDelete memories by ID or pattern.\n```\nmemory_forget(pattern?: string, id?: string)\n```\n\n### memory_update\nUpdate existing memory content or metadata.\n```\nmemory_update(id: string, content?: string, tags?: string[])\n```\n\n---\n\n## Navigation & Exploration\n\n### memory_timeline\nView memories chronologically.\n```\nmemory_timeline(start?: date, end?: date, limit?: number)\n```\n\n### memory_tree\nHierarchical view of knowledge graph.\n```\nmemory_tree(root?: string, depth?: number)\n```\n\n### memory_trace\nView provenance/derivation chain of a memory.\n```\nmemory_trace(id: string)\n```\n\n### memory_stats\nMemory usage statistics.\n```\nmemory_stats()\n```\n\n---\n\n## Agent Integration\n\n### memory_profile\nDetailed agent memory profile.\n```\nmemory_profile(agent_id?: string)\n```\n\n### memory_snapshot\nExport all memories as JSON.\n```\nmemory_snapshot(format?: \"json\" | \"markdown\")\n```\n\n### memory_import\nBulk import memories.\n```\nmemory_import(memory: Memory[], strategy?: \"merge\" | \"replace\")\n```\n\n### memory_compact\nCompress and consolidate memories.\n```\nmemory_compact(threshold?: number)\n```\n\n---\n\n## Knowledge Graph\n\n### memory_relate\nCreate relationships between memories.\n```\nmemory_relate(from_id: string, to_id: string, relationship?: string)\n```\n\n### memory_graph_query\nQuery knowledge graph.\n```\nmemory_graph_query(query: string, depth?: number)\n```\n\n### memory_entities\nList all entities in knowledge graph.\n```\nmemory_entities(type?: string)\n```\n\n### memory_paths\nFind paths between two memories.\n```\nmemory_paths(from_id: string, to_id: string)\n```\n\n---\n\n## Context & Sessions\n\n### memory_context\nGet context for current session.\n```\nmemory_context(include_recent?: number)\n```\n\n### memory_inject\nInject memories into current context.\n```\nmemory_inject(limit?: number, match?: string)\n```\n\n### memory_session\nSession-specific memory operations.\n```\nmemory_session(op: \"save\" | \"load\" | \"clear\", data?: any)\n```\n\n---\n\n## Configuration\n\n### memory_config\nView/update agentmemory configuration.\n```\nmemory_config(op: \"get\" | \"set\", key?: string, value?: any)\n```\n\n### memory_channels\nList available memory channels.\n```\nmemory_channels()\n```\n\n---\n\n## Advanced\n\n### memory_analyze\nAnalyze memory patterns.\n```\nmemory_analyze(analysis_type?: \"coverage\" | \"gaps\" | \"redundancy\")\n```\n\n### memory_consolidate\nConsolidate fragmented memories.\n```\nmemory_consolidate(strategy?: \"simple\" | \"semantic\")\n```\n\n### memory_evict\nEvict low-value memories.\n```\nmemory_evict(threshold?: number, dry_run?: boolean)\n```\n\n---\n\n## Usage in OpenClaw\n\n### Before starting a task\n```\nAgent can call: memory_recall(\"project architecture decisions\")\n→ Returns relevant past decisions, avoiding re-explaining\n```\n\n### After completing a task\n```\nAgent can call: memory_save(\"Deployed backend to production via railway\", \n type=\"decision\", tags=[\"deployment\", \"backend\"])\n→ Stores experience for future reference\n```\n\n### Check task deduplication\n```\nAgent can call: memory_smart_search(\"deploy backend production\")\n→ If match found, agent can reuse previous workflow\n```\n\nFile v0.9.14:references/openclaw-plugin/openclaw.plugin.json\n\n{\n \"schema_version\": 1,\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"Persistent cross-session memory with semantic search\",\n \"slots\": [\"memory\"],\n \"config\": {\n \"base_url\": {\n \"type\": \"string\",\n \"default\": \"http://localhost:3111\",\n \"description\": \"agentmemory server URL\"\n },\n \"token_budget\": {\n \"type\": \"number\",\n \"default\": 2000,\n \"description\": \"Max tokens per recall injection\"\n },\n \"min_confidence\": {\n \"type\": \"number\",\n \"default\": 0.5,\n \"description\": \"Minimum confidence threshold for recall\"\n },\n \"fallback_on_error\": {\n \"type\": \"boolean\",\n \"default\": true,\n \"description\": \"Continue without memory if server unavailable\"\n },\n \"timeout_ms\": {\n \"type\": \"number\",\n \"default\": 5000,\n \"description\": \"Request timeout in milliseconds\"\n }\n },\n \"hooks\": {\n \"beforeAgent\": \"onBeforeAgent\",\n \"afterAgent\": \"onAfterAgent\"\n },\n \"requirements\": {\n \"server\": \"agentmemory\",\n \"min_openclaw_version\": \"1.0.0\"\n }\n}\n\nFile v0.9.14:references/openclaw-plugin/package.json\n\n{\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"agentmemory plugin for OpenClaw - persistent cross-session memory\",\n \"main\": \"plugin.mjs\",\n \"openclaw\": {\n \"slots\": [\"memory\"],\n \"version\": \">=1.0.0\"\n },\n \"dependencies\": {\n \"axios\": \"^1.6.0\"\n }\n}\n\nArchive v0.9.13: 8 files, 13681 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), SKILL.md (18464b), _meta.json (135b)\n\nFile v0.9.13:SKILL.md\n\n---\nname: agentmemory\ndescription: |\n Persistent cross-session memory for OpenClaw via agentmemory.\n \n Use when:\n - User asks to install/configure agentmemory for OpenClaw\n - Agent needs to remember project context, decisions, or workflows across sessions\n - Setting up long-term memory for OpenClaw (MCP mode)\n - Integrating agentmemory with existing MEMORY.md system\n - Troubleshooting agentmemory connection issues\n - Upgrading or removing agentmemory\n\n ───────────────────────────────\n \n 基于 agentmemory 的跨会话持久化记忆系统，适用于 OpenClaw。\n \n 适用场景：\n - 用户要求安装/配置 agentmemory\n - Agent 需要记住项目背景、决策或工作流程\n - 为 OpenClaw 设置长期记忆（MCP 模式）\n - 与现有 MEMORY.md 系统集成\n - 排查 agentmemory 连接问题\n - 升级或移除 agentmemory\n---\n\n# agentmemory Integration for OpenClaw\n\n> **Status**: ✅ Verified working with OpenClaw v2026.5.4\n> **Version**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP Tools**: 107 REST + 51 MCP tools available\n\nPersistent memory server giving OpenClaw agents cross-session semantic recall via BM25+Vector+Graph RRF hybrid search.\n\n## Architecture\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)\n ↓\n SQLite/KV Store\n ↓\n Viewer (localhost:3113)\n```\n\n## Quick Start (MCP Mode — 5 minutes)\n\n### Step 1: Install and start memory server\n\n```bash\n# Server runs on localhost:3111, viewer at localhost:3113\nnpx @agentmemory/agentmemory\n```\n\n### Step 2: Configure OpenClaw MCP\n\nAdd to `~/.openclaw/openclaw.json` under `mcp.servers`:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n### Step 3: Restart Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n### Step 4: Verify\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# View memory dashboard\nopen http://localhost:3113\n```\n\n---\n\n## systemd Service (Production)\n\nFor auto-start and reliable background operation:\n\n### Install service\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# Enable linger (boot without login)\nloginctl enable-linger $(whoami)\n```\n\n### Service commands\n\n```bash\nsystemctl --user status agentmemory # Check status\njournalctl --user -u agentmemory -f # View logs\nsystemctl --user restart agentmemory # Restart\n```\n\n### Service environment variables\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `NODE_ENV` | `production` | Production mode |\n| `AGENTMEMORY_PORT` | `3111` | MCP API port |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | Dashboard port |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker image tag |\n\n> **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.\n\n### Docker socket\n\nThe 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.\n\n---\n\n## Search Mode: BM25 vs Vector\n\nagentmemory supports two search modes:\n\n| Mode | Description | Use when |\n|------|-------------|----------|\n| **BM25-only** | Keyword-based full-text search | Default, no API key needed |\n| **Hybrid (BM25+Vector)** | BM25 + semantic embeddings | Need semantic/synonym search |\n\n### Default: BM25-only (no configuration needed)\n\nBM25 covers 90%+ of searches for known terms (skill names, config keys, decision labels). Current status after setup:\n\n```\n[agentmemory] Embedding provider: none (BM25-only mode)\n```\n\n### Want vector search? Choose your embedding provider\n\nWhen you're ready to upgrade, choose from these free-tier options:\n\n| Provider | Free tier | Chinese | Setup |\n|----------|-----------|---------|-------|\n| **VoyageAI** | 50k tokens/month | ✅ Good | `VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai` |\n| **Cohere** | 50k tokens/month | ✅ Good | `COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere` |\n| **阿里云百炼 Qwen/E5** | ~$0.1/1M tokens | ✅ Excellent | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai` |\n\n**When user wants vector search**, ask them to choose one of the three, then configure accordingly:\n\n#### Option A: VoyageAI\n```ini\nEnvironment=EMBEDDING_PROVIDER=voyageai\nEnvironment=VOYAGE_API_KEY=your_voyage_key\n```\n\n#### Option B: Cohere\n```ini\nEnvironment=EMBEDDING_PROVIDER=cohere\nEnvironment=COHERE_API_KEY=your_cohere_key\n```\n\n#### Option C: 阿里云百炼 (Bailian)\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=your_bailian_key\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\nAfter configuring, reload and restart:\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\nVerify embedding is active:\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims) ← example for Bailian\n```\n\n---\n\n## Integration with MEMORY.md\n\nagentmemory and MEMORY.md serve different purposes — they coexist:\n\n| Layer | System | Purpose | Management |\n|-------|--------|---------|------------|\n| **Experience** | agentmemory | Manual save, semantic recall, cross-agent | `memory_save` (manual) |\n| **Knowledge** | MEMORY.md | Curated decisions, preferences, rules | Manual |\n\n### Coordination rules\n\n- **Before major tasks**: Call `memory_recall` to retrieve relevant experiences\n- **After important decisions**: Call `memory_save` with result\n- **Curated knowledge**: Stays in MEMORY.md (survives compaction)\n- **Session start**: Both systems loaded; no conflicts\n\n### After installation: migrate MEMORY.md (important!)\n\nAfter completing installation, migrate MEMORY.md content into agentmemory:\n\n1. **Open the dashboard to view current state**\n ```bash\n open http://localhost:3113\n ```\n Initially empty — migration populates it with searchable data.\n\n2. **Migrate MEMORY.md content**\n Use the CLI migrate command:\n ```bash\n agentmemory migrate --from-file /home/lufei/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **Verify migration results**\n After migration, reopen http://localhost:3113 to confirm data is stored.\n\n> Note: MEMORY.md stays intact — both systems coexist. agentmemory handles semantic search; MEMORY.md holds curated knowledge.\n\n---\n\n## Verification\n\nRun the verification script:\n```bash\nbash /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/verify.sh\n```\n\nExpected output:\n- ✅ Memory server on port 3111\n- ✅ Health endpoint responding\n- ✅ Viewer available on port 3113\n- ✅ OpenClaw MCP configured\n- ✅ systemd service active\n\n### Manual health check\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\nHealthy response shows: `{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n## MCP Tools (Key ones for OpenClaw)\n\n| Tool | Purpose |\n|------|---------|\n| `memory_recall` | Semantic search across all memories |\n| `memory_save` | Store new memories with type/tags |\n| `memory_smart_search` | Hybrid BM25+vector search |\n| `memory_timeline` | View memories chronologically |\n| `memory_profile` | Agent's memory usage stats |\n| `memory_snapshot` | Full memory export as JSON |\n| `memory_forget` | Delete specific memories |\n| `memory_context` | Get context for current session |\n| `memory_lesson_save` | Record lessons learned from errors |\n| `memory_reflect` | Cluster knowledge graph for insights |\n\nSee `references/mcp-tools.md` for full list of 51 tools.\n\n---\n\n## Uninstall\n\n### MCP mode removal\n\n1. Remove from `openclaw.json` mcp.servers section\n2. `openclaw gateway restart`\n\n### Full removal\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Connection refused on port 3111\"\nMemory server not running. Start it:\n```bash\nsystemctl --user start agentmemory\n# Or manually: npx @agentmemory/agentmemory\n```\n\n### \"Config invalid\" after editing openclaw.json\nEnsure `mcp.servers` path (not `mcpServers`). Run:\n```bash\nopenclaw status # Should show \"Config valid\"\n```\n\n### View real-time logs\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n### iii-engine version mismatch\nIf `api::graph-stats` and other v0.11.6 functions are not registered:\n```bash\n# Check current iii-engine version\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# Ensure AGENTMEMORY_III_VERSION=latest is set in systemd service\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n```\n\n### WebSocket disconnected (1006)\nThis is typically a client-side event (browser tab switch, network glitch), not a Gateway failure. Check:\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\nIf Gateway shows `webchat connected` after the disconnect, the service is fine.\n\n---\n\n---\n\n## 中文版 Chinese Version\n\n### agentmemory × OpenClaw 集成\n\n> **状态**: ✅ 已验证兼容 OpenClaw v2026.5.4\n> **版本**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP 工具**: 107 个 REST + 51 个 MCP 工具\n\n持久化记忆服务，为 OpenClaw Agent 提供跨会话语义召回能力，基于 BM25+向量+图谱混合搜索。\n\n### 系统架构\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP 服务器 (localhost:3111)\n ↓\n SQLite/KV 存储\n ↓\n 浏览器仪表板 (localhost:3113)\n```\n\n### 快速开始（MCP 模式 — 5 分钟）\n\n**第一步：启动记忆服务器**\n\n```bash\nnpx @agentmemory/agentmemory\n# 服务器端口：3111（API）、3113（浏览器仪表板）\n```\n\n**第二步：配置 OpenClaw MCP**\n\n在 `~/.openclaw/openclaw.json` 中加入：\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n**第三步：重启 Gateway**\n\n```bash\nopenclaw gateway restart\n```\n\n**第四步：验证**\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# 打开记忆仪表板\nopen http://localhost:3113\n```\n\n---\n\n### 搜索模式：BM25 vs 向量\n\nagentmemory 支持两种搜索模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| **仅 BM25** | 基于关键词的全文搜索 | 默认，无需 API key |\n| **混合搜索 (BM25+向量)** | BM25 + 语义 embeddings | 需要同义词/语义搜索时 |\n\n### 默认：仅 BM25（无需配置）\n\nBM25 对已知术语（技能名、配置键、决策标签）的搜索已覆盖 90%+ 需求。安装后的状态：\n\n```\n[agentmemory] Embedding provider: none (BM25-only mode)\n```\n\n### 需要向量搜索？从三个免费选项中选择\n\n准备好后再升级，从以下免费额度选项中选择：\n\n| 提供商 | 免费额度 | 中文支持 | 配置方式 |\n|--------|----------|----------|----------|\n| **VoyageAI** | 50k tokens/月 | ✅ 良好 | `VOYAGE_API_KEY` + `EMBEDDING_PROVIDER=voyageai` |\n| **Cohere** | 50k tokens/月 | ✅ 良好 | `COHERE_API_KEY` + `EMBEDDING_PROVIDER=cohere` |\n| **阿里云百炼 Qwen/E5** | ~$0.1/1M tokens | ✅ 优秀 | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_PROVIDER=openai` |\n\n**当用户需要向量搜索时**，先让他们从三个选项中选择，然后再配置：\n\n#### 选项 A: VoyageAI\n```ini\nEnvironment=EMBEDDING_PROVIDER=voyageai\nEnvironment=VOYAGE_API_KEY=your_voyage_key\n```\n\n#### 选项 B: Cohere\n```ini\nEnvironment=EMBEDDING_PROVIDER=cohere\nEnvironment=COHERE_API_KEY=your_cohere_key\n```\n\n#### 选项 C: 阿里云百炼 (Bailian)\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=your_bailian_key\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\n配置完成后，重载并重启服务：\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\n验证 embedding 已启用：\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims) ← Bailian 配置示例\n```\n\n---\n\n### systemd 服务（生产环境推荐）\n\n**安装服务：**\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# 启用 linger（开机免登录自动启动）\nloginctl enable-linger $(whoami)\n```\n\n**服务环境变量：**\n\n| 变量 | 值 | 说明 |\n|------|-----|------|\n| `NODE_ENV` | `production` | 生产模式 |\n| `AGENTMEMORY_PORT` | `3111` | MCP API 端口 |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | 仪表板端口 |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker 镜像标签 |\n\n> **重要**：`AGENTMEMORY_III_VERSION=latest` 用于绕过 npm CLI 硬编码的 `IIPINNED_VERSION=0.11.2`，确保使用最新的稳定版 iii-engine（v0.11.6）。\n\n**Docker socket**：服务使用系统 Docker socket `/var/run/docker.sock`（属于 `root:docker` 组）。不要设置 `DOCKER_HOST` 环境变量，默认 socket 路径已正确。\n\n---\n\n### 与 MEMORY.md 的协同\n\n两个系统分工不同，共存互补：\n\n| 层级 | 系统 | 用途 | 管理方式 |\n|------|------|------|----------|\n| **经验层** | agentmemory | 手动保存重要内容、语义召回、跨 Agent 共享 | `memory_save`（手动调用） |\n| **知识层** | MEMORY.md | 精心整理的决策、偏好、规则 | 手工维护 |\n\n**协调规则：**\n\n- **任务开始前** → 调用 `memory_recall` 检索相关经验\n- **重要决策后** → 调用 `memory_save` 保存结果\n- **精选知识** → 留在 MEMORY.md（不受会话压缩影响）\n- **会话启动时** → 两个系统同时加载，无冲突\n\n### 首次安装后：迁移 MEMORY.md（重要！）\n\n安装完成后，将 MEMORY.md 的核心内容迁移到 agentmemory：\n\n1. **打开仪表板查看当前状态**\n ```bash\n open http://localhost:3113\n ```\n 初始是空的，迁移后才有数据可搜。\n\n2. **迁移 MEMORY.md 内容**\n 使用 CLI migrate 命令：\n ```bash\n agentmemory migrate --from-file /home/lufei/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **验证迁移结果**\n 迁移完成后，再次打开 http://localhost:3113 查看记忆仪表板，确认数据已入库。\n\n> 注意：MEMORY.md 本身保留不动，两套系统共存 — agentmemory 负责语义搜索，MEMORY.md 负责手工精修知识。\n\n---\n\n### 核心 MCP 工具\n\n| 工具 | 用途 |\n|------|------|\n| `memory_recall` | 跨所有记忆的语义搜索 |\n| `memory_save` | 以类型/标签存储新记忆 |\n| `memory_smart_search` | BM25+向量混合搜索 |\n| `memory_timeline` | 按时间线查看记忆 |\n| `memory_profile` | Agent 记忆使用统计 |\n| `memory_snapshot` | 完整记忆导出 JSON |\n| `memory_forget` | 删除指定记忆 |\n| `memory_context` | 获取当前会话上下文 |\n| `memory_lesson_save` | 记录从错误中学到的教训 |\n| `memory_reflect` | 聚类知识图谱提炼洞察 |\n\n完整 51 个工具列表见 `references/mcp-tools.md`。\n\n---\n\n### 验证\n\n```bash\nbash /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/verify.sh\n```\n\n预期结果：\n- ✅ 记忆服务器在 3111 端口运行\n- ✅ Health 端点正常响应\n- ✅ 仪表板在 3113 端口可访问\n- ✅ OpenClaw MCP 已配置\n- ✅ systemd 服务已激活\n\n### 手动健康检查\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\n健康响应包含：`{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n### 卸载\n\n**仅移除 MCP 模式：**\n\n1. 从 `openclaw.json` 的 `mcp.servers` 中删除 agentmemory 条目\n2. 执行 `openclaw gateway restart`\n\n**完全移除：**\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n### 故障排查\n\n**\"Connection refused on port 3111\"**\n服务器未启动，启动它：\n```bash\nsystemctl --user start agentmemory\n# 或手动：npx @agentmemory/agentmemory\n```\n\n**修改 openclaw.json 后提示 \"Config invalid\"**\n确保路径是 `mcp.servers`（不是 `mcpServers`）：\n```bash\nopenclaw status # 应显示 \"Config valid\"\n```\n\n**查看实时日志：**\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n**iii-engine 版本不匹配**\n如果 `api::graph-stats` 等 v0.11.6 函数未注册：\n```bash\n# 检查当前 iii-engine 版本\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# 确认 systemd service 中设置了 AGENTMEMORY_III_VERSION=latest\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n\n**WebSocket 断连 (1006)**\n这通常是客户端事件（浏览器切页、网络抖动），非 Gateway 故障。检查：\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\n如果 Gateway 在断连后显示 `webchat connected`，说明服务正常。\n\n---\n\n*🦞 Skill by 龙虾 — agentmemory-mcp on ClawHub: https://clawhub.ai/lufei4/agentmemory-mcp*\n\nFile v0.9.13:_meta.json\n\n{\n \"ownerId\": \"kn73p7swcakp5x33a5x0sf7yes859vh8\",\n \"slug\": \"agentmemory-mcp\",\n \"version\": \"0.9.13\",\n \"publishedAt\": 1778655331519\n}\n\nFile v0.9.13:references/coordination.md\n\n# agentmemory + MEMORY.md Coordination Guide\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ OpenClaw Memory System │\n├─────────────────────────────────────────────────────────┤\n│ │\n│ ┌───────────────────────┐ ┌────────────────────────┐ │\n│ │ agentmemory (MCP) │ │ MEMORY.md / AGENTS │ │\n│ │ │ │ │ │\n│ │ • Auto-capture │ │ • Curated rules │ │\n│ │ • Semantic search │ │ • Preferences │ │\n│ │ • 95.2% R@5 │ │ • Manual updates │ │\n│ │ • Cross-agent │ │ • Human-readable │ │\n│ │ • Session sync │ │ • Survives compaction │ │\n│ └───────────────────────┘ └────────────────────────┘ │\n│ │ │ │\n│ └────────┬───────────────┘ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ OpenClaw Agent │ │\n│ └─────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Layer Responsibilities\n\n| Layer | Tool | What's stored | Management |\n|-------|------|--------------|------------|\n| **Experience** | agentmemory | Tasks, decisions, results, observations | Automatic |\n| **Knowledge** | MEMORY.md | Rules, preferences, long-term facts | Manual |\n| **Daily** | memory/YYYY-MM-DD.md | Session logs, events | Automatic |\n\n---\n\n## Agent Behavior Guidelines\n\n### Session Start\n\n1. **MEMORY.md + daily logs** → loaded automatically by OpenClaw\n2. **agentmemory** → agent can call `memory_recall` for additional context\n3. No conflict — both systems serve different purposes\n\n### During Work\n\n- **Task decision**: Call `memory_smart_search` to check if similar task was done\n- **Success**: Call `memory_save` with result, e.g.:\n ```\n memory_save(\"Deployed backend to Railway, took 8 minutes\", \n type=\"observation\", tags=[\"deployment\"])\n ```\n- **Failure**: Call `memory_save` noting what didn't work\n\n### Session End\n\n- OpenClaw auto-captures conversation via `plugins.slots.memory`\n- Critical learnings → also write to MEMORY.md (persists beyond compaction)\n\n---\n\n## Migration from Existing MEMORY.md\n\nIf MEMORY.md has valuable content, migrate selectively:\n\n```bash\n# Start server first\nnpx @agentmemory/agentmemory\n\n# In another terminal, import MEMORY.md\nnpx @agentmemory/agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md\n```\n\nOr use `memory_import` in batches:\n\n```javascript\n// Example: Migrate section by section\nmemory_import([\n { content: \"Backend deployed via Railway CLI\", type: \"observation\", tags: [\"deployment\"] },\n { content: \"User prefers brief responses\", type: \"preference\", tags: [\"communication\"] }\n], strategy: \"merge\")\n```\n\n---\n\n## Conflict Resolution\n\n**Q: What if agentmemory says something different from MEMORY.md?**\n\n| Scenario | Resolution |\n|----------|------------|\n| MEMORY.md has rule, agentmemory has conflicting experience | Trust MEMORY.md (curated), log conflict in agentmemory |\n| agentmemory has newer info | Update MEMORY.md if verified |\n| Uncertainty | Log to agentmemory, keep both until resolved |\n\n**Principle**: MEMORY.md is source of truth for rules; agentmemory is evidence of experience.\n\n---\n\n## Maintenance\n\n### Periodic (monthly)\n\n1. Read `memory_stats()` output\n2. Check for gaps with `memory_analyze(\"gaps\")`\n3. Review MEMORY.md for outdated entries\n\n### When Conflicting\n\n```bash\n# View memory for specific topic\nmemory_timeline(tag=\"deployment\", limit=10)\n\n# Check provenance\nmemory_trace(id=\"\")\n\n# Update or correct\nmemory_update(id=\"\", content=\"corrected information\")\n```\n\n---\n\n## Optimal Configuration\n\nFor maximum capability, run both systems:\n\n1. **agentmemory MCP** — handles automatic capture, semantic search, cross-agent sharing\n2. **MEMORY.md** — handles curated rules, preferences, compliance requirements\n\nThe agent uses whichever is appropriate for the situation — no forced preference.\n\nFile v0.9.13:references/mcp-tools.md\n\n# agentmemory MCP Tools Reference\n\nComplete list of 43 MCP tools available via `agentmemory` MCP server.\n\n## Core Memory Operations\n\n### memory_recall\nRetrieve semantically relevant memories.\n```\nmemory_recall(query: string, limit?: number, threshold?: number)\n```\n\n### memory_save\nStore new memories with optional metadata.\n```\nmemory_save(content: string, type?: \"observation\" | \"decision\" | \"fact\" | \"preference\", tags?: string[])\n```\n\n### memory_smart_search\nHybrid BM25 + vector search.\n```\nmemory_smart_search(query: string, limit?: number)\n```\n\n### memory_forget\nDelete memories by ID or pattern.\n```\nmemory_forget(pattern?: string, id?: string)\n```\n\n### memory_update\nUpdate existing memory content or metadata.\n```\nmemory_update(id: string, content?: string, tags?: string[])\n```\n\n---\n\n## Navigation & Exploration\n\n### memory_timeline\nView memories chronologically.\n```\nmemory_timeline(start?: date, end?: date, limit?: number)\n```\n\n### memory_tree\nHierarchical view of knowledge graph.\n```\nmemory_tree(root?: string, depth?: number)\n```\n\n### memory_trace\nView provenance/derivation chain of a memory.\n```\nmemory_trace(id: string)\n```\n\n### memory_stats\nMemory usage statistics.\n```\nmemory_stats()\n```\n\n---\n\n## Agent Integration\n\n### memory_profile\nDetailed agent memory profile.\n```\nmemory_profile(agent_id?: string)\n```\n\n### memory_snapshot\nExport all memories as JSON.\n```\nmemory_snapshot(format?: \"json\" | \"markdown\")\n```\n\n### memory_import\nBulk import memories.\n```\nmemory_import(memory: Memory[], strategy?: \"merge\" | \"replace\")\n```\n\n### memory_compact\nCompress and consolidate memories.\n```\nmemory_compact(threshold?: number)\n```\n\n---\n\n## Knowledge Graph\n\n### memory_relate\nCreate relationships between memories.\n```\nmemory_relate(from_id: string, to_id: string, relationship?: string)\n```\n\n### memory_graph_query\nQuery knowledge graph.\n```\nmemory_graph_query(query: string, depth?: number)\n```\n\n### memory_entities\nList all entities in knowledge graph.\n```\nmemory_entities(type?: string)\n```\n\n### memory_paths\nFind paths between two memories.\n```\nmemory_paths(from_id: string, to_id: string)\n```\n\n---\n\n## Context & Sessions\n\n### memory_context\nGet context for current session.\n```\nmemory_context(include_recent?: number)\n```\n\n### memory_inject\nInject memories into current context.\n```\nmemory_inject(limit?: number, match?: string)\n```\n\n### memory_session\nSession-specific memory operations.\n```\nmemory_session(op: \"save\" | \"load\" | \"clear\", data?: any)\n```\n\n---\n\n## Configuration\n\n### memory_config\nView/update agentmemory configuration.\n```\nmemory_config(op: \"get\" | \"set\", key?: string, value?: any)\n```\n\n### memory_channels\nList available memory channels.\n```\nmemory_channels()\n```\n\n---\n\n## Advanced\n\n### memory_analyze\nAnalyze memory patterns.\n```\nmemory_analyze(analysis_type?: \"coverage\" | \"gaps\" | \"redundancy\")\n```\n\n### memory_consolidate\nConsolidate fragmented memories.\n```\nmemory_consolidate(strategy?: \"simple\" | \"semantic\")\n```\n\n### memory_evict\nEvict low-value memories.\n```\nmemory_evict(threshold?: number, dry_run?: boolean)\n```\n\n---\n\n## Usage in OpenClaw\n\n### Before starting a task\n```\nAgent can call: memory_recall(\"project architecture decisions\")\n→ Returns relevant past decisions, avoiding re-explaining\n```\n\n### After completing a task\n```\nAgent can call: memory_save(\"Deployed backend to production via railway\", \n type=\"decision\", tags=[\"deployment\", \"backend\"])\n→ Stores experience for future reference\n```\n\n### Check task deduplication\n```\nAgent can call: memory_smart_search(\"deploy backend production\")\n→ If match found, agent can reuse previous workflow\n```\n\nFile v0.9.13:references/openclaw-plugin/openclaw.plugin.json\n\n{\n \"schema_version\": 1,\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"Persistent cross-session memory with semantic search\",\n \"slots\": [\"memory\"],\n \"config\": {\n \"base_url\": {\n \"type\": \"string\",\n \"default\": \"http://localhost:3111\",\n \"description\": \"agentmemory server URL\"\n },\n \"token_budget\": {\n \"type\": \"number\",\n \"default\": 2000,\n \"description\": \"Max tokens per recall injection\"\n },\n \"min_confidence\": {\n \"type\": \"number\",\n \"default\": 0.5,\n \"description\": \"Minimum confidence threshold for recall\"\n },\n \"fallback_on_error\": {\n \"type\": \"boolean\",\n \"default\": true,\n \"description\": \"Continue without memory if server unavailable\"\n },\n \"timeout_ms\": {\n \"type\": \"number\",\n \"default\": 5000,\n \"description\": \"Request timeout in milliseconds\"\n }\n },\n \"hooks\": {\n \"beforeAgent\": \"onBeforeAgent\",\n \"afterAgent\": \"onAfterAgent\"\n },\n \"requirements\": {\n \"server\": \"agentmemory\",\n \"min_openclaw_version\": \"1.0.0\"\n }\n}\n\nFile v0.9.13:references/openclaw-plugin/package.json\n\n{\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"agentmemory plugin for OpenClaw - persistent cross-session memory\",\n \"main\": \"plugin.mjs\",\n \"openclaw\": {\n \"slots\": [\"memory\"],\n \"version\": \">=1.0.0\"\n },\n \"dependencies\": {\n \"axios\": \"^1.6.0\"\n }\n}\n\nArchive v0.9.12: 8 files, 13954 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), SKILL.md (17847b), _meta.json (135b)\n\nFile v0.9.12:SKILL.md\n\n---\nname: agentmemory\ndescription: |\n Persistent cross-session memory for OpenClaw via agentmemory.\n \n Use when:\n - User asks to install/configure agentmemory for OpenClaw\n - Agent needs to remember project context, decisions, or workflows across sessions\n - Setting up long-term memory for OpenClaw (MCP mode)\n - Integrating agentmemory with existing MEMORY.md system\n - Troubleshooting agentmemory connection issues\n - Upgrading or removing agentmemory\n\n ───────────────────────────────\n \n 基于 agentmemory 的跨会话持久化记忆系统，适用于 OpenClaw。\n \n 适用场景：\n - 用户要求安装/配置 agentmemory\n - Agent 需要记住项目背景、决策或工作流程\n - 为 OpenClaw 设置长期记忆（MCP 模式）\n - 与现有 MEMORY.md 系统集成\n - 排查 agentmemory 连接问题\n - 升级或移除 agentmemory\n---\n\n# agentmemory Integration for OpenClaw\n\n> **Status**: ✅ Verified working with OpenClaw v2026.5.4\n> **Version**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP Tools**: 107 REST + 51 MCP tools available\n\nPersistent memory server giving OpenClaw agents cross-session semantic recall via BM25+Vector+Graph RRF hybrid search.\n\n## Architecture\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)\n ↓\n SQLite/KV Store\n ↓\n Viewer (localhost:3113)\n```\n\n## Quick Start (MCP Mode — 5 minutes)\n\n### Step 1: Install and start memory server\n\n```bash\n# Server runs on localhost:3111, viewer at localhost:3113\nnpx @agentmemory/agentmemory\n```\n\n### Step 2: Configure OpenClaw MCP\n\nAdd to `~/.openclaw/openclaw.json` under `mcp.servers`:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n### Step 3: Restart Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n### Step 4: Verify\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# View memory dashboard\nopen http://localhost:3113\n```\n\n---\n\n## MCP Tools (Key ones for OpenClaw)\n\n| Tool | Purpose |\n|------|---------|\n| `memory_recall` | Semantic search across all memories |\n| `memory_save` | Store new memories with type/tags |\n| `memory_smart_search` | Hybrid BM25+vector search |\n| `memory_timeline` | View memories chronologically |\n| `memory_profile` | Agent's memory usage stats |\n| `memory_snapshot` | Full memory export as JSON |\n| `memory_forget` | Delete specific memories |\n| `memory_context` | Get context for current session |\n| `memory_lesson_save` | Record lessons learned from errors |\n| `memory_reflect` | Cluster knowledge graph for insights |\n\nSee `references/mcp-tools.md` for full list of 51 tools.\n\n---\n\n## systemd Service (Production)\n\nFor auto-start and reliable background operation:\n\n### Install service\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# Enable linger (boot without login)\nloginctl enable-linger $(whoami)\n```\n\n### Service commands\n\n```bash\nsystemctl --user status agentmemory # Check status\njournalctl --user -u agentmemory -f # View logs\nsystemctl --user restart agentmemory # Restart\n```\n\n### Service environment variables\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `NODE_ENV` | `production` | Production mode |\n| `AGENTMEMORY_PORT` | `3111` | MCP API port |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | Dashboard port |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker image tag |\n\n> **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.\n\n### Docker socket\n\nThe 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.\n\n---\n\n## Embedding Provider: Alibaba Bailian (text-embedding-v4)\n\n> **Recommended for Chinese users** — uses your existing bailian API key for semantic search.\n\n**Configure the systemd service** with these environment variables:\n\n```ini\nEnvironment=EMBEDDING_PROVIDER=openai\nEnvironment=OPENAI_API_KEY=sk-6c0f8716ad654fdc9768448209f1814e\nEnvironment=OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1\nEnvironment=OPENAI_EMBEDDING_MODEL=text-embedding-v4\nEnvironment=OPENAI_EMBEDDING_DIMENSIONS=1024\n```\n\nThen reload and restart:\n```bash\nsystemctl --user daemon-reload\nsystemctl --user restart agentmemory\n```\n\n**Verify** the embedding provider is recognized:\n```bash\njournalctl --user -u agentmemory -n 5 --no-pager | grep \"Embedding provider\"\n# → [agentmemory] Embedding provider: openai (1024 dims)\n```\n\n**Test semantic search** (after saving some memories):\n```bash\n# Save a test memory\nagentmemory memory save --content \"I prefer qwen3.5-flash for coding\" --type preference\n\n# Search semantically\nagentmemory memory smart-search --query \"Which model is best for writing code?\"\n```\n\n**Model details**:\n- **Model**: text-embedding-v4 (aliyun bailian)\n- **Dimensions**: 1024\n- **Endpoint**: `https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings`\n- **Cost**: ~$0.1/1M tokens (very cheap)\n- **Chinese support**: ✅ Excellent\n\n---\n\n## Search Mode: BM25-only\n\n> **Current status**: iii-engine v0.11.6 running in BM25-only mode (no embedding provider configured).\n\nThis is a known limitation, not a fault:\n\n- LiteLLM proxy at `127.0.0.1:4000` does not support `/embeddings` endpoint (`No connected db` error)\n- No local GPU available for Ollama embedding models (GTX 1060 6GB)\n- BM25 covers 90%+ of known-term searches (skill names, config keys, decision labels)\n- Semantic search (e.g. \"大模型\" matching \"LLM\") is not available without an external embedding provider\n\n**If semantic search is needed**, configure an OpenRouter-compatible embedding API:\n```bash\nexport OPENROUTER_API_KEY=\"sk-...\"\nexport EMBEDDING_PROVIDER=openrouter\n```\nVoyageAI and Cohere both offer free tiers with generous quotas.\n\n---\n\n## Integration with MEMORY.md\n\nagentmemory and MEMORY.md serve different purposes — they coexist:\n\n| Layer | System | Purpose | Management |\n|-------|--------|---------|------------|\n| **Experience** | agentmemory | Manual save, semantic recall, cross-agent | `memory_save` (manual) |\n| **Knowledge** | MEMORY.md | Curated decisions, preferences, rules | Manual |\n\n### Coordination rules\n\n- **Before major tasks**: Call `memory_recall` to retrieve relevant experiences\n- **After important decisions**: Call `memory_save` with result\n- **Curated knowledge**: Stays in MEMORY.md (survives compaction)\n- **Session start**: Both systems loaded; no conflicts\n\n### After installation: migrate MEMORY.md (important!)\n\nAfter completing installation, migrate MEMORY.md content into agentmemory:\n\n1. **Open the dashboard to view current state**\n ```bash\n open http://localhost:3113\n ```\n Initially empty — migration populates it with searchable data.\n\n2. **Migrate MEMORY.md content**\n Use the CLI migrate command:\n ```bash\n agentmemory migrate --from-file /home/lufei/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **Verify migration results**\n After migration, reopen http://localhost:3113 to confirm data is stored.\n\n> Note: MEMORY.md stays intact — both systems coexist. agentmemory handles semantic search; MEMORY.md holds curated knowledge.\n\n---\n\n## Verification\n\nRun the verification script:\n```bash\nbash /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/verify.sh\n```\n\nExpected output:\n- ✅ Memory server on port 3111\n- ✅ Health endpoint responding\n- ✅ Viewer available on port 3113\n- ✅ OpenClaw MCP configured\n- ✅ systemd service active\n\n### Manual health check\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\nHealthy response shows: `{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n## Uninstall\n\n### MCP mode removal\n\n1. Remove from `openclaw.json` mcp.servers section\n2. `openclaw gateway restart`\n\n### Full removal\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Connection refused on port 3111\"\nMemory server not running. Start it:\n```bash\nsystemctl --user start agentmemory\n# Or manually: npx @agentmemory/agentmemory\n```\n\n### \"Config invalid\" after editing openclaw.json\nEnsure `mcp.servers` path (not `mcpServers`). Run:\n```bash\nopenclaw status # Should show \"Config valid\"\n```\n\n### View real-time logs\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n### iii-engine version mismatch\nIf `api::graph-stats` and other v0.11.6 functions are not registered:\n```bash\n# Check current iii-engine version\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# Ensure AGENTMEMORY_III_VERSION=latest is set in systemd service\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n```\n\n### WebSocket disconnected (1006)\nThis is typically a client-side event (browser tab switch, network glitch), not a Gateway failure. Check:\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\nIf Gateway shows `webchat connected` after the disconnect, the service is fine.\n\n---\n\n---\n\n## 中文版 Chinese Version\n\n### agentmemory × OpenClaw 集成\n\n> **状态**: ✅ 已验证兼容 OpenClaw v2026.5.4\n> **版本**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP 工具**: 107 个 REST + 51 个 MCP 工具\n\n持久化记忆服务，为 OpenClaw Agent 提供跨会话语义召回能力，基于 BM25+向量+图谱混合搜索。\n\n### 系统架构\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP 服务器 (localhost:3111)\n ↓\n SQLite/KV 存储\n ↓\n 浏览器仪表板 (localhost:3113)\n```\n\n### 快速开始（MCP 模式 — 5 分钟）\n\n**第一步：启动记忆服务器**\n\n```bash\nnpx @agentmemory/agentmemory\n# 服务器端口：3111（API）、3113（浏览器仪表板）\n```\n\n**第二步：配置 OpenClaw MCP**\n\n在 `~/.openclaw/openclaw.json` 中加入：\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n**第三步：重启 Gateway**\n\n```bash\nopenclaw gateway restart\n```\n\n**第四步：验证**\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# 打开记忆仪表板\nopen http://localhost:3113\n```\n\n---\n\n### 核心 MCP 工具\n\n| 工具 | 用途 |\n|------|------|\n| `memory_recall` | 跨所有记忆的语义搜索 |\n| `memory_save` | 以类型/标签存储新记忆 |\n| `memory_smart_search` | BM25+向量混合搜索 |\n| `memory_timeline` | 按时间线查看记忆 |\n| `memory_profile` | Agent 记忆使用统计 |\n| `memory_snapshot` | 完整记忆导出 JSON |\n| `memory_forget` | 删除指定记忆 |\n| `memory_context` | 获取当前会话上下文 |\n| `memory_lesson_save` | 记录从错误中学到的教训 |\n| `memory_reflect` | 聚类知识图谱提炼洞察 |\n\n完整 51 个工具列表见 `references/mcp-tools.md`。\n\n---\n\n### systemd 服务（生产环境推荐）\n\n**安装服务：**\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# 启用 linger（开机免登录自动启动）\nloginctl enable-linger $(whoami)\n```\n\n**服务环境变量：**\n\n| 变量 | 值 | 说明 |\n|------|-----|------|\n| `NODE_ENV` | `production` | 生产模式 |\n| `AGENTMEMORY_PORT` | `3111` | MCP API 端口 |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | 仪表板端口 |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker 镜像标签 |\n\n> **重要**：`AGENTMEMORY_III_VERSION=latest` 用于绕过 npm CLI 硬编码的 `IIPINNED_VERSION=0.11.2`，确保使用最新的稳定版 iii-engine（v0.11.6）。\n\n**Docker socket**：服务使用系统 Docker socket `/var/run/docker.sock`（属于 `root:docker` 组）。不要设置 `DOCKER_HOST` 环境变量，默认 socket 路径已正确。\n\n---\n\n### 搜索模式：BM25-only\n\n> **当前状态**：iii-engine v0.11.6 运行在 BM25-only 模式（未配置 embedding provider）。\n\n这是已知限制，不是故障：\n\n- LiteLLM proxy (`127.0.0.1:4000`) 不支持 `/embeddings` 端点（返回 `No connected db`）\n- 无本地 GPU 可运行 Ollama embedding 模型（GTX 1060 6GB）\n- BM25 对已知术语搜索（技能名、配置键、决策标签）已覆盖 90%+ 需求\n- 语义搜索（如\"大模型\"匹配\"LLM\"）需外部 embedding provider\n\n**如需语义搜索**，可配置 OpenRouter 兼容的 embedding API：\n```bash\nexport OPENROUTER_API_KEY=\"sk-...\"\nexport EMBEDDING_PROVIDER=openrouter\n```\nVoyageAI 和 Cohere 均有免费额度。\n\n---\n\n### 与 MEMORY.md 的协同\n\n两个系统分工不同，共存互补：\n\n| 层级 | 系统 | 用途 | 管理方式 |\n|------|------|------|----------|\n| **经验层** | agentmemory | 手动保存重要内容、语义召回、跨 Agent 共享 | `memory_save`（手动调用） |\n| **知识层** | MEMORY.md | 精心整理的决策、偏好、规则 | 手工维护 |\n\n**协调规则：**\n\n- **任务开始前** → 调用 `memory_recall` 检索相关经验\n- **重要决策后** → 调用 `memory_save` 保存结果\n- **精选知识** → 留在 MEMORY.md（不受会话压缩影响）\n- **会话启动时** → 两个系统同时加载，无冲突\n\n### 首次安装后：迁移 MEMORY.md（重要！）\n\n安装完成后，将 MEMORY.md 的核心内容迁移到 agentmemory：\n\n1. **打开仪表板查看当前状态**\n ```bash\n open http://localhost:3113\n ```\n 初始是空的，迁移后才有数据可搜。\n\n2. **迁移 MEMORY.md 内容**\n 使用 CLI migrate 命令：\n ```bash\n agentmemory migrate --from-file /home/lufei/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **验证迁移结果**\n 迁移完成后，再次打开 http://localhost:3113 查看记忆仪表板，确认数据已入库。\n\n> 注意：MEMORY.md 本身保留不动，两套系统共存 — agentmemory 负责语义搜索，MEMORY.md 负责手工精修知识。\n\n---\n\n### 验证\n\n```bash\nbash /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/verify.sh\n```\n\n预期结果：\n- ✅ 记忆服务器在 3111 端口运行\n- ✅ Health 端点正常响应\n- ✅ 仪表板在 3113 端口可访问\n- ✅ OpenClaw MCP 已配置\n- ✅ systemd 服务已激活\n\n### 手动健康检查\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\n健康响应包含：`{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n### 卸载\n\n**仅移除 MCP 模式：**\n\n1. 从 `openclaw.json` 的 `mcp.servers` 中删除 agentmemory 条目\n2. 执行 `openclaw gateway restart`\n\n**完全移除：**\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n### 故障排查\n\n**\"Connection refused on port 3111\"**\n服务器未启动，启动它：\n```bash\nsystemctl --user start agentmemory\n# 或手动：npx @agentmemory/agentmemory\n```\n\n**修改 openclaw.json 后提示 \"Config invalid\"**\n确保路径是 `mcp.servers`（不是 `mcpServers`）：\n```bash\nopenclaw status # 应显示 \"Config valid\"\n```\n\n**查看实时日志：**\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n**iii-engine 版本不匹配**\n如果 `api::graph-stats` 等 v0.11.6 函数未注册：\n```bash\n# 检查当前 iii-engine 版本\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# 确认 systemd service 中设置了 AGENTMEMORY_III_VERSION=latest\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n```\n\n**WebSocket 断连 (1006)**\n这通常是客户端事件（浏览器切页、网络抖动），非 Gateway 故障。检查：\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\n如果 Gateway 在断连后显示 `webchat connected`，说明服务正常。\n\n---\n\n### 实际带来的好处\n\n| 场景 | 没有 agentmemory | 有 agentmemory |\n|------|-----------------|---------------|\n| 会话丢失上下文 | 每次重新解释背景 | 自动从历史记忆捞取 |\n| 跨会话决策追溯 | 靠 MEMORY.md 手工记录 | `memory_recall` 语义搜索自动找 |\n| 重复踩同一个坑 | 不同 session 反复犯错 | 学到的教训自动积累+衰减 |\n| 新项目上手 | 要翻很久聊天记录 | 语义搜索项目背景即得 |\n| 记忆体检索 | 关键词匹配漏检率高 | BM25+Vector+Graph RRF 高召回 |\n| 记忆保存方式 | 全靠手工写 MEMORY.md | 手动调 `memory_save` 保存重要内容 |\n\n---\n\n*🦞 Skill by 龙虾 — agentmemory-mcp on ClawHub: https://clawhub.ai/lufei4/agentmemory-mcp*\n\nFile v0.9.12:_meta.json\n\n{\n \"ownerId\": \"kn73p7swcakp5x33a5x0sf7yes859vh8\",\n \"slug\": \"agentmemory-mcp\",\n \"version\": \"0.9.12\",\n \"publishedAt\": 1778654286890\n}\n\nFile v0.9.12:references/coordination.md\n\n# agentmemory + MEMORY.md Coordination Guide\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ OpenClaw Memory System │\n├─────────────────────────────────────────────────────────┤\n│ │\n│ ┌───────────────────────┐ ┌────────────────────────┐ │\n│ │ agentmemory (MCP) │ │ MEMORY.md / AGENTS │ │\n│ │ │ │ │ │\n│ │ • Auto-capture │ │ • Curated rules │ │\n│ │ • Semantic search │ │ • Preferences │ │\n│ │ • 95.2% R@5 │ │ • Manual updates │ │\n│ │ • Cross-agent │ │ • Human-readable │ │\n│ │ • Session sync │ │ • Survives compaction │ │\n│ └───────────────────────┘ └────────────────────────┘ │\n│ │ │ │\n│ └────────┬───────────────┘ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ OpenClaw Agent │ │\n│ └─────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Layer Responsibilities\n\n| Layer | Tool | What's stored | Management |\n|-------|------|--------------|------------|\n| **Experience** | agentmemory | Tasks, decisions, results, observations | Automatic |\n| **Knowledge** | MEMORY.md | Rules, preferences, long-term facts | Manual |\n| **Daily** | memory/YYYY-MM-DD.md | Session logs, events | Automatic |\n\n---\n\n## Agent Behavior Guidelines\n\n### Session Start\n\n1. **MEMORY.md + daily logs** → loaded automatically by OpenClaw\n2. **agentmemory** → agent can call `memory_recall` for additional context\n3. No conflict — both systems serve different purposes\n\n### During Work\n\n- **Task decision**: Call `memory_smart_search` to check if similar task was done\n- **Success**: Call `memory_save` with result, e.g.:\n ```\n memory_save(\"Deployed backend to Railway, took 8 minutes\", \n type=\"observation\", tags=[\"deployment\"])\n ```\n- **Failure**: Call `memory_save` noting what didn't work\n\n### Session End\n\n- OpenClaw auto-captures conversation via `plugins.slots.memory`\n- Critical learnings → also write to MEMORY.md (persists beyond compaction)\n\n---\n\n## Migration from Existing MEMORY.md\n\nIf MEMORY.md has valuable content, migrate selectively:\n\n```bash\n# Start server first\nnpx @agentmemory/agentmemory\n\n# In another terminal, import MEMORY.md\nnpx @agentmemory/agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md\n```\n\nOr use `memory_import` in batches:\n\n```javascript\n// Example: Migrate section by section\nmemory_import([\n { content: \"Backend deployed via Railway CLI\", type: \"observation\", tags: [\"deployment\"] },\n { content: \"User prefers brief responses\", type: \"preference\", tags: [\"communication\"] }\n], strategy: \"merge\")\n```\n\n---\n\n## Conflict Resolution\n\n**Q: What if agentmemory says something different from MEMORY.md?**\n\n| Scenario | Resolution |\n|----------|------------|\n| MEMORY.md has rule, agentmemory has conflicting experience | Trust MEMORY.md (curated), log conflict in agentmemory |\n| agentmemory has newer info | Update MEMORY.md if verified |\n| Uncertainty | Log to agentmemory, keep both until resolved |\n\n**Principle**: MEMORY.md is source of truth for rules; agentmemory is evidence of experience.\n\n---\n\n## Maintenance\n\n### Periodic (monthly)\n\n1. Read `memory_stats()` output\n2. Check for gaps with `memory_analyze(\"gaps\")`\n3. Review MEMORY.md for outdated entries\n\n### When Conflicting\n\n```bash\n# View memory for specific topic\nmemory_timeline(tag=\"deployment\", limit=10)\n\n# Check provenance\nmemory_trace(id=\"\")\n\n# Update or correct\nmemory_update(id=\"\", content=\"corrected information\")\n```\n\n---\n\n## Optimal Configuration\n\nFor maximum capability, run both systems:\n\n1. **agentmemory MCP** — handles automatic capture, semantic search, cross-agent sharing\n2. **MEMORY.md** — handles curated rules, preferences, compliance requirements\n\nThe agent uses whichever is appropriate for the situation — no forced preference.\n\nFile v0.9.12:references/mcp-tools.md\n\n# agentmemory MCP Tools Reference\n\nComplete list of 43 MCP tools available via `agentmemory` MCP server.\n\n## Core Memory Operations\n\n### memory_recall\nRetrieve semantically relevant memories.\n```\nmemory_recall(query: string, limit?: number, threshold?: number)\n```\n\n### memory_save\nStore new memories with optional metadata.\n```\nmemory_save(content: string, type?: \"observation\" | \"decision\" | \"fact\" | \"preference\", tags?: string[])\n```\n\n### memory_smart_search\nHybrid BM25 + vector search.\n```\nmemory_smart_search(query: string, limit?: number)\n```\n\n### memory_forget\nDelete memories by ID or pattern.\n```\nmemory_forget(pattern?: string, id?: string)\n```\n\n### memory_update\nUpdate existing memory content or metadata.\n```\nmemory_update(id: string, content?: string, tags?: string[])\n```\n\n---\n\n## Navigation & Exploration\n\n### memory_timeline\nView memories chronologically.\n```\nmemory_timeline(start?: date, end?: date, limit?: number)\n```\n\n### memory_tree\nHierarchical view of knowledge graph.\n```\nmemory_tree(root?: string, depth?: number)\n```\n\n### memory_trace\nView provenance/derivation chain of a memory.\n```\nmemory_trace(id: string)\n```\n\n### memory_stats\nMemory usage statistics.\n```\nmemory_stats()\n```\n\n---\n\n## Agent Integration\n\n### memory_profile\nDetailed agent memory profile.\n```\nmemory_profile(agent_id?: string)\n```\n\n### memory_snapshot\nExport all memories as JSON.\n```\nmemory_snapshot(format?: \"json\" | \"markdown\")\n```\n\n### memory_import\nBulk import memories.\n```\nmemory_import(memory: Memory[], strategy?: \"merge\" | \"replace\")\n```\n\n### memory_compact\nCompress and consolidate memories.\n```\nmemory_compact(threshold?: number)\n```\n\n---\n\n## Knowledge Graph\n\n### memory_relate\nCreate relationships between memories.\n```\nmemory_relate(from_id: string, to_id: string, relationship?: string)\n```\n\n### memory_graph_query\nQuery knowledge graph.\n```\nmemory_graph_query(query: string, depth?: number)\n```\n\n### memory_entities\nList all entities in knowledge graph.\n```\nmemory_entities(type?: string)\n```\n\n### memory_paths\nFind paths between two memories.\n```\nmemory_paths(from_id: string, to_id: string)\n```\n\n---\n\n## Context & Sessions\n\n### memory_context\nGet context for current session.\n```\nmemory_context(include_recent?: number)\n```\n\n### memory_inject\nInject memories into current context.\n```\nmemory_inject(limit?: number, match?: string)\n```\n\n### memory_session\nSession-specific memory operations.\n```\nmemory_session(op: \"save\" | \"load\" | \"clear\", data?: any)\n```\n\n---\n\n## Configuration\n\n### memory_config\nView/update agentmemory configuration.\n```\nmemory_config(op: \"get\" | \"set\", key?: string, value?: any)\n```\n\n### memory_channels\nList available memory channels.\n```\nmemory_channels()\n```\n\n---\n\n## Advanced\n\n### memory_analyze\nAnalyze memory patterns.\n```\nmemory_analyze(analysis_type?: \"coverage\" | \"gaps\" | \"redundancy\")\n```\n\n### memory_consolidate\nConsolidate fragmented memories.\n```\nmemory_consolidate(strategy?: \"simple\" | \"semantic\")\n```\n\n### memory_evict\nEvict low-value memories.\n```\nmemory_evict(threshold?: number, dry_run?: boolean)\n```\n\n---\n\n## Usage in OpenClaw\n\n### Before starting a task\n```\nAgent can call: memory_recall(\"project architecture decisions\")\n→ Returns relevant past decisions, avoiding re-explaining\n```\n\n### After completing a task\n```\nAgent can call: memory_save(\"Deployed backend to production via railway\", \n type=\"decision\", tags=[\"deployment\", \"backend\"])\n→ Stores experience for future reference\n```\n\n### Check task deduplication\n```\nAgent can call: memory_smart_search(\"deploy backend production\")\n→ If match found, agent can reuse previous workflow\n```\n\nFile v0.9.12:references/openclaw-plugin/openclaw.plugin.json\n\n{\n \"schema_version\": 1,\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"Persistent cross-session memory with semantic search\",\n \"slots\": [\"memory\"],\n \"config\": {\n \"base_url\": {\n \"type\": \"string\",\n \"default\": \"http://localhost:3111\",\n \"description\": \"agentmemory server URL\"\n },\n \"token_budget\": {\n \"type\": \"number\",\n \"default\": 2000,\n \"description\": \"Max tokens per recall injection\"\n },\n \"min_confidence\": {\n \"type\": \"number\",\n \"default\": 0.5,\n \"description\": \"Minimum confidence threshold for recall\"\n },\n \"fallback_on_error\": {\n \"type\": \"boolean\",\n \"default\": true,\n \"description\": \"Continue without memory if server unavailable\"\n },\n \"timeout_ms\": {\n \"type\": \"number\",\n \"default\": 5000,\n \"description\": \"Request timeout in milliseconds\"\n }\n },\n \"hooks\": {\n \"beforeAgent\": \"onBeforeAgent\",\n \"afterAgent\": \"onAfterAgent\"\n },\n \"requirements\": {\n \"server\": \"agentmemory\",\n \"min_openclaw_version\": \"1.0.0\"\n }\n}\n\nFile v0.9.12:references/openclaw-plugin/package.json\n\n{\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"agentmemory plugin for OpenClaw - persistent cross-session memory\",\n \"main\": \"plugin.mjs\",\n \"openclaw\": {\n \"slots\": [\"memory\"],\n \"version\": \">=1.0.0\"\n },\n \"dependencies\": {\n \"axios\": \"^1.6.0\"\n }\n}\n\nArchive v0.9.11: 8 files, 13391 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), SKILL.md (16495b), _meta.json (135b)\n\nFile v0.9.11:SKILL.md\n\n---\nname: agentmemory\ndescription: |\n Persistent cross-session memory for OpenClaw via agentmemory.\n \n Use when:\n - User asks to install/configure agentmemory for OpenClaw\n - Agent needs to remember project context, decisions, or workflows across sessions\n - Setting up long-term memory for OpenClaw (MCP mode)\n - Integrating agentmemory with existing MEMORY.md system\n - Troubleshooting agentmemory connection issues\n - Upgrading or removing agentmemory\n\n ───────────────────────────────\n \n 基于 agentmemory 的跨会话持久化记忆系统，适用于 OpenClaw。\n \n 适用场景：\n - 用户要求安装/配置 agentmemory\n - Agent 需要记住项目背景、决策或工作流程\n - 为 OpenClaw 设置长期记忆（MCP 模式）\n - 与现有 MEMORY.md 系统集成\n - 排查 agentmemory 连接问题\n - 升级或移除 agentmemory\n---\n\n# agentmemory Integration for OpenClaw\n\n> **Status**: ✅ Verified working with OpenClaw v2026.5.4\n> **Version**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP Tools**: 107 REST + 51 MCP tools available\n\nPersistent memory server giving OpenClaw agents cross-session semantic recall via BM25+Vector+Graph RRF hybrid search.\n\n## Architecture\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)\n ↓\n SQLite/KV Store\n ↓\n Viewer (localhost:3113)\n```\n\n## Quick Start (MCP Mode — 5 minutes)\n\n### Step 1: Install and start memory server\n\n```bash\n# Server runs on localhost:3111, viewer at localhost:3113\nnpx @agentmemory/agentmemory\n```\n\n### Step 2: Configure OpenClaw MCP\n\nAdd to `~/.openclaw/openclaw.json` under `mcp.servers`:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n### Step 3: Restart Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n### Step 4: Verify\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# View memory dashboard\nopen http://localhost:3113\n```\n\n---\n\n## MCP Tools (Key ones for OpenClaw)\n\n| Tool | Purpose |\n|------|---------|\n| `memory_recall` | Semantic search across all memories |\n| `memory_save` | Store new memories with type/tags |\n| `memory_smart_search` | Hybrid BM25+vector search |\n| `memory_timeline` | View memories chronologically |\n| `memory_profile` | Agent's memory usage stats |\n| `memory_snapshot` | Full memory export as JSON |\n| `memory_forget` | Delete specific memories |\n| `memory_context` | Get context for current session |\n| `memory_lesson_save` | Record lessons learned from errors |\n| `memory_reflect` | Cluster knowledge graph for insights |\n\nSee `references/mcp-tools.md` for full list of 51 tools.\n\n---\n\n## systemd Service (Production)\n\nFor auto-start and reliable background operation:\n\n### Install service\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# Enable linger (boot without login)\nloginctl enable-linger $(whoami)\n```\n\n### Service commands\n\n```bash\nsystemctl --user status agentmemory # Check status\njournalctl --user -u agentmemory -f # View logs\nsystemctl --user restart agentmemory # Restart\n```\n\n### Service environment variables\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `NODE_ENV` | `production` | Production mode |\n| `AGENTMEMORY_PORT` | `3111` | MCP API port |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | Dashboard port |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker image tag |\n\n> **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.\n\n### Docker socket\n\nThe 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.\n\n---\n\n## Search Mode: BM25-only\n\n> **Current status**: iii-engine v0.11.6 running in BM25-only mode (no embedding provider configured).\n\nThis is a known limitation, not a fault:\n\n- LiteLLM proxy at `127.0.0.1:4000` does not support `/embeddings` endpoint (`No connected db` error)\n- No local GPU available for Ollama embedding models (GTX 1060 6GB)\n- BM25 covers 90%+ of known-term searches (skill names, config keys, decision labels)\n- Semantic search (e.g. \"大模型\" matching \"LLM\") is not available without an external embedding provider\n\n**If semantic search is needed**, configure an OpenRouter-compatible embedding API:\n```bash\nexport OPENROUTER_API_KEY=\"sk-...\"\nexport EMBEDDING_PROVIDER=openrouter\n```\nVoyageAI and Cohere both offer free tiers with generous quotas.\n\n---\n\n## Integration with MEMORY.md\n\nagentmemory and MEMORY.md serve different purposes — they coexist:\n\n| Layer | System | Purpose | Management |\n|-------|--------|---------|------------|\n| **Experience** | agentmemory | Manual save, semantic recall, cross-agent | `memory_save` (manual) |\n| **Knowledge** | MEMORY.md | Curated decisions, preferences, rules | Manual |\n\n### Coordination rules\n\n- **Before major tasks**: Call `memory_recall` to retrieve relevant experiences\n- **After important decisions**: Call `memory_save` with result\n- **Curated knowledge**: Stays in MEMORY.md (survives compaction)\n- **Session start**: Both systems loaded; no conflicts\n\n### After installation: migrate MEMORY.md (important!)\n\nAfter completing installation, migrate MEMORY.md content into agentmemory:\n\n1. **Open the dashboard to view current state**\n ```bash\n open http://localhost:3113\n ```\n Initially empty — migration populates it with searchable data.\n\n2. **Migrate MEMORY.md content**\n Use the CLI migrate command:\n ```bash\n agentmemory migrate --from-file /home/lufei/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **Verify migration results**\n After migration, reopen http://localhost:3113 to confirm data is stored.\n\n> Note: MEMORY.md stays intact — both systems coexist. agentmemory handles semantic search; MEMORY.md holds curated knowledge.\n\n---\n\n## Verification\n\nRun the verification script:\n```bash\nbash /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/verify.sh\n```\n\nExpected output:\n- ✅ Memory server on port 3111\n- ✅ Health endpoint responding\n- ✅ Viewer available on port 3113\n- ✅ OpenClaw MCP configured\n- ✅ systemd service active\n\n### Manual health check\n\n```bash\ncurl http://127.0.0.1:3111/agentmemory/health | python3 -m json.tool\n```\n\nHealthy response shows: `{\"status\":\"healthy\",\"uptimeSeconds\":...,\"workers\":[...]}`\n\n---\n\n## Uninstall\n\n### MCP mode removal\n\n1. Remove from `openclaw.json` mcp.servers section\n2. `openclaw gateway restart`\n\n### Full removal\n\n```bash\nsystemctl --user stop agentmemory\nsystemctl --user disable agentmemory\nrm ~/.config/systemd/user/agentmemory.service\npkill -f \"agentmemory\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Connection refused on port 3111\"\nMemory server not running. Start it:\n```bash\nsystemctl --user start agentmemory\n# Or manually: npx @agentmemory/agentmemory\n```\n\n### \"Config invalid\" after editing openclaw.json\nEnsure `mcp.servers` path (not `mcpServers`). Run:\n```bash\nopenclaw status # Should show \"Config valid\"\n```\n\n### View real-time logs\n```bash\njournalctl --user -u agentmemory -f --since \"1 hour ago\"\n```\n\n### iii-engine version mismatch\nIf `api::graph-stats` and other v0.11.6 functions are not registered:\n```bash\n# Check current iii-engine version\ncurl -s http://127.0.0.1:3111/agentmemory/health | python3 -c \"\nimport json,sys; d=json.load(sys.stdin)\nfor w in d['health']['workers']:\n print(w['name'], '→', w['version'])\n\"\n\n# Ensure AGENTMEMORY_III_VERSION=latest is set in systemd service\nsystemctl --user status agentmemory\ngrep AGENTMEMORY_III_VERSION ~/.config/systemd/user/agentmemory.service\n```\n\n### WebSocket disconnected (1006)\nThis is typically a client-side event (browser tab switch, network glitch), not a Gateway failure. Check:\n```bash\njournalctl --user -u openclaw-gateway --since \"5 minutes ago\" | grep -E \"connected|disconnected\"\n```\nIf Gateway shows `webchat connected` after the disconnect, the service is fine.\n\n---\n\n---\n\n## 中文版 Chinese Version\n\n### agentmemory × OpenClaw 集成\n\n> **状态**: ✅ 已验证兼容 OpenClaw v2026.5.4\n> **版本**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP 工具**: 107 个 REST + 51 个 MCP 工具\n\n持久化记忆服务，为 OpenClaw Agent 提供跨会话语义召回能力，基于 BM25+向量+图谱混合搜索。\n\n### 系统架构\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP 服务器 (localhost:3111)\n ↓\n SQLite/KV 存储\n ↓\n 浏览器仪表板 (localhost:3113)\n```\n\n### 快速开始（MCP 模式 — 5 分钟）\n\n**第一步：启动记忆服务器**\n\n```bash\nnpx @agentmemory/agentmemory\n# 服务器端口：3111（API）、3113（浏览器仪表板）\n```\n\n**第二步：配置 OpenClaw MCP**\n\n在 `~/.openclaw/openclaw.json` 中加入：\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n**第三步：重启 Gateway**\n\n```bash\nopenclaw gateway restart\n```\n\n**第四步：验证**\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# 打开记忆仪表板\nopen http://localhost:3113\n```\n\n---\n\n### 核心 MCP 工具\n\n| 工具 | 用途 |\n|------|------|\n| `memory_recall` | 跨所有记忆的语义搜索 |\n| `memory_save` | 以类型/标签存储新记忆 |\n| `memory_smart_search` | BM25+向量混合搜索 |\n| `memory_timeline` | 按时间线查看记忆 |\n| `memory_profile` | Agent 记忆使用统计 |\n| `memory_snapshot` | 完整记忆导出 JSON |\n| `memory_forget` | 删除指定记忆 |\n| `memory_context` | 获取当前会话上下文 |\n| `memory_lesson_save` | 记录从错误中学到的教训 |\n| `memory_reflect` | 聚类知识图谱提炼洞察 |\n\n完整 51 个工具列表见 `references/mcp-tools.md`。\n\n---\n\n### systemd 服务（生产环境推荐）\n\n**安装服务：**\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp /home/lufei/.openclaw/workspace/skills/agentmemory/scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# 启用 linger（开机免登录自动启动）\nloginctl enable-linger $(whoami)\n```\n\n**服务环境变量：**\n\n| 变量 | 值 | 说明 |\n|------|-----|------|\n| `NODE_ENV` | `production` | 生产模式 |\n| `AGENTMEMORY_PORT` | `3111` | MCP API 端口 |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | 仪表板端口 |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker 镜像标签 |\n\n> **重要**：`AGENTMEMORY_III_VERSION=latest` 用于绕过 npm CLI 硬编码的 `IIPINNED_VERSION=0.11.2`，确保使用最新的稳定版 iii-engine（v0.11.6）。\n\n**Docker socket**：服务使用系统 Docker socket `/var/run/docker.sock`（属于 `root:docker` 组）。不要设置 `DOCKER_HOST` 环境变量，默认 socket 路径已正确。\n\n---\n\n### 搜索模式：BM25-only\n\n> **当前状态**：iii-engine v0.11.6 运行在 BM25-only 模式（未配置 embedding provider）。\n\n这是已知限制，不是故障：\n\n- LiteLLM proxy (`127.0.0.1:4000`) 不支持 `/embeddings` 端点（返回 `No connected db`）\n- 无本地 GPU 可运行 Ollama embedding 模型（GTX 1060 6GB）\n- BM25 对已知术语搜索（技能名、配置键、决策标签）已覆盖 90%+ 需求\n- 语义搜索（如\"大模型\"匹配\"LLM\"）需外部 embedding provider\n\n**如需语义搜索**，可配置 OpenRouter 兼容的 embedding API：\n```bash\nexport OPENROUTER_API_KEY=\"sk-...\"\nexport EMBEDDING_PROVIDER=openrouter\n```\nVoyageAI 和 Cohere 均有免费额度。\n\n---\n\n### 与 MEMORY.md 的协同\n\n两个系统分工不同，共存互补：\n\n| 层级 | 系统 | 用途 | 管理方式 |\n|------|------|------|----------|\n| **经验层** | agentmemory | 手动保存重要内容、语义召回、跨 Agent 共享 | `memory_save`（手动调用） |\n| **知识层** | MEMORY.md | 精心整理的决策、偏好、规则 | 手工维护 |\n\n**协调规则：**\n\n- **任务开始前** → 调用 `memory_recall` 检索相关经验\n- **重要决策后** → 调用 `memory_save` 保存结果\n- **精选知识** → 留在 MEMORY.md（不受会话压缩影响）\n- **会话启动时** → 两个系统同时加载，无冲突\n\n### 首次安装后：迁移 MEMORY.md（重要！）\n\n安装完成后，将 MEMORY.md 的核心内容迁移到 agentmemory：\n\n1. **打开仪表板查看当前状态**\n ```bash\n open http://localhost:3113\n ```\n 初始是空的，迁移后才有数据可搜。\n\n2. **迁移 MEMORY.md 内容**\n 使用 CLI migrate 命令：\n ```bash\n agentmemory migrate --from-file /home/lufei/.openclaw/workspace/MEMORY.md --verbose\n ```\n\n3. **验证迁移结果**\n 迁移完成后，再次打开 http://localhost:3113 查看记忆仪表板，确认数据已入库。\n\n> 注意：MEMORY.md 本身保留不动，两套系统共存 — agentmemory 负责语义搜索，MEMORY.md 负责手工精修知识。\n\n---\n\n### 验证\n\n```ba\n\nArchive v1.2.0: 8 files, 11647 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), SKILL.md (11665b), _meta.json (134b)\n\nArchive v1.1.0: 8 files, 10904 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), SKILL.md (9927b), _meta.json (134b)\n\nArchive v1.0.0: 8 files, 9037 bytes\n\nFiles: references/coordination.md (5052b), references/mcp-tools.md (3611b), references/openclaw-plugin/openclaw.plugin.json (1051b), references/openclaw-plugin/package.json (277b), references/openclaw-plugin/plugin.mjs (3167b), scripts/verify.sh (2201b), SKILL.md (4846b), _meta.json (134b)","readmeExcerpt":"Skill: agentmemory-mcp Owner: lufei4 Summary: Persistent cross-session memory for OpenClaw via agentmemory. Use when: - User asks to install/configure agentmemory for OpenClaw - Agent needs to remember p... Tags: agentmemory:1.1.0, latest:1.3.0, mcp:1.1.0, memory:1.1.0, openclauw:1.1.0, persistent:1.1.0 Version history: v1.3.0 | 2026-05-13T07:47:38.658Z | user Major: Full Search Mode guide (BM25 vs Vector embedding p","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"OpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)\n ↓\n SQLite/KV Store\n ↓\n Viewer (localhost:3113)"},{"language":"bash","snippet":"# Server runs on localhost:3111, viewer at localhost:3113\nnpx @agentmemory/agentmemory"},{"language":"json","snippet":"{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}"},{"language":"bash","snippet":"openclaw gateway restart"},{"language":"bash","snippet":"curl http://localhost:3111/agentmemory/health"},{"language":"bash","snippet":"curl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# View memory dashboard\nopen http://localhost:3113"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: agentmemory\ndescription: |\n Persistent cross-session memory for OpenClaw via agentmemory.\n \n Use when:\n - User asks to install/configure agentmemory for OpenClaw\n - Agent needs to remember project context, decisions, or workflows across sessions\n - Setting up long-term memory for OpenClaw (MCP mode)\n - Integrating agentmemory with existing MEMORY.md system\n - Troubleshooting agentmemory connection issues\n - Upgrading or removing agentmemory\n\n ───────────────────────────────\n \n 基于 agentmemory 的跨会话持久化记忆系统，适用于 OpenClaw。\n \n 适用场景：\n - 用户要求安装/配置 agentmemory\n - Agent 需要记住项目背景、决策或工作流程\n - 为 OpenClaw 设置长期记忆（MCP 模式）\n - 与现有 MEMORY.md 系统集成\n - 排查 agentmemory 连接问题\n - 升级或移除 agentmemory\n---\n\n# agentmemory Integration for OpenClaw\n\n> **Status**: ✅ Verified working with OpenClaw v2026.5.4\n> **Version**: agentmemory npm v0.9.11 · iii-engine Docker v0.11.6\n> **MCP Tools**: 107 REST + 51 MCP tools available\n\nPersistent memory server giving OpenClaw agents cross-session semantic recall via BM25+Vector+Graph RRF hybrid search.\n\n## Architecture\n\n```\nOpenClaw Agent ←→ Gateway (MCP) ←→ agentmemory MCP Server (localhost:3111)\n ↓\n SQLite/KV Store\n ↓\n Viewer (localhost:3113)\n```\n\n## Quick Start (MCP Mode — 5 minutes)\n\n### Step 1: Install and start memory server\n\n```bash\n# Server runs on localhost:3111, viewer at localhost:3113\nnpx @agentmemory/agentmemory\n```\n\n### Step 2: Configure OpenClaw MCP\n\nAdd to `~/.openclaw/openclaw.json` under `mcp.servers`:\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"agentmemory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@agentmemory/mcp\"]\n }\n }\n }\n}\n```\n\n### Step 3: Restart Gateway\n\n```bash\nopenclaw gateway restart\n```\n\n### Step 4: Verify\n\n```bash\ncurl http://localhost:3111/agentmemory/health\n# → {\"status\":\"healthy\",\"version\":\"0.9.11\"}\n\n# View memory dashboard\nopen http://localhost:3113\n```\n\n---\n\n## systemd Service (Production)\n\nFor auto-start and reliable background operation:\n\n### Install service\n\n```bash\nmkdir -p ~/.config/systemd/user\ncp ./scripts/agentmemory.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable agentmemory\nsystemctl --user start agentmemory\n\n# Enable linger (boot without login)\nloginctl enable-linger $(whoami)\n```\n\n### Service commands\n\n```bash\nsystemctl --user status agentmemory # Check status\njournalctl --user -u agentmemory -f # View logs\nsystemctl --user restart agentmemory # Restart\n```\n\n### Service environment variables\n\n| Variable | Value | Purpose |\n|----------|-------|---------|\n| `NODE_ENV` | `production` | Production mode |\n| `AGENTMEMORY_PORT` | `3111` | MCP API port |\n| `AGENTMEMORY_VIEWER_PORT` | `3113` | Dashboard port |\n| `AGENTMEMORY_III_VERSION` | `latest` | iii-engine Docker image tag |\n\n> **Important**: `AGENTMEMORY_III_VERSION=latest` overrides the npm CL"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn73p7swcakp5x33a5x0sf7yes859vh8\",\n \"slug\": \"agentmemory-mcp\",\n \"version\": \"1.3.0\",\n \"publishedAt\": 1778658458658\n}"},{"path":"references/coordination.md","content":"# agentmemory + MEMORY.md Coordination Guide\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ OpenClaw Memory System │\n├─────────────────────────────────────────────────────────┤\n│ │\n│ ┌───────────────────────┐ ┌────────────────────────┐ │\n│ │ agentmemory (MCP) │ │ MEMORY.md / AGENTS │ │\n│ │ │ │ │ │\n│ │ • Auto-capture │ │ • Curated rules │ │\n│ │ • Semantic search │ │ • Preferences │ │\n│ │ • 95.2% R@5 │ │ • Manual updates │ │\n│ │ • Cross-agent │ │ • Human-readable │ │\n│ │ • Session sync │ │ • Survives compaction │ │\n│ └───────────────────────┘ └────────────────────────┘ │\n│ │ │ │\n│ └────────┬───────────────┘ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ OpenClaw Agent │ │\n│ └─────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Layer Responsibilities\n\n| Layer | Tool | What's stored | Management |\n|-------|------|--------------|------------|\n| **Experience** | agentmemory | Tasks, decisions, results, observations | Automatic |\n| **Knowledge** | MEMORY.md | Rules, preferences, long-term facts | Manual |\n| **Daily** | memory/YYYY-MM-DD.md | Session logs, events | Automatic |\n\n---\n\n## Agent Behavior Guidelines\n\n### Session Start\n\n1. **MEMORY.md + daily logs** → loaded automatically by OpenClaw\n2. **agentmemory** → agent can call `memory_recall` for additional context\n3. No conflict — both systems serve different purposes\n\n### During Work\n\n- **Task decision**: Call `memory_smart_search` to check if similar task was done\n- **Success**: Call `memory_save` with result, e.g.:\n ```\n memory_save(\"Deployed backend to Railway, took 8 minutes\", \n type=\"observation\", tags=[\"deployment\"])\n ```\n- **Failure**: Call `memory_save` noting what didn't work\n\n### Session End\n\n- OpenClaw auto-captures conversation via `plugins.slots.memory`\n- Critical learnings → also write to MEMORY.md (persists beyond compaction)\n\n---\n\n## Migration from Existing MEMORY.md\n\nIf MEMORY.md has valuable content, migrate selectively:\n\n```bash\n# Start server first\nnpx @agentmemory/agentmemory\n\n# In another terminal, import MEMORY.md\nnpx @agentmemory/agentmemory migrate --from-file ~/.openclaw/workspace/MEMORY.md\n```\n\nOr use `memory_import` in batches:\n\n```javascript\n// Example: Migrate section by section\nmemory_import([\n { content: \"Backend deployed via Railway CLI\", type: \"observation\", tags: [\"deployment\"] },\n { content: \"User prefers brief responses\", type: \"preference\", tags: [\"communication\"] }\n], strategy: \"merge\")\n```\n\n---\n\n## Conflict Resolution\n\n**Q:"},{"path":"references/mcp-tools.md","content":"# agentmemory MCP Tools Reference\n\nComplete list of 43 MCP tools available via `agentmemory` MCP server.\n\n## Core Memory Operations\n\n### memory_recall\nRetrieve semantically relevant memories.\n```\nmemory_recall(query: string, limit?: number, threshold?: number)\n```\n\n### memory_save\nStore new memories with optional metadata.\n```\nmemory_save(content: string, type?: \"observation\" | \"decision\" | \"fact\" | \"preference\", tags?: string[])\n```\n\n### memory_smart_search\nHybrid BM25 + vector search.\n```\nmemory_smart_search(query: string, limit?: number)\n```\n\n### memory_forget\nDelete memories by ID or pattern.\n```\nmemory_forget(pattern?: string, id?: string)\n```\n\n### memory_update\nUpdate existing memory content or metadata.\n```\nmemory_update(id: string, content?: string, tags?: string[])\n```\n\n---\n\n## Navigation & Exploration\n\n### memory_timeline\nView memories chronologically.\n```\nmemory_timeline(start?: date, end?: date, limit?: number)\n```\n\n### memory_tree\nHierarchical view of knowledge graph.\n```\nmemory_tree(root?: string, depth?: number)\n```\n\n### memory_trace\nView provenance/derivation chain of a memory.\n```\nmemory_trace(id: string)\n```\n\n### memory_stats\nMemory usage statistics.\n```\nmemory_stats()\n```\n\n---\n\n## Agent Integration\n\n### memory_profile\nDetailed agent memory profile.\n```\nmemory_profile(agent_id?: string)\n```\n\n### memory_snapshot\nExport all memories as JSON.\n```\nmemory_snapshot(format?: \"json\" | \"markdown\")\n```\n\n### memory_import\nBulk import memories.\n```\nmemory_import(memory: Memory[], strategy?: \"merge\" | \"replace\")\n```\n\n### memory_compact\nCompress and consolidate memories.\n```\nmemory_compact(threshold?: number)\n```\n\n---\n\n## Knowledge Graph\n\n### memory_relate\nCreate relationships between memories.\n```\nmemory_relate(from_id: string, to_id: string, relationship?: string)\n```\n\n### memory_graph_query\nQuery knowledge graph.\n```\nmemory_graph_query(query: string, depth?: number)\n```\n\n### memory_entities\nList all entities in knowledge graph.\n```\nmemory_entities(type?: string)\n```\n\n### memory_paths\nFind paths between two memories.\n```\nmemory_paths(from_id: string, to_id: string)\n```\n\n---\n\n## Context & Sessions\n\n### memory_context\nGet context for current session.\n```\nmemory_context(include_recent?: number)\n```\n\n### memory_inject\nInject memories into current context.\n```\nmemory_inject(limit?: number, match?: string)\n```\n\n### memory_session\nSession-specific memory operations.\n```\nmemory_session(op: \"save\" | \"load\" | \"clear\", data?: any)\n```\n\n---\n\n## Configuration\n\n### memory_config\nView/update agentmemory configuration.\n```\nmemory_config(op: \"get\" | \"set\", key?: string, value?: any)\n```\n\n### memory_channels\nList available memory channels.\n```\nmemory_channels()\n```\n\n---\n\n## Advanced\n\n### memory_analyze\nAnalyze memory patterns.\n```\nmemory_analyze(analysis_type?: \"coverage\" | \"gaps\" | \"redundancy\")\n```\n\n### memory_consolidate\nConsolidate fragmented memories.\n```\nmemory_consolidate(strategy?: \"simple\" | \"semantic\")\n```\n\n### memory_evict\nEvict low-value memories"},{"path":"references/openclaw-plugin/openclaw.plugin.json","content":"{\n \"schema_version\": 1,\n \"name\": \"agentmemory\",\n \"version\": \"1.0.0\",\n \"description\": \"Persistent cross-session memory with semantic search\",\n \"slots\": [\"memory\"],\n \"config\": {\n \"base_url\": {\n \"type\": \"string\",\n \"default\": \"http://localhost:3111\",\n \"description\": \"agentmemory server URL\"\n },\n \"token_budget\": {\n \"type\": \"number\",\n \"default\": 2000,\n \"description\": \"Max tokens per recall injection\"\n },\n \"min_confidence\": {\n \"type\": \"number\",\n \"default\": 0.5,\n \"description\": \"Minimum confidence threshold for recall\"\n },\n \"fallback_on_error\": {\n \"type\": \"boolean\",\n \"default\": true,\n \"description\": \"Continue without memory if server unavailable\"\n },\n \"timeout_ms\": {\n \"type\": \"number\",\n \"default\": 5000,\n \"description\": \"Request timeout in milliseconds\"\n }\n },\n \"hooks\": {\n \"beforeAgent\": \"onBeforeAgent\",\n \"afterAgent\": \"onAfterAgent\"\n },\n \"requirements\": {\n \"server\": \"agentmemory\",\n \"min_openclaw_version\": \"1.0.0\"\n }\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Persistent cross-session memory for OpenClaw via agentmemory. Use when: - User asks to install/configure agentmemory for OpenClaw - Agent needs to remember p... Skill: agentmemory-mcp Owner: lufei4 Summary: Persistent cross-session memory for OpenClaw via agentmemory. Use when: - User asks to install/configure agentmemory for OpenClaw - Agent needs to remember p... Tags: agentmemory:1.1.0, latest:1.3.0, mcp:1.1.0, memory:1.1.0, openclauw:1.1.0, persistent:1.1.0 Version history: v1.3.0 | 2026-05-13T07:47:38.658Z | user Major: Full Search Mode guide (BM25 vs Vector embedding p","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1178,"uniquenessScore":51,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:35:20.775Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:35:20.775Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T15:57:03.534Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}