agentmemory

提供持久记忆层，让AI编码代理（如Claude Code、Cursor等）跨会话记住上下文，不再重复解释架构或偏好。基于LongMemEval基准测试达到95.2%检索准确率，且零外部数据库依赖（仅SQLite+自研引擎）。亮点包括4级记忆合并、混合检索（BM25+向量+知识图谱）、51个MCP工具和实时Web查看器，实测可减少92%的token消耗。适合需要记忆持久化的AI编码工作流。

README

agentmemory — AI 编程智能体的持久化记忆

你的编程智能体记住一切。无需反复解释。基于 iii engine 构建 为 Claude Code、Cursor、Gemini CLI、Codex CLI、pi、OpenCode 以及任何 MCP 客户端提供持久化记忆。

该 gist 扩展了 Karpathy 的 LLM Wiki 模式，增加了置信度评分、生命周期、知识图谱和混合搜索。
agentmemory 是其实现。

95.2% 召回率 R@5 减少 92% token 51 个 MCP 工具 12 个自动钩子 0 个外部数据库 827 个测试通过

agentmemory 演示

快速开始 • 基准测试 • vs 竞品 • 智能体 • 工作原理 • MCP • 查看器 • iii 控制台 • 由 iii 驱动 • 配置 • API

agentmemory 适用于任何支持 hooks、MCP 或 REST API 的智能体。所有智能体共享同一个记忆服务器。

Claude Code 12 个 hooks + MCP + skills	OpenClaw MCP + 插件	Hermes MCP + 插件	Cursor MCP 服务器	Gemini CLI MCP 服务器	OpenCode MCP 服务器	Codex CLI MCP 服务器	Cline MCP 服务器
Goose MCP 服务器	Kilo Code MCP 服务器	Aider REST API	Claude Desktop MCP 服务器	Windsurf MCP 服务器	Roo Code MCP 服务器	Claude SDK AgentSDKProvider	任何智能体 REST API

适用于支持 MCP 或 HTTP 的任何智能体。一个服务器，所有智能体共享记忆。

每次会话你都要解释相同的架构。你反复发现同样的 bug。你反复教导相同的偏好。内建记忆（CLAUDE.md、.cursorrules）上限 200 行，而且会过时。agentmemory 解决了这个问题。它静默捕获智能体的所有操作，压缩成可搜索的记忆，并在下次会话开始时注入正确的上下文。一条命令。跨智能体工作。

变化在于： 第一次会话你设置了 JWT 认证。第二次会话你要求限流。智能体已经知道你的认证使用了 src/middleware/auth.ts 中的 jose 中间件，测试覆盖了 token 验证，并且你为了 Edge 兼容性选择了 jose 而非 jsonwebtoken。无需重新解释，无需复制粘贴。智能体直接知晓。

npx @agentmemory/agentmemory

v0.9.0 新特性 — 落地页 agent-memory.dev，文件系统连接器（@agentmemory/fs-watcher），独立的 MCP 现在代理到运行中的服务器以便 hooks 和查看器一致，审计策略在所有删除路径上统一，健康检查不再对小型 Node 进程标记 memory_critical。完整说明见 CHANGELOG.md。

检索准确率

LongMemEval-S（ICLR 2025，500 个问题）

系统	R@5	R@10	MRR
agentmemory	95.2%	98.6%	88.2%
仅 BM25 备用	86.2%	94.6%	71.5%

Token 节省

方法	每年 token 数	每年费用
粘贴完整上下文	1950 万+	不可能（超出窗口）
LLM 摘要	~65 万	~$500
agentmemory	~17 万	~$10
agentmemory + 本地 embedding	~17 万	$0

Embedding 模型：all-MiniLM-L6-v2（本地，免费，无需 API 密钥）。完整报告：benchmark/LONGMEMEVAL.md、benchmark/QUALITY.md、benchmark/SCALE.md。竞品对比：benchmark/COMPARISON.md — agentmemory vs mem0、Letta、Khoj、claude-mem、Hippo。

	agentmemory	mem0（53K ⭐）	Letta / MemGPT（22K ⭐）	内建（CLAUDE.md）
类型	记忆引擎 + MCP 服务器	记忆层 API	完整智能体运行时	静态文件
检索 R@5	95.2%	68.5%（LoCoMo）	83.2%（LoCoMo）	N/A（grep）
自动捕获	12 个 hooks（零手动操作）	手动调用 `add()`	智能体自编辑	手动编辑
搜索	BM25 + 向量 + 图谱（RRF 融合）	向量 + 图谱	向量（归档）	将所有内容加载到上下文
多智能体	MCP + REST + 租约 + 信号	API（无协调）	仅在 Letta 运行时内	每个智能体各自文件
框架锁定	无（任何 MCP 客户端）	无	高（必须使用 Letta）	每个智能体格式
外部依赖	无（SQLite + iii-engine）	Qdrant / pgvector	Postgres + 向量数据库	无
记忆生命周期	4 层整合 + 衰减 + 自动遗忘	被动提取	智能体管理	手动修剪
Token 效率	每次会话约 1,900 token（每年 $10）	因集成而异	核心记忆在上下文中	240 条观察时 22K+ token
实时查看器	是（端口 3113）	云端控制面板	云端控制面板	无
自托管	是（默认）	可选	可选	是

