agentmemory 详细部署与配置教程

agentmemory 是一个为 AI 编程代理提供持久化记忆的开源工具，能让 Claude Code、Cursor、Gemini CLI 等 Agent 跨会话记住之前的上下文、决策和代码模式。本教程将带你完成从安装到完整配置的全过程。

一、准备工作

1.1 系统要求

  • Node.js：版本 20 或更高（使用 node -v 检查）
  • npm 和 npx：确保可用（npm -v、npx -v）
  • 操作系统：macOS、Linux 或 Windows 10/11

1.2 额外依赖（macOS/Linux）

agentmemory 自动安装 iii-engine 时需要 curl、POSIX sh 和 tar。精简版镜像（如 node:20-slim）可能缺少这些，需手动安装。

二、安装 agentmemory

2.1 快速安装（推荐）

打开终端，执行以下命令启动首次运行：

1
npx -y @agentmemory/agentmemory@latest

首次运行会启动交互式设置：

  1. 选择要接入的 AI 代理（Claude Code、Cursor、Codex、Gemini CLI 等）
  2. 选择 LLM 提供者（或保持无密钥模式）
  3. 自动生成配置、在 3111 端口启动记忆服务器

验证安装成功：

1
2
curl -s http://localhost:3111/agentmemory/health
# 返回 {"status":"healthy"} 即表示正常

打开浏览器访问 http://localhost:3113，可以看到实时记忆捕获面板。

2.2 全局安装（可选）

为了避免每次使用 npx，可以全局安装：

1
npm install -g @agentmemory/agentmemory@latest

之后直接用 agentmemory 命令即可启动。

提示：从 v0.9.16 版本开始，首次 npx 运行会提示是否全局安装，回答 Y 即可一键完成。

2.3 解决 npx 缓存问题

如果 npx 提供了旧版本，使用以下方式强制拉取最新版：

1
2
3
4
5
6
# 方式一：强制指定 latest
npx -y @agentmemory/agentmemory@latest

# 方式二：清除 npx 缓存后重试
rm -rf ~/.npm/_npx   # macOS/Linux
# Windows: Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

三、Windows 系统特殊配置

agentmemory 可在 Windows 10/11 运行，但需要额外安装 iii-engine 运行时。有三种方式可选：

3.1 方式一：手动安装 iii.exe（推荐）

  1. 浏览器打开 iii v0.11.2 发布页
  2. 下载 iii-x86_64-pc-windows-msvc.zip
  3. 解压 iii.exe 到 %USERPROFILE%\.agentmemory\bin\iii.exe
  4. 验证：
1
2
& "$HOME\.agentmemory\bin\iii.exe" --version
# 应输出 0.11.2
  1. 然后正常运行 agentmemory：
1
npx -y @agentmemory/agentmemory@latest

3.2 方式二：Docker Desktop

1
2
3
# 启动 Docker Desktop，然后运行：
$env:AGENTMEMORY_USE_DOCKER = "1"
npx -y @agentmemory/agentmemory@latest

3.3 方式三：仅 MCP 模式（无引擎）

如果只需要 MCP 工具供代理使用，不需要 REST API、查看器或定时任务，可跳过引擎：

1
2
3
npx -y @agentmemory/agentmemory@latest mcp
# 或直接使用 shim 包
npx -y @agentmemory/mcp

四、配置 LLM 和 Embedding（可选）

agentmemory 即使不配置任何 API Key 也能跑——纯靠 BM25 关键词匹配做检索。但若需要 LLM 压缩总结、智能反思、向量语义搜索等高级能力，则需配置 LLM 和 Embedding。

配置文件位于 ~/.agentmemory/.env。

4.1 配置 LLM

agentmemory 使用 LLM 来压缩观察记录、生成摘要、提取概念。

以阿里云 DashScope 为例：

1
2
3
4
# ===== LLM 配置 =====
OPENAI_API_KEY=sk-你的DashScope_API_Key
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_MODEL=qwen3.5-flash

同样的逻辑适用于 OpenAI、DeepSeek、硅基流动等兼容 OpenAI 协议的服务。

使用 Anthropic Claude：

1
ANTHROPIC_API_KEY=sk-ant-xxx

使用本地 Ollama：

1
2
3
OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b

注意：配置 LLM 提供者后，还需设置 AGENTMEMORY_AUTO_COMPRESS=true 才会启用自动压缩。

4.2 配置 Embedding（向量检索）

Embedding 用于实现语义搜索。推荐免费方案：

1
EMBEDDING_PROVIDER=local

首次使用会下载 Xenova/all-MiniLM-L6-v2 模型（需网络），之后完全本地运行，零成本。

使用远程 Embedding 服务：

1
2
3
EMBEDDING_PROVIDER=openai
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMENSIONS=1536

配置完成后重启：

1
2
agentmemory stop
agentmemory

使用 agentmemory status 可查看当前 Provider 和 Embedding 状态。

五、接入 AI 代理

5.1 接入 Claude Code

1
2
3
4
5
6
# 终端 1：启动记忆服务器
npx -y @agentmemory/agentmemory@latest

# 终端 2：安装 Claude Code 插件
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory

