agentmemory

环境要求

• Node.js 20 或更高版本，并自带 npm 和 npx（可用 node -v、npm -v、npx -v 自检）
• macOS/Linux 自动安装 iii-engine 还需要 curl、POSIX sh 和 tar（node:20-slim 等精简镜像可能缺少）
• 原生 Windows 需手动安装固定版本的 iii-engine v0.22.1 的 iii.exe，建议改用 WSL2 或 Docker Desktop
• 首次运行会联网下载 npm 包与固定版本 iii-engine（v0.22.1）

安装与启动步骤

1. 1检查运行环境

   确认 Node 版本不低于 20，且 npm、npx 可用。任一命令报错就先装好 Node.js 再继续。

   node -v
   npm -v
   npx -v

   复制

2. 2一键安装并启动

   这是官方推荐的全新安装命令，-y 接受 npx 的包提示，@latest 避免用到旧缓存版本。首次运行是交互式设置。

   npx -y @agentmemory/agentmemory@latest

   复制

3. 3完成交互式配置

   按提示选择要接入的智能体（Claude Code、Cursor、Codex、Gemini CLI、OpenCode 等），再选 LLM 提供方或保持 keyless，程序会写入配置并启动记忆服务及其固定版 iii 引擎。

4. 4验证记忆召回

   运行 demo 会灌入示例会话并演练召回。默认 keyless 模式下关键词检索走 BM25，应能命中。

   npx -y @agentmemory/agentmemory@latest demo

   复制

5. 5给智能体装技能

   安装 17 个原生技能，让智能体知道何时该调用记忆能力。

   npx skills add rohitg00/agentmemory -y

   复制

6. 6接入更多智能体

   之后随时可以用 connect 子命令把其它智能体接到同一个记忆服务器上，共 20 个适配器；把 cursor 换成你要接入的智能体名即可。

   agentmemory connect cursor

   复制

7. 7可选：全局安装

   想让裸命令 agentmemory 随处可用可全局安装；npx 方式仍是官方推荐的全新安装路径，能避开全局前缀权限问题（EACCES）。

   npm install -g @agentmemory/agentmemory@latest

   复制

8. 8可选：本地语义检索

   在 ~/.agentmemory/.env 中设置 EMBEDDING_PROVIDER=local 并重启，可获得免费端侧语义召回；首次请求会下载 Xenova/all-MiniLM-L6-v2 模型。

关键配置

如何确认成功

本地服务会在 3111（REST/MCP HTTP）和 3113（viewer）等端口监听；再跑一次 demo，关键词检索能命中的话说明记忆写入与召回已正常。

常见问题

注意事项

• 数据默认存放位置：macOS 为 ~/Library/Application Support/agentmemory，Linux 为 $XDG_DATA_HOME/agentmemory 或 ~/.local/share/agentmemory，Windows 为 %APPDATA%gentme
• 用 --data-dir 或 AGENTMEMORY_DATA_DIR 覆盖数据目录后，每次重启都要传同一个值，否则会读到不同的记忆库。
• 若已存在 ./data/state_store.db 或 ./data/iii-config.yaml，会优先于平台默认目录（仅实例 0），显式参数或环境变量仍然优先。
• 本地运行占用四个端口：3111 REST/MCP HTTP、3112 iii streams、3113 viewer、49134 iii worker WebSocket。