兼容性：此版本针对稳定的 iii-sdk ^0.11.0 和 iii-engine v0.11.x。

30 秒尝试

# 终端 1：启动服务器
npx @agentmemory/agentmemory

# 终端 2：填充示例数据并查看召回效果
npx @agentmemory/agentmemory demo

demo 填充 3 个真实会话（JWT 认证、N+1 查询修复、限流），并对它们运行语义搜索。你会看到搜索 "database performance optimization" 时找到 "N+1 query fix" — 关键词匹配做不到这一点。

打开 http://localhost:3113 实时观察记忆构建过程。

会话回放

agentmemory 记录的每个会话都可回放。打开查看器，选择 Replay 标签页，在时间线上滑动：提示词、工具调用、工具结果和响应作为离散事件渲染，支持播放/暂停、速度控制（0.5×–4×）和键盘快捷键（空格切换，箭头步进）。

如果你有旧的 Claude Code JSONL 记录想要导入：

# 导入默认 ~/.claude/projects 下的所有内容
npx @agentmemory/agentmemory import-jsonl

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

导入的会话会与本机会话一起出现在 Replay 选择器中。底层每条记录都通过 mem::replay::load、mem::replay::sessions 和 mem::replay::import-jsonl iii 函数路由 — 无需旁路服务器。

升级 / 维护

当你明确想要更新本地运行时，使用维护命令：

npx @agentmemory/agentmemory upgrade

警告：此命令会修改当前工作区/运行时。它可能会更新 JavaScript 依赖项，可能会运行 cargo install iii-engine --force，并可能拉取 Docker 镜像。

实现细节位于 src/cli.ts（参见 runUpgrade 函数，位于 src/cli.ts:544-595 区域）。

Claude Code（一个代码块，直接粘贴）

安装 agentmemory：在独立终端中运行 `npx @agentmemory/agentmemory` 启动记忆服务器。然后运行 `/plugin marketplace add rohitg00/agentmemory` 和 `/plugin install agentmemory` — 该插件将注册全部 12 个 hooks、4 个 skills，并通过其 `.mcp.json` 自动连接 `@agentmemory/mcp` stdio 服务器，从而无需额外配置即可获得 51 个 MCP 工具（memory_smart_search、memory_save、memory_sessions、memory_governance_delete 等）。使用 `curl http://localhost:3111/agentmemory/health` 验证。实时查看器位于 http://localhost:3113。

OpenClaw（粘贴此提示）

为 OpenClaw 安装 agentmemory。在独立终端中运行 `npx @agentmemory/agentmemory` 启动记忆服务器（localhost:3111）。然后将以下内容添加到 OpenClaw 的 MCP 配置中，以便 agentmemory 的所有 43 个记忆工具可用：

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

重启 OpenClaw。使用 `curl http://localhost:3111/agentmemory/health` 验证。打开 http://localhost:3113 查看实时查看器。如需更深度的记忆槽集成，请将 `integrations/openclaw` 复制到 `~/.openclaw/extensions/agentmemory`，并在 `~/.openclaw/openclaw.json` 中启用 `plugins.slots.memory = "agentmemory"`。

完整指南：integrations/openclaw/

Hermes Agent（粘贴此提示）

为 Hermes 安装 agentmemory。在独立终端中运行 `npx @agentmemory/agentmemory` 启动记忆服务器（localhost:3111）。然后将以下内容添加到 ~/.hermes/config.yaml，以便 Hermes 可以将 agentmemory 用作 MCP 服务器，拥有全部 43 个记忆工具：

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

使用 `curl http://localhost:3111/agentmemory/health` 验证。打开 http://localhost:3113 查看实时查看器。如需更深度的 6 钩子记忆提供者集成（LLM 前上下文注入、turn 捕获、MEMORY.md 镜像、系统提示块），请将 agentmemory 仓库中的 integrations/hermes 复制到 ~/.hermes/plugins/agentmemory。

完整指南：integrations/hermes/

其他智能体

启动记忆服务器：npx @agentmemory/agentmemory

然后为你的智能体添加 MCP 配置：

智能体	设置方法
Cursor	添加到 `~/.cursor/mcp.json`：`{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}`
OpenClaw	添加到 MCP 配置：`{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}` 或使用记忆插件
Gemini CLI	`gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user`
Codex CLI	`codex mcp add agentmemory -- npx -y @agentmemory/mcp` 或添加 `[mcp_servers.agentmemory]` 到 `.codex/config.toml`
pi	将 `integrations/pi` 复制到 `~/.pi/agent/extensions/agentmemory` 并重启 pi
OpenCode	添加到 `opencode.json`：`{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`
Hermes Agent	添加到 `~/.hermes/config.yaml` 并设置 `memory.provider: agentmemory`，或使用记忆提供者插件
Cline / Goose / Kilo Code	在设置中添加 MCP 服务器
Claude Desktop	添加到 `claude_desktop_config.json`：`{"mcpServers": {"agentmemory": {"command": "npx", "args": ["-y", "@agentmemory/mcp"]}}}`
Aider	REST API：`curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`
任何智能体（32+）	`npx skillkit install agentmemory`