插件会自动注册 12 个钩子、17 个技能，并自动配置 MCP 服务器（54 个工具）。

验证：

1
curl http://localhost:3111/agentmemory/health

5.2 接入 Codex CLI

1
2
3
4
5
6
# 1. 启动记忆服务器（另一终端）
npx -y @agentmemory/agentmemory@latest

# 2. 注册 marketplace 并安装插件
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

5.3 通用 MCP 接入（Cursor、Cline、Claude Desktop 等）

在对应配置文件的 mcpServers 中添加以下条目：

1
2
3
4
5
6
7
8
9
10
11
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

各代理配置文件路径：

  • Cursor：~/.cursor/mcp.json
  • Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
  • Cline：设置界面 → MCP Servers → 编辑 JSON

重要：@agentmemory/mcp 是轻量 shim 包。只有连接到运行中的 agentmemory 服务器时才暴露 54 个完整工具；无服务器时仅提供 7 个本地工具。

5.4 接入 OpenCode

1
2
3
4
5
6
7
8
9
{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  }
}

5.5 接入更多代理

使用 connect 命令可一键接入支持的代理：

1
2
3
4
5
agentmemory connect claude-code   # Claude Code
agentmemory connect cursor         # Cursor
agentmemory connect gemini         # Gemini CLI
agentmemory connect codex          # Codex CLI
# 更多代理见官方文档

六、安装 Skills（技能包）

agentmemory 提供了 17 个技能（9 个可调用技能 + 8 个参考技能），让代理知道何时调用记忆功能：

1
npx skills add rohitg00/agentmemory -y

支持 50+ 种代理自动识别。也可以指定安装到特定代理：

1
2
npx skills add rohitg00/agentmemory -y -a warp   # 指定安装到 Warp
npx skills add rohitg00/agentmemory -y -a '*'    # 安装到所有已安装的代理

核心技能包括：/recall（搜索记忆）、/remember（保存记忆）、/session-history（查看会话历史）、/forget（删除记录）等。

七、验证部署

7.1 运行 Demo 测试

1
2
3
4
5
# 注入示例会话数据
npx -y @agentmemory/agentmemory@latest demo

# 无 Embedding 时，关键词搜索可命中
# 有 Embedding 时，语义搜索也能命中

7.2 验证重启持久化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 保存一条测试数据
curl -X POST http://localhost:3111/agentmemory/remember \
  -H 'Content-Type: application/json' \
  -d '{"content":"agentmemory 部署测试数据"}'

# 搜索验证
curl -X POST http://localhost:3111/agentmemory/smart-search \
  -H 'Content-Type: application/json' \
  -d '{"query":"部署测试"}'

# 停止服务
agentmemory stop

# 重启
agentmemory

# 再次搜索，数据应仍存在

7.3 访问实时查看器

打开浏览器访问 http://localhost:3113：

  • 实时观察记忆写入流
  • 会话资源管理器
  • 知识图谱可视化
  • 会话回放功能（支持 0.5x~4x 速度控制）

八、常用命令与维护

1
2
3
4
5
6
7
agentmemory              # 启动服务器
agentmemory stop         # 停止服务器
agentmemory status       # 查看状态
agentmemory doctor       # 交互式诊断 + 修复
agentmemory connect <agent>  # 接入新代理
agentmemory upgrade      # 升级到最新版本（会更新 JS 依赖和 Docker 镜像）
agentmemory remove       # 卸载所有 agentmemory 创建的内容

导入历史会话（Claude Code）

1
2
3
4
5
# 导入默认目录下所有 JSONL 记录
npx -y @agentmemory/agentmemory@latest import-jsonl

# 导入单文件
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

注意：Claude Code 默认 30 天后清理 ~/.claude/projects/ 下的 JSONL 文件。建议及时导入或调高 cleanupPeriodDays 设置。

九、部署到生产环境

项目提供了多种一键部署模板：

  • Fly.io：deploy/fly/，单机配置 auto_stop_machines = "stop" 节省成本
  • Railway：deploy/railway/，Hobby 计划固定费用
  • Render：deploy/render/，使用 Blueprint 流程，付费计划支持自动磁盘快照
  • Coolify：deploy/coolify/，自托管 VPS

所有模板使用自包含 Dockerfile，持久存储挂载在 /data，首次启动自动生成 HMAC secret 并降权运行。

十、常见问题排查

问题 解决方案
端口冲突 使用 --port <N> 指定不同端口，或 `netstat -ano
npx 提供旧版本 使用 npx -y @agentmemory/agentmemory@latest 或清除 ~/.npm/_npx
Windows 引擎启动失败 使用 --verbose 查看具体错误，确认 iii.exe 已正确安装
MCP 只显示 7 个工具 确认 agentmemory 服务器已启动，且 MCP 配置中 AGENTMEMORY_URL=http://localhost:3111 正确设置
语义搜索无结果 确认已配置 Embedding（EMBEDDING_PROVIDER=local 或远程服务），首次下载模型需要网络

部署完成后，你的 AI 编程代理将拥有跨会话的持久记忆，无需重复解释项目架构和上下文。