rohitg00/agentmemory · 上手攻略

  • 仓库：rohitg00/agentmemory
  • 链接：https://github.com/rohitg00/agentmemory
  • 分类：ai · agent
  • 作者：Tom
  • 更新：2026-07-07

它是什么

agentmemory 是给 AI 编码代理用的持久化记忆系统。简单说：让你的 Claude Code、Codex CLI、Cursor 等代理在多次会话之间"记住"项目背景、决策历史、代码规范，不再每次从头解释。

底层基于 iii engine，不需要任何外部数据库，记忆存储在本地文件。代理每次完成任务后，agentmemory 自动把关键信息写入记忆；下次启动时自动召回 relevant 的上下文注入对话，大幅减少 token 消耗。

核心数字：95.2% R@5 召回率、减少 92% token、53 个 MCP 工具、1423+ 测试通过。

解决什么问题

AI 代理的痛点：每次新会话都是"白板"，代理不知道你项目的技术栈、代码规范、上次的决策思路。导致： - 每次要重复解释上下文（费 token、费时间） - 代理容易做出与项目规范冲突的改动 - 跨会话学习无法积累（昨天的决策今天就忘）

agentmemory 把代理的记忆做成持久的、可检索的，像给代理建了一个私人知识库。

快速安装

npm 全局安装（推荐）

npm install -g @agentmemory/agentmemory

macOS/Linux 若遇 EACCES 权限报错：

sudo npm install -g @agentmemory/agentmemory

npx 免安装（临时用）

npx -y @agentmemory/agentmemory@latest

验证安装

agentmemory                                      # 启动记忆服务器（默认端口 3111）
agentmemory demo                                 # 注入示例会话，验证召回是否正常
agentmemory demo --serve                         # 一条命令：启动服务+跑demo+自动清理

核心用法

1. 连接代理（让代理自动使用记忆）

agentmemory connect claude-code     # 连接 Claude Code
agentmemory connect codex            # 连接 Codex CLI
agentmemory connect cursor            # 连接 Cursor
agentmemory connect gemini-cli        # 连接 Gemini CLI
agentmemory connect openclaw          # 连接 OpenClaw

连接后，代理在每次对话时自动读写记忆，无需手动操作。

2. 安装原生技能（让代理知道何时用记忆）

npx skills add rohitg00/agentmemory -y

这会安装 15 个原生技能（8 个可主动调用，7 个参考用），代理能判断何时该查记忆、何时该写新记忆。

3. iii Console（实时查看记忆状态）

agentmemory console
# 浏览器打开 http://localhost:3111

iii Console 提供实时记忆查看、搜索、和会话回放功能。

4. MCP 服务器模式（支持任何 MCP 客户端）

agentmemory 也提供 MCP server，可接入任何 MCP 兼容的客户端。

5. REST API 编程调用

# 写入记忆
curl -X POST http://localhost:3111/memory \
  -H "Content-Type: application/json" \
  -d '{"type":"project","content":"本项目使用 Python 3.11，使用 Poetry 管理依赖"}'

# 检索记忆
curl "http://localhost:3111/search?q=Python+版本"

# 列出所有记忆
curl http://localhost:3111/memories

典型适用场景

  1. 长期项目维护：代理记住项目技术栈、代码规范，避免每次重新解释
  2. 多代理协作：不同代理共享同一记忆后端，保持上下文一致性
  3. Code Review 记忆：记住历史 review 结论和项目 coding style
  4. Bug 追踪：记住之前修过哪些 bug、怎么修的，防止重复踩坑
  5. 新人 onboarding：新会话代理能快速了解项目全貌

坑与注意

  1. Windows 原生支持有限：推荐用 WSL2。官方说 native Windows 手动配置约需 10-20 分钟，且 agentmemory connect 目前在 Windows 不支持。
  2. iii 版本锁定：agentmemory 固定使用 iii-engine v0.11.2，若本机已跑 iii，agentmemory 会启动自己内置的 v0.11.2，产生冲突。解决方法：先停掉本机 iii，再跑 agentmemory。
  3. npx 版本缓存：若 npx @agentmemory/agentmemory 运行的是旧版，强制指定 @latest：npx -y @agentmemory/agentmemory@latest，或清除 ~/.npm/_npx。
  4. 记忆是本地的：记忆文件存在本机，换机器或换目录后记忆不通用的。
  5. 中文项目名/路径：iii engine 对中文路径支持可能有问题（未实测，建议用英文路径）。

与同类对比

工具 记忆方式 外部依赖 支持代理 特点
agentmemory 本地文件+iii 无 Claude Code/Codex/Cursor/Gemini CLI/OpenClaw/Hermes/pi 等 0外部DB，支持最多代理，MCP 生态完整
Mem0 云端/自托管向量数据库 PostgreSQL/Pinecone 等 通用 偏云端，本地场景需额外配置
Zep 云端 云服务 通用 商业化，功能全但需付费
Continue + memories 向量数据库 Qdrant/Chroma 等 VS Code Continue 插件 绑定 IDE，本地部署需自己搭

agentmemory 的核心优势：零外部依赖，接入代理数量最多，适合不想运维数据库的个人开发者或小团队。

一句话推荐

如果你用 Claude Code 或 Codex CLI 做日常开发，装上 agentmemory 几乎零成本，能让代理真正"认识"你的项目，长期省大量重复解释的 token 和时间。