rohitg00/agentmemory GitHub: rohitg00/agentmemory
为 AI 编程助手提供跨会话持久化记忆的 MCP 服务器，让智能体自动记住项目上下文和技术决策，无需反复解释。
Stars: 3920 | Forks: 381
你的编码助手能记住一切。无需反复解释。
基于 iii engine 构建
适用于 Claude Code、Cursor、Gemini CLI、Codex CLI、pi、OpenCode 以及任何 MCP 客户端的持久化记忆。
核心要点是在 Karpathy 的 LLM Wiki 模式基础上进行了扩展，增加了置信度评分、生命周期、知识图谱和混合搜索。
快速开始 •
性能基准 •
竞品对比 •
智能体 •
工作原理 •
MCP •
查看器 •
iii 控制台 •
由 iii 驱动 •
配置 •
API
agentmemory 支持任何兼容 hooks、MCP 或 REST API 的智能体。所有智能体共享同一个记忆服务器。
Claude Code 12 hooks + MCP + skills
OpenClaw MCP + plugin
Hermes MCP + plugin
Cursor MCP server
Gemini CLI MCP server
OpenCode MCP server
Codex CLI MCP server
Cline MCP server
Goose MCP server
Kilo Code MCP server
Aider REST API
Claude Desktop MCP server
Windsurf MCP server
Roo Code MCP server
Claude SDK AgentSDKProvider
Any agent REST API
兼容任何 支持 MCP 或 HTTP 的智能体。一个服务器，所有记忆跨平台共享。
你每次会话都在重复解释相同的架构。你反复踩同一个 Bug。你不断重复相同的偏好设置。内置记忆（如 CLAUDE.md、.cursorrules）最多只能写 200 行，而且很容易过时。agentmemory 解决了这个问题。它会静默捕获你的智能体操作，将其压缩为可搜索的记忆，并在下一个会话开始时注入正确的上下文。只需一个命令。跨智能体通用。
**效果展示：** 在会话 1 中你设置了 JWT 认证。在会话 2 中你要求添加速率限制。智能体已经知道你的认证使用了 `src/middleware/auth.ts` 中的 jose 中间件，你的测试涵盖了 token 验证，并且你为了 Edge 兼容性选择了 jose 而不是 jsonwebtoken。无需重新解释。无需复制粘贴。智能体就是*知道*。
```
npx @agentmemory/agentmemory
```
### 检索准确率
**LongMemEval-S** (ICLR 2025，500 个问题)
| System | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| 仅 BM25 备用方案 | 86.2% | 94.6% | 71.5% |
### Token 节省量
| Approach | Tokens/yr | Cost/yr |
|---|---|---|
| 粘贴完整上下文 | 19.5M+ | 不可能（超出窗口限制） |
| LLM 摘要 | ~650K | ~$500 |
| **agentmemory** | **~170K** | **~$10** |
| agentmemory + 本地 Embeddings | ~170K | **$0** |
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 tokens/会话 ($10/年)
因集成而异
核心记忆保留在上下文中
240 次观察需 22K+ tokens
实时查看器 支持（端口 3113）
云端仪表盘
云端仪表盘
不支持
自托管 支持（默认）
可选
可选
支持
兼容性说明：此版本针对稳定版 `iii-sdk` `^0.11.0` 和 iii-engine v0.11.x。
### 30 秒试用
```
# Terminal 1: start the server
npx @agentmemory/agentmemory
# Terminal 2: seed sample data and see recall in action
npx @agentmemory/agentmemory demo
```
`demo` 会植入 3 个真实会话（JWT 认证、N+1 查询修复、速率限制）并针对它们运行语义搜索。你会看到当搜索“数据库性能优化”时，它能找到“N+1 查询修复”——关键词匹配是做不到这一点的。
打开 `http://localhost:3113` 观看实时的记忆构建过程。
### 会话回放
agentmemory 记录的每个会话都可以回放。打开查看器，选择 **Replay** 选项卡，拖动时间轴滑块：提示词、工具调用、工具结果和响应都以独立事件的形式呈现，支持播放/暂停、速度控制（0.5×–4×）和键盘快捷键（空格键切换，方向键单步执行）。
已经有旧的 Claude Code JSONL 转录记录想要导入？
```
# Import everything under the default ~/.claude/projects
npx @agentmemory/agentmemory import-jsonl
# Or import a single file
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
导入的会话将与原生会话一起显示在回放选择器中。在底层，每个条目通过 `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` 中（参见 `src/cli.ts:544-595` 区域附近的 `runUpgrade`）。
### Claude Code（复制粘贴这一个代码块）
```
Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 51 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
```
OpenClaw（粘贴此提示词）
Hermes Agent（粘贴此提示词）
### 其他智能体
启动记忆服务器：`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"]}}}` 或使用 [记忆插件](integrations/openclaw/) |
| **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`](integrations/pi/) 到 `~/.pi/agent/extensions/agentmemory` 并重启 pi |
| **OpenCode** | 添加到 `opencode.json`：`{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}` |
| **Hermes Agent** | 将 `memory.provider: agentmemory` 添加到 `~/.hermes/config.yaml` 或使用 [记忆提供者插件](integrations/hermes/) |
| **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` 启动 agentmemory，或者在 Docker 可用时回退到 Docker Compose。REST、流和查看器默认绑定到 `127.0.0.1`。
手动安装 `iii-engine`。**agentmemory 目前将 `iii-engine` 锁定在 `v0.11.2` 版本** —— `v0.11.6` 引入了全新的 sandbox-everything-via-`iii worker add` 模型，agentmemory 尚未为此进行重构。重构完成后锁定的版本将解除。如果你已手动迁移到沙盒模型，可以通过 `AGENTMEMORY_III_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](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2) 下载 `iii-x86_64-pc-windows-msvc.zip`，解压 `iii.exe`，添加到 PATH
或者使用 Docker（附带的 `docker-compose.yml` 会拉取 `iiidev/iii:0.11.2`）。完整文档：[iii.dev/docs](https://iii.dev/docs)。
### Windows台
agentmemory 可以在 Windows 10/11 上运行，但仅有 Node.js 包是不够的——你还需要将 `iii-engine` 运行时（一个独立的原生二进制文件）作为后台进程。官方上游安装程序是一个 `sh` 脚本，目前没有 PowerShell 安装程序或 scoop/winget 包，因此 Windows 用户有两条路径：
**方案 A — 预编译的 Windows 二进制文件（推荐）：**
```
# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
# (we pin to v0.11.2 until agentmemory refactors for the new sandbox
# model that engine v0.11.6+ requires)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe somewhere on PATH, or place it at:
# %USERPROFILE%\.local\bin\iii.exe
# (agentmemory checks that location automatically)
# 4. Verify:
iii --version
# Should print: 0.11.2
# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory
```
**方案 B — Docker Desktop：**
```
# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Run agentmemory — it will auto-start the bundled compose file:
npx -y @agentmemory/agentmemory
```
**方案 C — 仅独立 MCP（无引擎）：** 如果你只需要智能体的 MCP 工具，而不需要 REST API、查看器或 cron 任务，可以完全跳过引擎：
```
npx -y @agentmemory/agentmemory mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**Windows 诊断：** 如果 `npx @agentmemory/agentmemory` 失败，请使用 `--verbose` 重新运行以查看实际的引擎标准错误输出。常见故障模式：
| 症状 | 解决方法 |
|---|---|
| 出现 `iii-engine process started` 然后 `did not become ready within 15s` | 引擎在启动时崩溃——使用 `--verbose` 重新运行，检查标准错误输出 |
| `Could not start iii-engine` | 未安装 `iii.exe` 或 Docker。请参见上面的方案 A 或 B |
| 端口冲突 | 运行 `netstat -ano \| findstr :3111` 查看占用端口的进程，然后结束该进程或使用 `--port ` |
| 即使安装了 Docker，也跳过了 Docker 备用方案 | 确保 Docker Desktop 实际正在运行（系统托盘图标） |
` 标签在存储前会被剥离 |
| **自我修复** | 断路器、提供者回退链、健康监控 |
| **Claude 桥接** | 与 MEMORY.md 双向同步 |
| **知识图谱** | 实体提取 + BFS 遍历 |
| **团队记忆** | 跨团队成员的命名空间共享 + 私有记忆 |
| **引用溯源** | 将任何记忆追溯到原始观察结果 |
| **Git 快照** | 版本控制、回滚和对比记忆状态 |
核心工具（始终可用）
| 工具 | 描述 |
|------|-------------|
| `memory_recall` | 搜索过去的观察结果 |
| `memory_compress_file` | 压缩 Markdown 文件同时保留结构 |
| `memory_save` | 保存洞察、决策或模式 |
| `memory_patterns` | 检测重复模式 |
| `memory_smart_search` | 混合语义 + 关键词搜索 |
| `memory_file_history` | 关于特定文件的过往观察 |
| `memory_sessions` | 列出最近的会话 |
| `memory_timeline` | 按时间顺序的观察结果 |
| `memory_profile` | 项目档案（概念、文件、模式） |
| `memory_export` | 导出所有记忆数据 |
| `memory_relations` | 查询关系图谱 |
扩展工具（共 50 个——需设置 AGENTMEMORY_TOOLS=all）
| 工具 | 描述 |
|------|-------------|
| `memory_patterns` | 检测重复模式 |
| `memory_timeline` | 按时间顺序的观察结果 |
| `memory_relations` | 查询关系图谱 |
| `memory_graph_query` | 知识图谱遍历 |
| `memory_consolidate` | 运行 4 级合并 |
| `memory_claude_bridge_sync` | 与 MEMORY.md 同步 |
| `memory_team_share` | 与团队成员共享 |
| `memory_team_feed` | 最近的共享项目 |
| `memory_audit` | 操作审计追踪 |
| `memory_governance_delete` | 带审计追踪的删除 |
| `memory_snapshot_create` | Git 版本控制的快照 |
| `memory_action_create` | 创建具有依赖关系的工作项 |
| `memory_action_update` | 更新动作状态 |
| `memory_frontier` | 按优先级排序的未阻塞动作 |
| `memory_next` | 单个最重要的下一步动作 |
| `memory_lease` | 独占动作租约（多智能体） |
| `memory_routine_run` | 实例化工作流例程 |
| `memory_signal_send` | 智能体间消息传递 |
| `memory_signal_read` | 读取带回执的消息 |
| `memory_checkpoint` | 外部条件门控 |
| `memory_mesh_sync` | 实例间的 P2P 同步 |
| `memory_sentinel_create` | 事件驱动的监视器 |
| `memory_sentinel_trigger` | 外部触发哨兵 |
| `memory_sketch_create` | 临时动作图 |
| `memory_sketch_promote` | 提升为永久状态 |
| `memory_crystallize` | 紧凑动作链 |
| `memory_diagnose` | 健康检查 |
| `memory_heal` | 自动修复卡住的状态 |
| `memory_facet_tag` | 维度:值 标签 |
| `memory_facet_query` | 按 facet 标签查询 |
| `memory_verify` | 追溯来源 |
### 6 个资源 · 3 个提示词 · 4 个技能
| 类型 | 名称 | 描述 |
|------|------|-------------|
| 资源 | `agentmemory://status` | 健康状态、会话数、记忆数 |
| 资源 | `agentmemory://project/{name}/profile` | 单项目的智能信息 |
| 资源 | `agentmemory://memories/latest` | 最新的 10 条活动记忆 |
| 资源 | `agentmemory://graph/stats` | 知识图谱统计信息 |
| 提示词 | `recall_context` | 搜索 + 返回上下文消息 |
| 提示词 | `session_handoff` | 智能体间的移交数据 |
| 提示词 | `detect_patterns` | 分析重复模式 |
| 技能 | `/recall` | 搜索记忆 |
| 技能 | `/remember` | 保存到长期记忆 |
| 技能 | `/session-history` | 最近的会话摘要 |
| 技能 | `/forget` | 删除观察/会话 |
### 独立 MCP
无需完整服务器即可运行——适用于任何 MCP 客户端。以下任一方式均可：
```
npx -y @agentmemory/agentmemory mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
或者添加到你的智能体的 MCP 配置中：
大多数智能体（Cursor、Claude Desktop、Cline 等）：
```
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"]
}
}
}
```
OpenCode (`opencode.json`)：
```
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
}
}
```
Workers page: every connected worker — including agentmemory itself — with PID, function count, runtime, and last-seen.
**已预装。** 控制台随 `iii` 一起提供——无需单独安装。
**与 agentmemory 一起启动：**
```
# agentmemory viewer holds port 3113, so run the console on 3114.
# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
iii console --port 3114
```
然后打开 `http://localhost:3114`。添加 `--enable-flow` 可开启实验性的图页面。
仅在更改过引擎端点时才需要覆盖配置：
```
iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**你可以从控制台执行的操作：**
| 页面 | 用途 |
|------|-----------|
| **Workers** | 查看每个已连接的 worker 及其实时指标——包括 agentmemory worker 本身。 |
| **Functions** | 使用 JSON Payload 直接调用 agentmemory 的任何函数——非常适合在不连接客户端的情况下测试 `memory.recall`、`memory.consolidate`、`graph.query`。 |
| **Triggers** | 重放 HTTP、cron、event 和 state 触发器——手动触发合并 cron，重试 HTTP 路由，发出状态更改。 |
| **States** | 支持完整 CRUD 的 KV 浏览器——会话、记忆槽、生命周期计时器、Embeddings 索引——可原地编辑值。 |
| **Streams** | 针对 memory 写入、hook 事件和观察更新的实时 WebSocket 监控器，数据流经 iii streams。 |
| **Queues** | 持久化队列主题 + 死信管理。重放或丢弃失败的 Embedding / 压缩任务。 |
| **Traces** | OpenTelemetry 瀑布图 / 火焰图 / 服务分解视图。通过 `trace_id` 筛选，准确查看单个 `memory.search` 产生了哪些函数、数据库调用和 Embedding 请求。 |
| **Logs** | 结构化 OTEL 日志，可过滤并与 trace/span ID 相关联。 |
| **Config** | 运行时配置——准确查看你的引擎正在运行哪些 workers、提供者和端口。 |
| **Flow** | （可选，`--enable-flow`）显示每个 worker、trigger 和 stream 的交互式架构图。 |
Traces: waterfall / flame / service breakdown for every memory operation.
**追踪已默认开启：**
`iii-config.yaml` 附带已启用的 `iii-observability` worker（`exporter: memory`、`sampling_ratio: 1.0`、metrics + logs）。无需额外配置——从 agentmemory 启动的那一刻起，每个记忆操作都会发出一个 trace span 和控制台可读的结构化日志。
如果你想导出到 Jaeger/Honeycomb/Grafana Tempo，请将 `exporter: memory` 更改为 `exporter: otlp`，并根据 iii 的可观测性文档设置 collector endpoint。
` |
**118 个源文件 · 约 21,800 行代码 · 800 个测试 · 123 个函数 · 34 个 KV 作用域**——全部基于三个原语构建。不需要 `agentmemory plugin install`。插件系统就是 iii 本身。
`，并且 Mesh 同步端点要求两个对等点都设置了 `AGENTMEMORY_SECRET`。
核心端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | 健康检查（始终公开） |
| `POST` | `/agentmemory/session/start` | 启动会话 + 获取上下文 |
| `POST` | `/agentmemory/session/end` | 结束会话 |
| `POST` | `/agentmemory/observe` | 捕获观察结果 |
| `POST` | `/agentmemory/smart-search` | 混合搜索 |
| `POST` | `/agentmemory/context` | 生成上下文 |
| `POST` | `/agentmemory/remember` | 保存到长期记忆 |
| `POST` | `/agentmemory/forget` | 删除观察结果 |
| `POST` | `/agentmemory/enrich` | 文件上下文 + 记忆 + Bug |
| `GET` | `/agentmemory/profile` | 项目档案 |
| `GET` | `/agentmemory/export` | 导出所有数据 |
| `POST` | `/agentmemory/import` | 从 JSON 导入 |
| `POST` | `/agentmemory/graph/query` | 知识图谱查询 |
| `POST` | `/agentmemory/team/share` | 与团队共享 |
| `GET` | `/agentmemory/audit` | 审计追踪 |
完整端点列表：[`src/triggers/api.ts`](src/triggers/api.ts)
标签： AI编程助手, Claude Code, Cursor, DLL 劫持, DNS解析, Gemini CLI, GNU通用公共许可证, LLM记忆, MCP客户端, MITM代理, Node.js, NPM包, OSV-Scalibr, RAG, SOC Prime, 上下文管理, 人工智能, 代码生成, 向量检索, 大语言模型, 威胁情报, 开发工具, 开发者工具, 开源项目, 持久化存储, 搜索引擎, 混合搜索, 渗透测试工具, 生命周期管理, 用户代理, 用户模式Hook绕过, 置信度评分, 自动化攻击