从源码构建

git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start

如果已安装 iii，则使用本地 iii-engine 启动；否则如果 Docker 可用则回退到 Docker Compose。默认绑定 REST、流和查看器到 127.0.0.1。

手动安装 iii-engine。agentmemory 目前锁定 iii-engine 为 v0.11.2 — v0.11.6 引入了新的“通过 iii worker add 沙箱化一切”模型，agentmemory 尚未针对此模型重构。当重构完成后将解除锁定。如果你已手动迁移到沙箱模型，可通过 AGENTMEMORY_III_VERSION=<version> 覆盖。

macOS arm64: mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii
macOS x64: 将 aarch64-apple-darwin 替换为 x86_64-apple-darwin
Linux x64: 替换为 x86_64-unknown-linux-gnu
Linux arm64: 替换为 aarch64-unknown-linux-gnu
Windows: 从 iii-hq/iii releases v0.11.2 下载 iii-x86_64-pc-windows-msvc.zip，解压 iii.exe，添加到 PATH

或使用 Docker（附带的 docker-compose.yml 拉取 iiidev/iii:0.11.2）。完整文档：iii.dev/docs。

Windows

agentmemory 可在 Windows 10/11 上运行，但仅 Node.js 包不够 — 你还需要将 iii-engine 运行时（一个单独的原生二进制文件）作为后台进程运行。官方的上游安装器是一个 sh 脚本，目前没有 PowerShell 安装器或 scoop/winget 包，因此 Windows 用户有两种路径：

选项 A — 预构建的 Windows 二进制（推荐）：

# 1. 在浏览器中打开 https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2
#    （我们锁定到 v0.11.2，直到 agentmemory 为引擎 v0.11.6+ 所需的新沙箱模型重构）
# 2. 下载 iii-x86_64-pc-windows-msvc.zip
#    （如果是 ARM 机器，下载 iii-aarch64-pc-windows-msvc.zip）
# 3. 将 iii.exe 解压到 PATH 中的某个位置，或放在：
#    %USERPROFILE%\.local\bin\iii.exe
#    （agentmemory 会自动检查该位置）
# 4. 验证：
iii --version
# 应输出：0.11.2

# 5. 然后照常运行 agentmemory：
npx -y @agentmemory/agentmemory

选项 B — Docker Desktop：

# 1. 安装 Windows 版 Docker Desktop
# 2. 启动 Docker Desktop 并确保引擎正在运行
# 3. 运行 agentmemory — 它将自动启动附带的 compose 文件：
npx -y @agentmemory/agentmemory

选项 C — 仅独立 MCP（无引擎）： 如果只需要智能体的 MCP 工具，不需要 REST API、查看器或 cron 任务，则可完全跳过引擎：

npx -y @agentmemory/agentmemory mcp
# 或通过 shim 包：
npx -y @agentmemory/mcp

Windows 诊断： 如果 npx @agentmemory/agentmemory 失败，使用 --verbose 重新运行以查看引擎 stderr。常见失败模式：

症状	修复
`iii-engine process started` 然后 `did not become ready within 15s`	引擎启动时崩溃 — 使用 `--verbose` 重新运行，检查 stderr
`Could not start iii-engine`	既未安装 `iii.exe` 也未安装 Docker。参见上方选项 A 或 B
端口冲突	`netstat -ano \| findstr :3111` 查看绑定内容，然后杀死或使用 `--port <N>`
即使已安装 Docker 也跳过了 Docker 回退	确保 Docker Desktop 正在运行（系统托盘图标）

注意：没有 cargo install iii-engine — iii 未发布到 crates.io。唯一支持的安装方法是上述预构建二进制、上游 sh 安装脚本（仅 macOS/Linux）和 Docker 镜像。

每个编程智能体在会话结束后都会忘记一切。你每次会话都要浪费前 5 分钟重新解释你的技术栈。agentmemory 在后台运行，完全消除这一点。

会话 1："为 API 添加认证"
  智能体编写代码、运行测试、修复 bug
  agentmemory 静默捕获每次工具使用
  会话结束 -> 观察结果压缩为结构化记忆

会话 2："现在添加限流"
  智能体已经知道：
    - 认证使用 src/middleware/auth.ts 中的 JWT 中间件
    - test/auth.test.ts 中的测试覆盖 token 验证
    - 你为了 Edge 兼容性选择了 jose 而非 jsonwebtoken
  零重新解释。立即开始工作。

vs 内建智能体记忆

每个 AI 编程智能体都自带内建记忆 — Claude Code 有 MEMORY.md，Cursor 有记事本，Cline 有记忆银行。它们像便利贴一样工作。agentmemory 是便利贴背后的可搜索数据库。

| | 内建（CL

开源项目rohitg002026-05-09原文

打开互动版