diff --git a/README.md b/README.md index d04da37..e82e375 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,19 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/rohitg00/agentmemory) · [上游 README](https://github.com/rohitg00/agentmemory/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

- agentmemory — Persistent memory for AI coding agents + agentmemory — 面向 AI 编程智能体的持久化记忆

- Your coding agent remembers everything. No more re-explaining. - Built on iii engine + 你的编程智能体会记住一切。再也不用重复解释。 + 基于 iii engine 构建
- Persistent memory for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client. + 为 Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode 及任意 MCP 客户端提供持久化记忆。

@@ -34,17 +40,17 @@ - Star History Chart + Star 历史图表

- Design doc: 1.3k stars / 182 forks on the gist + 设计文档：gist 上 1.3k stars / 182 forks

- The gist extends Karpathy's LLM Wiki pattern with confidence scoring, lifecycle, knowledge graphs, and hybrid search: agentmemory is the implementation. + 该 gist 在 Karpathy 的 LLM Wiki 模式上扩展了置信度评分、生命周期、知识图谱与混合搜索：agentmemory 即其实现。

@@ -56,41 +62,41 @@

95.2% retrieval R@5 - 92% fewer tokens - 53 MCP tools - 12 auto hooks - 0 external DBs - 1,423+ tests passing + 减少 92% token + 53 个 MCP 工具 + 12 个自动 hooks + 0 个外部数据库 + 1,423+ 项测试通过

- agentmemory demo + agentmemory 演示

- Install • - Quick Start • - Benchmarks • - vs Competitors • - Agents • - How It Works • + 安装 • + 快速开始 • + 基准测试 • + 与竞品对比 • + 智能体 • + 工作原理 • MCP • - Viewer • + 查看器 • iii Console • - Powered by iii • - Config • + 由 iii 驱动 • + 配置 • API

--- -## Install +## 安装 -Fastest path if you use a coding agent: hand it this one instruction and it installs, wires, and verifies agentmemory end to end. +若你使用编程智能体，最快方式是：把下面这一条指令交给它，即可端到端完成 agentmemory 的安装、接入与验证。 -> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md +> 请获取并遵循以下位置的说明：https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md -On Windows the fast path is WSL2. Native Windows engine setup is manual (about 10 to 20 minutes) and `agentmemory connect` is currently unsupported there. See the [Windows notes](#windows) below for the step-by-step. +在 Windows 上，快速路径是 WSL2。原生 Windows 引擎需手动配置（约 10 至 20 分钟），且 `agentmemory connect` 目前尚不支持。分步说明见下方 [Windows 说明](#windows)。 ```bash npm install -g @agentmemory/agentmemory # once — bare `agentmemory` on PATH @@ -103,35 +109,35 @@ agentmemory connect claude-code # wire MCP into your agent (als npx skills add rohitg00/agentmemory -y # install 15 native skills (8 you can invoke, 7 reference) so your agent knows when to use the tools ``` -Or via `npx` (no install): +或通过 `npx`（无需安装）： ```bash npx @agentmemory/agentmemory ``` -Heads-up — npx caches per version. If a bare `npx @agentmemory/agentmemory` serves an older release, force the latest with `npx -y @agentmemory/agentmemory@latest`, or clear the cache once with `rm -rf ~/.npm/_npx` (macOS/Linux; on Windows delete `%LOCALAPPDATA%\npm-cache\_npx`). The first npx run from v0.9.16+ prompts to install globally inline so the bare `agentmemory` command works everywhere afterwards. +提示 — npx 会按版本缓存。如果裸用 `npx @agentmemory/agentmemory` 拉取到的是旧版本，请用 `npx -y @agentmemory/agentmemory@latest` 强制使用最新版，或用 `rm -rf ~/.npm/_npx` 清除缓存一次（macOS/Linux；在 Windows 上请删除 `%LOCALAPPDATA%\npm-cache\_npx`）。从 v0.9.16+ 起首次 npx 运行会提示全局内联安装，之后裸用 `agentmemory` 命令即可在各处生效。 -Already running your own `iii` engine? agentmemory pins iii-engine v0.11.2 and won't attach to a different version (the worker can't speak another engine's protocol). Stop the other engine, then run `npx -y @agentmemory/agentmemory@latest` — it installs and runs the pinned v0.11.2 in `~/.agentmemory/bin`, leaving your own `iii` untouched. +已在运行自己的 `iii` 引擎？agentmemory 固定使用 iii-engine v0.11.2，不会挂接到其他版本（worker 无法与另一引擎的协议通信）。请先停止其他引擎，再运行 `npx -y @agentmemory/agentmemory@latest` —— 它会在 `~/.agentmemory/bin` 中安装并运行固定的 v0.11.2，不会动你自己的 `iii`。 -Full options at [Quick Start](#quick-start) below. Agent-specific wiring at [Works with every agent](#works-with-every-agent). +完整选项见下方 [Quick Start](#quick-start)。各 Agent 的接入方式见 [Works with every agent](#works-with-every-agent)。 --- -

Works with every agent

+

适用于所有 Agent

-agentmemory works with any agent that supports hooks, MCP, or REST API. All agents share the same memory server. +agentmemory 可与任何支持 hooks、MCP 或 REST API 的 Agent 配合使用。所有 Agent 共享同一套 memory server。
Claude Code
Claude Code
-native plugin + 12 hooks + MCP +原生 plugin + 12 个 hooks + MCP 		Codex CLI
Codex CLI
-native plugin + 6 hooks + MCP +原生 plugin + 6 个 hooks + MCP 		GitHub Copilot CLI
@@ -141,22 +147,22 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen 		OpenClaw
OpenClaw
-native plugin + MCP +原生 plugin + MCP 		Hermes
Hermes
-native plugin + MCP +原生 plugin + MCP 		pi
pi
-native plugin + MCP +原生 plugin + MCP 		OpenHuman
OpenHuman
-native Memory trait backend +原生 Memory trait 后端 		Cursor
@@ -173,7 +179,7 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen 		OpenCode
OpenCode
-22 hooks + MCP + plugin +22 个 hooks + MCP + plugin 		Cline
@@ -221,41 +227,41 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen

- Works with any agent that speaks MCP or HTTP. One server, memories shared across all of them. + 适用于说 MCP 或 HTTP 的任何 agent。一个服务器，所有 agent 共享记忆。

--- -You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences. Built-in memory (CLAUDE.md, .cursorrules) caps out at 200 lines and goes stale. agentmemory fixes this. It silently captures what your agent does, compresses it into searchable memory, and injects the right context when the next session starts. One command. Works across agents. +每个会话你都要重复解释同一套架构。你重新发现同样的 bug。你反复教授同样的偏好。内置记忆（CLAUDE.md、.cursorrules）上限约 200 行且会过时。agentmemory 解决了这个问题。它会静默捕获 agent 的行为，压缩为可搜索的记忆，并在下次会话开始时注入合适的上下文。一条命令。跨 agent 通用。 -**What changes:** Session 1 you set up JWT auth. Session 2 you ask for rate limiting. The agent already knows your auth uses jose middleware in `src/middleware/auth.ts`, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility. No re-explaining. No copy-pasting. The agent just *knows*. +**会有什么变化：** 第 1 次会话你配置 JWT auth。第 2 次会话你要求 rate limiting。agent 已经知道你的 auth 在 `src/middleware/auth.ts` 中使用 jose 中间件，测试覆盖 token 验证，且你因 Edge 兼容性选择 jose 而非 jsonwebtoken。无需重复解释。无需复制粘贴。agent 就是*知道*。 ```bash npx @agentmemory/agentmemory ``` -Latest release notes: [CHANGELOG.md](CHANGELOG.md). +最新发布说明：[CHANGELOG.md](CHANGELOG.md)。 --- -

Benchmarks

+

基准测试

-### Retrieval Accuracy +### 检索准确率 -**coding-agent-life-v1** (in-house corpus, sandbox-reproducible) +**coding-agent-life-v1**（内部语料库，沙箱可复现） | Adapter | P@5 | R@5 | Top-5 hit rate | p50 latency | |---|---|---|---|---| | **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms | | grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms | -100% top-5 hit rate at the **P@5 math ceiling** for this corpus (0.240, see scorecard). Hybrid retrieves every gold session; grep misses 1 of 2 gold on the multi-session temporal query. Lift is **recall + temporal**, not aggregate precision — this benchmark is small + gold-sparse, the larger LongMemEval-S below differentiates better. Full per-type breakdown + correction note: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](docs/benchmarks/2026-05-20-coding-agent-life-v1.md). +在此语料库上达到 **P@5 数学上限**（0.240，见 scorecard）的 100% top-5 命中率。Hybrid 检索到每个 gold session；grep 在多会话时序查询中 2 个 gold 漏掉 1 个。提升来自 **召回率 + 时序**，而非整体精确率——该基准规模小且 gold 稀疏，下方更大的 LongMemEval-S 区分度更好。完整分类型拆解与修正说明：[`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](docs/benchmarks/2026-05-20-coding-agent-life-v1.md)。 -**LongMemEval-S** (ICLR 2025, 500 questions) +**LongMemEval-S**（ICLR 2025，500 道题） | System | R@5 | R@10 | MRR | |---|---|---|---| @@ -265,7 +271,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). -### Token Savings +### Token 节省 | Approach | Tokens/yr | Cost/yr | |---|---|---| @@ -278,15 +284,15 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md).
-> Embedding model: `all-MiniLM-L6-v2` (local, free, no API key). Full reports: [`benchmark/LONGMEMEVAL.md`](benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](benchmark/QUALITY.md), [`benchmark/SCALE.md`](benchmark/SCALE.md). Competitor comparison: [`benchmark/COMPARISON.md`](benchmark/COMPARISON.md) covering agentmemory vs mem0, Letta, Khoj, supermemory, MemPalace, Hippo. +> Embedding model: `all-MiniLM-L6-v2`（本地、免费、无需 API key）。完整报告：[`benchmark/LONGMEMEVAL.md`](benchmark/LONGMEMEVAL.md)、[`benchmark/QUALITY.md`](benchmark/QUALITY.md)、[`benchmark/SCALE.md`](benchmark/SCALE.md)。竞品对比：[`benchmark/COMPARISON.md`](benchmark/COMPARISON.md)，涵盖 agentmemory 与 mem0、Letta、Khoj、supermemory、MemPalace、Hippo。 -**Reproduce locally:** [`eval/README.md`](eval/README.md) — adapter-pluggable harness for LongMemEval `_s` (public 500-Q) + `coding-agent-life-v1` (in-house 15-session corpus). Grep / vector / agentmemory adapters score side-by-side, NDJSON output, published scorecards land in [`docs/benchmarks/`](docs/benchmarks/). +**本地复现：** [`eval/README.md`](eval/README.md)——可插拔 adapter 的评测框架，支持 LongMemEval `_s`（公开 500 题）与 `coding-agent-life-v1`（内部 15-session 语料库）。Grep / vector / agentmemory adapter 并排计分，NDJSON 输出，发布的 scorecard 存放于 [`docs/benchmarks/`](docs/benchmarks/)。 -**Pairs with [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), and [Graphify](https://github.com/safishamsi/graphify).** Code-graph indexing, multi-agent build pipelines, and broader knowledge graphs across docs / PDFs / images / videos. agentmemory remembers the work; those three projects light up the rest of the context layer. Recipes + question-routing table: [`docs/recipes/pairings.md`](docs/recipes/pairings.md). +**搭配 [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), 与 [Graphify](https://github.com/safishamsi/graphify).**：**代码图（Code-graph）**索引、多 agent 构建流水线，以及跨文档 / PDF / 图片 / 视频的更广泛知识图谱。agentmemory 记住工作成果；这三个项目点亮其余上下文层。配方与问题路由表：[`docs/recipes/pairings.md`](docs/recipes/pairings.md)。 --- -

vs Competitors

+

与竞品对比

@@ -302,7 +308,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -314,7 +320,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -326,8 +332,8 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - - + + @@ -338,7 +344,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -350,7 +356,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -362,7 +368,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -374,7 +380,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -386,7 +392,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -398,7 +404,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -410,7 +416,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -422,7 +428,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md). - + @@ -435,15 +441,15 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md).
Built-in (CLAUDE.md)
Type类型 Memory engine + MCP server Memory layer API Full agent runtimeStatic file
Retrieval R@5检索 R@5 95.2% 68.5% (LoCoMo) 83.2% (LoCoMo)N/A (grep)
Auto-capture12 hooks (zero manual effort)自动捕获12 hooks（零手动操作） Manual add() calls Agent self-edits ManualManual editing
Search搜索 BM25 + Vector + Graph (RRF fusion) Vector + Graph Vector (archival)Loads everything into context
Multi-agent多 agent MCP + REST + leases + signals API (no coordination) Within Letta runtime onlyPer-agent files
Framework lock-in框架锁定 None (any MCP client) None High (must use Letta)Per-agent format
External deps外部依赖 None (SQLite + iii-engine) Qdrant / pgvector Postgres + vector DBNone
Memory lifecycle记忆生命周期 4-tier consolidation + decay + auto-forget Passive extraction Agent-managedManual pruning
Token efficiencyToken 效率 ~1,900 tokens/session ($10/yr) Varies by integration Core memory in context22K+ tokens at 240 obs
Real-time viewer实时查看器 Yes (port 3113) Cloud dashboard Cloud dashboardNo
Self-hosted自托管 Yes (default) Optional Optional
-Benchmark note: only agentmemory's R@5 is our own measured result (LongMemEval-S, reproducible from benchmark/COMPARISON.md). The mem0 and Letta figures are their published LoCoMo numbers (a different dataset); the MemPalace, supermemory, and oracleagentmemory figures are vendor self-reported claims we have not independently reproduced (oracleagentmemory's run used GPT-5.5 against an Oracle AI Database). Shown side by side for ballpark only, not a head-to-head on identical data. Star counts are approximate and drift over time. +基准测试说明：仅 agentmemory 的 R@5 为我们自行测量的结果（LongMemEval-S，可从 benchmark/COMPARISON.md 复现）。mem0 与 Letta 的数据为其公布的 LoCoMo 数字（不同数据集）；MemPalace、supermemory 与 oracleagentmemory 的数据为厂商自行报告、我们尚未独立复现的声明（oracleagentmemory 的运行使用 GPT-5.5 搭配 Oracle AI Database）。并列展示仅供粗略参考，并非在相同数据上的正面交锋。Star 数量为近似值，会随时间变化。 --- -

Quick Start

+

快速开始

-Compatibility: this release targets stable `iii-sdk` `^0.11.0` and iii-engine v0.11.x. +兼容性：本版本面向稳定的 `iii-sdk` `^0.11.0` 与 iii-engine v0.11.x。 -### Try it in 30 seconds +### 30 秒快速体验 ```bash # Terminal 1: start the server @@ -453,13 +459,13 @@ npx @agentmemory/agentmemory npx @agentmemory/agentmemory demo ``` -`demo` seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting) and runs semantic searches against them. You'll see it find "N+1 query fix" when you search "database performance optimization" — keyword matching can't do that. +`demo` 会初始化 3 个真实会话（JWT auth、N+1 查询修复、rate limiting），并对它们运行语义搜索。当你搜索「database performance optimization」时，它会找到「N+1 query fix」——关键词匹配做不到这一点。 -Open `http://localhost:3113` to watch the memory build live. +打开 `http://localhost:3113` 实时观看 memory 构建过程。 -### Recommended: install globally +### 推荐：全局安装 -`npx` caches per-version. If you ran `npx @agentmemory/agentmemory@0.9.14` last week, a bare `npx @agentmemory/agentmemory` may serve the stale 0.9.14 from `~/.npm/_npx/`, not the latest release. Install once and the bare `agentmemory` command works everywhere: +`npx` 会按版本缓存。如果你上周运行过 `npx @agentmemory/agentmemory@0.9.14`，裸用的 `npx @agentmemory/agentmemory` 可能仍会从 `~/.npm/_npx/` 提供过时的 0.9.14，而不是最新发布版。全局安装一次后，裸用的 `agentmemory` 命令即可随处使用： ```bash npm install -g @agentmemory/agentmemory @@ -472,20 +478,20 @@ agentmemory connect claude-code # wire one agent agentmemory doctor # interactive diagnostics + fix prompts ``` -From v0.9.16 onward, the first npx run prompts you to install globally inline — answer `Y` once and you're set. If you skip, fall back to either of these for a fresh fetch: +从 v0.9.16 起，首次 npx 运行会内联提示你进行全局安装——回答一次 `Y` 即可。若跳过，可改用以下任一方式获取最新版本： ```bash npx -y @agentmemory/agentmemory@latest # forces latest from npm (cross-platform) rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory # macOS/Linux only (POSIX shell) ``` -On Windows / PowerShell, the equivalent cache clear is `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — the `npx -y ...@latest` form above is the cross-platform option. +在 Windows / PowerShell 上，等效的缓存清理命令是 `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"`——上文中的 `npx -y ...@latest` 形式是跨平台方案。 -### Session Replay +### 会话回放（Session Replay） -Every session agentmemory records is replayable. Open the viewer, pick the **Replay** tab, and scrub through the timeline: prompts, tool calls, tool results, and responses render as discrete events with play/pause, speed control (0.5×–4×), and keyboard shortcuts (space to toggle, arrows to step). +agentmemory 记录的每个会话都可回放。打开查看器，选择 **Replay** 标签页，在时间轴上拖动浏览：prompts、tool calls、tool results 和 responses 会渲染为离散事件，支持播放/暂停、速度控制（0.5×–4×）以及键盘快捷键（空格切换播放，方向键逐步前进）。 -Already have older Claude Code JSONL transcripts you want to bring in? +已有较旧的 Claude Code JSONL 转录文件想要导入？ ```bash # Import everything under the default ~/.claude/projects @@ -495,42 +501,42 @@ npx @agentmemory/agentmemory import-jsonl npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl ``` -Imported sessions show up in the Replay picker alongside native ones. Under the hood each entry routes through the `mem::replay::load`, `mem::replay::sessions`, and `mem::replay::import-jsonl` iii functions — no side-channel servers. +导入的会话会与原生会话一并出现在 Replay 选择器中。底层每条记录都会经由 `mem::replay::load`、`mem::replay::sessions` 和 `mem::replay::import-jsonl` iii 函数路由——无需旁路服务器。 -> **Heads-up if you rely on `import-jsonl` as your primary capture path:** Claude Code's `cleanupPeriodDays` (in `~/.claude/settings.json`, default **30**) auto-deletes JSONL transcripts older than that window from `~/.claude/projects/`. If you install agentmemory fresh on a months-old Claude Code history, anything older than 30 days is already gone before the first import. Either run `import-jsonl` on a cron, raise `cleanupPeriodDays` to something higher, or wire the auto-capture hooks (the default plugin install path) so each turn lands in agentmemory while the session is live and the JSONL cleanup stops mattering. +> **若你依赖 `import-jsonl` 作为主要采集路径，请注意：** Claude Code 的 `cleanupPeriodDays`（位于 `~/.claude/settings.json`，默认 **30**）会自动从 `~/.claude/projects/` 删除早于该时间窗口的 JSONL 转录文件。如果你在数月前的 Claude Code 历史上全新安装 agentmemory，首次导入前，超过 30 天的内容早已不存在。可任选其一：用 cron 定期运行 `import-jsonl`、将 `cleanupPeriodDays` 调高，或接入自动采集 hooks（默认插件安装路径），让每一轮在会话进行中就写入 agentmemory，这样 JSONL 清理就不再重要。 -### Upgrade / Maintenance +### 升级 / 维护 -Use the maintenance command when you intentionally want to update your local runtime: +当你有意更新本地运行时时，使用维护命令： ```bash npx @agentmemory/agentmemory upgrade ``` -Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies and pull the pinned `iiidev/iii:0.11.2` Docker image. It never installs an unpinned or newer iii engine. +警告：该命令会修改当前工作区/运行时。它可能更新 JavaScript 依赖并拉取已固定版本的 `iiidev/iii:0.11.2` Docker 镜像。它绝不会安装未固定版本或更新的 iii 引擎。 -Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cli.ts:544-595` region). +实现细节见 `src/cli.ts`（参见 `runUpgrade` 中 `src/cli.ts:544-595` 区域附近）。 -### Claude Code (one block, paste it) +### Claude Code（单块粘贴） ```text 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, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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. ``` -#### Claude Code without the plugin install (MCP-standalone path) +#### Claude Code 不通过插件安装（MCP 独立路径） -If you wire agentmemory's MCP server through `~/.claude.json` directly instead of using `/plugin install`, Claude Code never resolves `${CLAUDE_PLUGIN_ROOT}` and you have to point hook scripts at absolute paths in `~/.claude/settings.json`. Those paths typically embed the agentmemory version (e.g. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), so the next upgrade silently breaks every hook. +若你通过 `~/.claude.json` 直接接入 agentmemory 的 MCP 服务器，而不是使用 `/plugin install`，Claude Code 永远不会解析 `${CLAUDE_PLUGIN_ROOT}`，你必须在 `~/.claude/settings.json` 中将 hook 脚本指向绝对路径。这些路径通常内嵌 agentmemory 版本（例如 `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`），因此下次升级会悄然破坏所有 hook。 -Workaround: +变通方案： ```bash agentmemory connect claude-code --with-hooks ``` -This merges the same hook commands into `~/.claude/settings.json` with absolute paths resolved to the bundled `plugin/` directory of the currently installed `@agentmemory/agentmemory` package. Re-run the command after upgrading agentmemory to refresh the paths. User entries in the same file are preserved; only previous agentmemory entries are replaced. Using the `/plugin install` path remains the recommended approach. -For remote or protected deployments, launch Claude Code with `AGENTMEMORY_URL` and `AGENTMEMORY_SECRET` set. The plugin passes both values through to its bundled MCP server; when `AGENTMEMORY_URL` is empty, the MCP shim uses `http://localhost:3111`. +这会将相同的 hook 命令合并进 `~/.claude/settings.json`，绝对路径解析为当前已安装的 `@agentmemory/agentmemory` 包内捆绑的 `plugin/` 目录。升级 agentmemory 后请重新运行该命令以刷新路径。同一文件中的用户条目会保留；仅会替换先前的 agentmemory 条目。使用 `/plugin install` 路径仍是推荐做法。 +对于远程或受保护部署，启动 Claude Code 时设置 `AGENTMEMORY_URL` 和 `AGENTMEMORY_SECRET`。插件会将这两个值透传给其捆绑的 MCP 服务器；当 `AGENTMEMORY_URL` 为空时，MCP shim 使用 `http://localhost:3111`。 -### Codex CLI (Codex plugin platform) +### Codex CLI（Codex 插件平台） ```bash # 1. start the memory server in a separate terminal @@ -541,25 +547,25 @@ codex plugin marketplace add rohitg00/agentmemory codex plugin add agentmemory@agentmemory ``` -The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers: +Codex 插件与 Claude Code 插件出自同一 `plugin/` 目录。它注册： -- `@agentmemory/mcp` as an MCP server (proxies all 53 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) -- 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` -- 8 invocable skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/commit-context`, `/commit-history`, plus 7 reference skills the agent loads on demand (MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide) +- `@agentmemory/mcp` 作为 MCP 服务器（当 `AGENTMEMORY_URL` 指向运行中的 agentmemory 服务器时，代理全部 53 个 tools；无法连接服务器时本地回退为 7 个 tools） +- 6 个生命周期 hooks：`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`PreCompact`、`Stop` +- 8 个可调用 skills：`/recall`、`/remember`、`/session-history`、`/forget`、`/recap`、`/handoff`、`/commit-context`、`/commit-history`，另有 7 个 reference skills 供 agent 按需加载（MCP tools、REST API、config、agents、hooks、architecture 以及 skill 编写指南） -Codex's hook engine injects `CLAUDE_PLUGIN_ROOT` into hook subprocesses (per [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex. +Codex 的 hook 引擎会向 hook 子进程注入 `CLAUDE_PLUGIN_ROOT`（依据 [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)),），使同一套 hook 脚本可在两个宿主上复用而无需重复。Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure 事件仅适用于 Claude Code，不会为 Codex 注册。 -#### Codex Desktop: plugin hooks currently silent (workaround available) +#### Codex Desktop：插件 hooks 当前静默（有变通方案） -`CodexHooks` and `PluginHooks` are both stable + default-enabled in [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs), but Codex Desktop builds currently do not dispatch plugin-local `hooks.json` ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). MCP tools still work; only the lifecycle observations are missing. +`CodexHooks` 与 `PluginHooks` 在 [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs), 中均为 stable 且默认启用，但 Codex Desktop 构建版目前不会分发插件本地的 `hooks.json`（[openai/codex#16430](https://github.com/openai/codex/issues/16430)).）。MCP tools 仍可用；仅缺少生命周期观测。 -Until upstream lands the fix, mirror the same hook commands into the global `~/.codex/hooks.json`: +在上游修复落地前，将相同的 hook 命令镜像到全局 `~/.codex/hooks.json`： ```bash agentmemory connect codex --with-hooks ``` -This adds an idempotent block to `~/.codex/hooks.json` referencing absolute paths to the bundled scripts (no `${CLAUDE_PLUGIN_ROOT}` expansion needed at user-scope). Re-run the same command after upgrading agentmemory to refresh paths. User entries in the same file are preserved; only previous agentmemory entries are replaced. +这会在 `~/.codex/hooks.json` 中添加一个幂等块，引用捆绑脚本的绝对路径（用户作用域无需 `${CLAUDE_PLUGIN_ROOT}` 展开）。升级 agentmemory 后请重新运行同一命令以刷新路径。同一文件中的用户条目会保留；仅会替换先前的 agentmemory 条目。 ### GitHub Copilot CLI @@ -571,10 +577,10 @@ agentmemory connect copilot-cli copilot plugin install rohitg00/agentmemory:plugin ``` -`agentmemory connect copilot-cli` merges `mcpServers.agentmemory` into `~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json` when `COPILOT_HOME` is set) and preserves existing servers. This adapter is Windows-safe even though other `connect` adapters still require manual Windows setup. Copilot picks up the MCP server on next launch or after `/mcp`. Install the plugin as well when you want the full hook/skill experience. +`agentmemory connect copilot-cli` 会将 `mcpServers.agentmemory` 合并进 `~/.copilot/mcp-config.json`（若设置了 `COPILOT_HOME` 则为 `$COPILOT_HOME/mcp-config.json`），并保留现有服务器。尽管其他 `connect` 适配器仍需要手动进行 Windows 配置，此适配器在 Windows 上是安全的。Copilot 会在下次启动时，或在执行 `/mcp` 之后识别 MCP 服务器。若需要完整的 hook/skill 体验，也请安装该插件。
-OpenClaw (paste this prompt) +OpenClaw（粘贴此提示词） ```text Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 53 memory tools: @@ -594,12 +600,12 @@ Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separa Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`. ``` -Full guide: [`integrations/openclaw/`](integrations/openclaw/) +完整指南：[`integrations/openclaw/`](integrations/openclaw/)
-Hermes Agent (paste this prompt) +Hermes Agent（粘贴此提示词） ```text Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 53 memory tools: @@ -615,17 +621,17 @@ memory: Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory. ``` -Full guide: [`integrations/hermes/`](integrations/hermes/) +完整指南：[`integrations/hermes/`](integrations/hermes/)
-### Other agents +### 其他 Agent -Start the memory server: `npx @agentmemory/agentmemory` +启动 memory 服务器：`npx @agentmemory/agentmemory` -#### Native skills via `npx skills add` (50+ agents) +#### 通过 `npx skills add` 使用原生 skills（50+ 个 Agent） -agentmemory ships 15 skills in the Claude-Code-style `/SKILL.md` format: 8 invocable action skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) and 7 reference skills the agent loads on demand (`agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). The reference skills carry data tables generated from source, so they never drift. The [`skills`](https://npmjs.com/package/skills) CLI by vercel-labs auto-installs them into the calling agent's native skill directory across 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, and more): +agentmemory 以 Claude Code 风格的 `/SKILL.md` 格式提供 15 个 skills：8 个可调用 action skills（`remember`、`recall`、`recap`、`handoff`、`forget`、`commit-context`、`commit-history`、`session-history`）以及 7 个由 Agent 按需加载的 reference skills（`agentmemory-mcp-tools`、`agentmemory-rest-api`、`agentmemory-config`、`agentmemory-agents`、`agentmemory-hooks`、`agentmemory-architecture`、`write-agentmemory-skill`）。reference skills 携带由源码生成的数据表，因此不会漂移。[`skills`](https://npmjs.com/package/skills) CLI by vercel-labs 可自动将其安装到调用方 Agent 的原生 skill 目录，支持 50+ 个 Agent（Claude Code、Cursor、Cline、Continue、Droid、Warp、Codex、Antigravity、Kiro、OpenCode、Goose、Roo、Trae、Windsurf 等）： ```bash npx skills add rohitg00/agentmemory -y # auto-detects the calling agent @@ -633,16 +639,16 @@ npx skills add rohitg00/agentmemory -y -a warp # explicit agent npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent ``` -This is **complementary** to `agentmemory connect `: +这与 `agentmemory connect ` **互为补充**： -- `agentmemory connect ` writes the MCP server config so the tools are available. -- `npx skills add rohitg00/agentmemory` installs the skills so the agent knows when to call them. +- `agentmemory connect ` 会写入 MCP 服务器配置，使工具可用。 +- `npx skills add rohitg00/agentmemory` 会安装 skills，使 Agent 知道何时调用它们。 -For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop the 15 SKILL.md files under the agent's native skill directory yourself — same format works everywhere. +对于 skills CLI 尚未覆盖的少数 Agent（Zed v1.3.x 及更低版本），请自行将 15 个 SKILL.md 文件放入该 Agent 的原生 skill 目录——相同格式在各处均适用。 -#### Standard MCP block +#### 标准 MCP 配置块 -The agentmemory entry is the **same MCP server block** across every host that uses the `mcpServers` shape (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw): +在所有采用 `mcpServers` 结构的宿主上，agentmemory 条目均为**相同的 MCP 服务器配置块**（Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI、OpenClaw）： ```json "agentmemory": { @@ -655,41 +661,41 @@ The agentmemory entry is the **same MCP server block** across every host that us } ``` -**Merge this entry into the existing `mcpServers` object** in the host's config file — don't replace the file. If the file already has other servers, add `agentmemory` next to them as another key inside `mcpServers`. If `mcpServers` is missing entirely, paste the block inside `{ "mcpServers": { ... } }`. The `${VAR}` placeholders inherit `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` from the shell at MCP-server launch — unset vars pass empty strings and the shim falls back to `http://localhost:3111`. One wired entry covers both local and remote (k8s / reverse-proxied) deployments. +**将此条目合并进宿主配置文件中的现有 `mcpServers` 对象**——不要替换整个文件。若文件已有其他服务器，请在 `mcpServers` 内将 `agentmemory` 作为另一个键添加在它们旁边。若完全缺少 `mcpServers`，请将配置块粘贴到 `{ "mcpServers": { ... } }` 内。`${VAR}` 占位符会在 MCP 服务器启动时从 shell 继承 `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`——未设置的变量会传入空字符串，shim 会回退到 `http://localhost:3111`。一条已接入的配置即可同时覆盖本地与远程（k8s / 反向代理）部署。 -| Agent | Config file | Notes | +| Agent | 配置文件 | 说明 | |---|---|---| -| **Cursor** | `~/.cursor/mcp.json` | Merge into `mcpServers`. One-click deeplink also available on the website. | -| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Merge into `mcpServers`. Restart Claude Desktop after editing. | -| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Same `mcpServers` block. | -| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Same `mcpServers` block. | -| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merges). | -| **GitHub Copilot CLI (MCP only)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` merges `mcpServers.agentmemory`; Copilot picks it up on next launch or `/mcp`. | -| **GitHub Copilot CLI (full plugin)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` for the plugin from the GitHub subdir. | -| **OpenClaw** | OpenClaw MCP config | Same `mcpServers` block, or use the deeper [memory plugin](integrations/openclaw/). | -| **Codex CLI (MCP only)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, or add `[mcp_servers.agentmemory]` manually. | -| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` then `codex plugin add agentmemory@agentmemory`. Registers MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 15 skills. On Codex Desktop, also run `agentmemory connect codex --with-hooks` until [openai/codex#16430](https://github.com/openai/codex/issues/16430) lands — plugin hooks are currently silent there. | -| **OpenCode (MCP only)** | `opencode.json` | Different shape — top-level `mcp` key, command as array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. | -| **OpenCode (full plugin)** | `plugin/opencode/` | 22 auto-capture hooks covering session lifecycle, messages, tools, errors. Two slash commands (`/recall`, `/remember`). Copy `plugin/opencode/` into your OpenCode workspace and add the plugin entry to `opencode.json`. See [`plugin/opencode/README.md`](plugin/opencode/README.md) for the full hook table + gap analysis. | -| **pi** | `~/.pi/agent/extensions/agentmemory` | Copy [`integrations/pi`](integrations/pi/) and restart pi. | -| **Hermes Agent** | `~/.hermes/config.yaml` | Use the deeper [memory provider plugin](integrations/hermes/) with `memory.provider: agentmemory`. | -| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` writes the standard `mcpServers` block. Hook payload is field-compatible with Claude Code, so the existing 12-hook scripts work without modification — wire them via the `hooks` section in the same `settings.json`. | -| **Antigravity** (replaces Gemini CLI) | `mcp_config.json` (in Antigravity's User dir) | `agentmemory connect antigravity` writes the standard `mcpServers` block. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. Use after the 2026-06-18 Gemini CLI sunset. | -| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` writes the user-level config. Workspace overrides go in `.kiro/settings/mcp.json` next to your code. | -| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` writes the standard `mcpServers` block. Warp also auto-discovers skills from `.claude/skills/` — once the Claude Code plugin is installed the 8 agentmemory skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) appear natively in Warp's slash-command palette. | -| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` writes the standard `mcpServers` block. VS Code extension users: paste the same block via Cline Settings → MCP Servers → Edit JSON. | -| **Continue.dev** | `~/.continue/config.yaml` (preferred) or `config.json` (legacy) | `agentmemory connect continue` creates `config.yaml` from scratch when neither exists, or modifies existing `config.json`. **If you already have `config.yaml`** the adapter prints the exact block to paste under `mcpServers:` — it won't silently rewrite your yaml because preserving comments and anchors safely needs a YAML parser the package doesn't ship. Continue uses array form (not object) for `mcpServers`. | -| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` writes under `context_servers` (Zed's key, NOT `mcpServers`). Remote MCP servers can be wired via `{"url": "..."}` instead. | -| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` writes the standard `mcpServers` block. Project-scoped overrides go in `/.factory/mcp.json`. The `/mcp` slash command inside droid lists configured servers. | -| **Goose** | Goose MCP settings UI | Same `mcpServers` block — use `goose configure` → Add Extension → MCP. Direct YAML edit at `~/.config/goose/config.yaml` is supported but the schema uses `extensions:` + `cmd` (not `mcpServers:` + `command`). | -| **Aider** | n/a | Talk to the REST API directly: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. | -| **Any agent (32+)** | n/a | `npx skillkit install agentmemory` auto-detects the host and merges. | +| **Cursor** | `~/.cursor/mcp.json` | 合并进 `mcpServers`。网站也提供一键 deeplink。 | +| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | 合并进 `mcpServers`。编辑后请重启 Claude Desktop。 | +| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | 相同的 `mcpServers` 配置块。 | +| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | 相同的 `mcpServers` 配置块。 | +| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user`（自动合并）。 | +| **GitHub Copilot CLI (MCP only)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` 会合并 `mcpServers.agentmemory`；Copilot 会在下次启动时或执行 `/mcp` 后识别。 | +| **GitHub Copilot CLI (full plugin)** | Copilot plugin install | 从 GitHub 子目录使用 `copilot plugin install rohitg00/agentmemory:plugin` 安装插件。 | +| **OpenClaw** | OpenClaw MCP config | 相同的 `mcpServers` 配置块，或使用更完整的 [memory plugin](integrations/openclaw/)。 | +| **Codex CLI (MCP only)** | `.codex/config.toml` | TOML 结构：`codex mcp add agentmemory -- npx -y @agentmemory/mcp`，或手动添加 `[mcp_servers.agentmemory]`。 | +| **Codex CLI (full plugin)** | Codex plugin marketplace | 先执行 `codex plugin marketplace add rohitg00/agentmemory`，再执行 `codex plugin add agentmemory@agentmemory`。会注册 MCP + 6 个生命周期 hooks（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop）+ 15 个 skills。在 Codex Desktop 上，还需运行 `agentmemory connect codex --with-hooks`，直至 [openai/codex#16430](https://github.com/openai/codex/issues/16430) 落地——目前插件 hooks 在该环境中是静默的。 | +| **OpenCode (MCP only)** | `opencode.json` | 结构不同——顶层 `mcp` 键，command 为数组：`{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`。 | +| **OpenCode (full plugin)** | `plugin/opencode/` | 22 个自动捕获 hooks，覆盖会话生命周期、消息、工具与错误。两个斜杠命令（`/recall`、`/remember`）。将 `plugin/opencode/` 复制到你的 OpenCode 工作区，并在 `opencode.json` 中添加插件条目。完整 hook 表与缺口分析见 [`plugin/opencode/README.md`](plugin/opencode/README.md)。 | +| **pi** | `~/.pi/agent/extensions/agentmemory` | 复制 [`integrations/pi`](integrations/pi/) 并重启 pi。 | +| **Hermes Agent** | `~/.hermes/config.yaml` | 配合 `memory.provider: agentmemory` 使用更完整的 [memory provider plugin](integrations/hermes/)。 | +| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` 会写入标准 `mcpServers` 配置块。Hook 载荷与 Claude Code 字段兼容，因此现有 12 个 hook 脚本无需修改即可工作——在同一 `settings.json` 的 `hooks` 节中接入即可。 | +| **Antigravity**（取代 Gemini CLI） | `mcp_config.json`（位于 Antigravity 的 User 目录） | `agentmemory connect antigravity` 会写入标准 `mcpServers` 配置块。macOS：`~/Library/Application Support/Antigravity/User/`。Linux：`~/.config/Antigravity/User/`。请在 2026-06-18 Gemini CLI 停服后使用。 | +| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` 会写入用户级配置。工作区覆盖配置放在代码旁的 `.kiro/settings/mcp.json`。 | +| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` 会写入标准 `mcpServers` 配置块。Warp 还会从 `.claude/skills/` 自动发现 skills——安装 Claude Code 插件后，8 个 agentmemory skills（`remember`、`recall`、`recap`、`handoff`、`forget`、`commit-context`、`commit-history`、`session-history`）会原生出现在 Warp 的斜杠命令面板中。 | +| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` 会写入标准 `mcpServers` 配置块。VS Code 扩展用户：通过 Cline Settings → MCP Servers → Edit JSON 粘贴相同配置块。 | +| **Continue.dev** | `~/.continue/config.yaml`（推荐）或 `config.json`（旧版） | `agentmemory connect continue` 会在两者都不存在时从零创建 `config.yaml`，或修改现有的 `config.json`。**若你已有 `config.yaml`**，适配器会打印需粘贴到 `mcpServers:` 下的精确配置块——它不会静默重写你的 yaml，因为安全保留注释与锚点需要本包未附带的 YAML 解析器。Continue 对 `mcpServers` 使用数组形式（而非对象）。 | +| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` 会写入 `context_servers` 下（Zed 的键，不是 `mcpServers`）。远程 MCP 服务器也可通过 `{"url": "..."}` 接入。 | +| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` 会写入标准 `mcpServers` 配置块。项目级覆盖配置放在 `/.factory/mcp.json`。droid 内的 `/mcp` 斜杠命令会列出已配置的服务器。 | +| **Goose** | Goose MCP settings UI | 相同的 `mcpServers` 配置块——使用 `goose configure` → Add Extension → MCP。也支持在 `~/.config/goose/config.yaml` 直接编辑 YAML，但其 schema 使用 `extensions:` + `cmd`（而非 `mcpServers:` + `command`）。 | +| **Aider** | n/a | 直接调用 REST API：`curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 | +| **Any agent (32+)** | n/a | `npx skillkit install agentmemory` 会自动检测宿主并合并。 | -**Sandboxed MCP clients** (Flatpak / Snap / restrictive containers) that can't reach the host's `localhost`: also set `"AGENTMEMORY_FORCE_PROXY": "1"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP). +**沙箱化 MCP 客户端**（Flatpak / Snap / 受限容器）无法访问宿主机的 `localhost` 时：请同时在 `env` 块中设置 `"AGENTMEMORY_FORCE_PROXY": "1"`，并将 `AGENTMEMORY_URL` 指向沙箱实际可访问的路由（例如你的局域网 IP）。 -### Programmatic access (Python / Rust / Node) +### 编程式访问（Python / Rust / Node） -agentmemory registers its core operations as iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Any language with an iii SDK can call them directly over `ws://localhost:49134` — no separate REST client per language. +agentmemory 将其核心操作注册为 iii 函数（`mem::remember`、`mem::observe`、`mem::context`、`mem::smart-search`、`mem::forget`）。任何具备 iii SDK 的语言都可通过 `ws://localhost:49134` 直接调用它们——无需为每种语言单独编写 REST 客户端。 ```bash pip install iii-sdk # Python @@ -709,32 +715,32 @@ iii.trigger({ }) ``` -Worked example: [`examples/python/`](examples/python/) (quickstart + observation/recall flow). REST on `:3111` remains available for hosts without an iii runtime. +完整示例：[`examples/python/`](examples/python/)（快速入门 + observation/recall 流程）。对于没有 iii 运行时的主机，`:3111` 上的 REST 仍然可用。 -### From source +### 从源码安装 ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` -This starts agentmemory with a local `iii-engine` if `iii` is already installed, or falls back to Docker Compose if Docker is available. REST, streams, and the viewer bind to `127.0.0.1` by default. +若已安装 `iii`，将使用本地的 `iii-engine` 启动 agentmemory；否则在 Docker 可用时回退到 Docker Compose。REST、streams 与 viewer 默认绑定到 `127.0.0.1`。 -Install `iii-engine` manually. **agentmemory currently pins `iii-engine` to `v0.11.2`** — `v0.11.6` introduces a new sandbox-everything-via-`iii worker add` model that agentmemory hasn't been refactored for yet. Pin lifts once the refactor lands. Override with `AGENTMEMORY_III_VERSION=` if you've migrated to the sandbox model manually. +请手动安装 `iii-engine`。**agentmemory 目前将 `iii-engine` 固定为 `v0.11.2`**——`v0.11.6` 引入了全新的「一切经 `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:** swap `aarch64-apple-darwin` for `x86_64-apple-darwin` -- **Linux x64:** swap for `x86_64-unknown-linux-gnu` -- **Linux arm64:** swap for `aarch64-unknown-linux-gnu` -- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` from [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), extract `iii.exe`, add to PATH +- **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 -Or use Docker (the bundled `docker-compose.yml` pulls `iiidev/iii:0.11.2`). Full docs: [iii.dev/docs](https://iii.dev/docs). +也可使用 Docker（附带的 `docker-compose.yml` 会拉取 `iiidev/iii:0.11.2`）。完整文档：[iii.dev/docs](https://iii.dev/docs). ### Windows -agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough — you also need the `iii-engine` runtime (a separate native binary) as a background process. The official upstream installer is a `sh` script and there is no PowerShell installer or scoop/winget package today, so Windows users have two paths: +agentmemory 可在 Windows 10/11 上运行，但仅有 Node.js 包不够——你还需要将 `iii-engine` 运行时（独立的原生二进制）作为后台进程运行。官方上游安装器是 `sh` 脚本，目前没有 PowerShell 安装器，也没有 scoop/winget 包，因此 Windows 用户有两条路径： -**Option A — Prebuilt Windows binary (recommended):** +**选项 A — 预构建 Windows 二进制（推荐）：** ```powershell # 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser @@ -753,7 +759,7 @@ iii --version npx -y @agentmemory/agentmemory ``` -**Option B — Docker Desktop:** +**选项 B — Docker Desktop：** ```powershell # 1. Install Docker Desktop for Windows @@ -762,7 +768,7 @@ npx -y @agentmemory/agentmemory npx -y @agentmemory/agentmemory ``` -**Option C — standalone MCP only (no engine):** if you only need the MCP tools for your agent and don't need the REST API, viewer, or cron jobs, skip the engine entirely: +**选项 C — 仅独立 MCP（无引擎）：** 若你只需要供 agent 使用的 MCP 工具，而不需要 REST API、viewer 或 cron 任务，可完全跳过引擎： ```powershell npx -y @agentmemory/agentmemory mcp @@ -770,60 +776,60 @@ npx -y @agentmemory/agentmemory mcp npx -y @agentmemory/mcp ``` -**Diagnostics for Windows:** if `npx @agentmemory/agentmemory` fails, re-run with `--verbose` to see the actual engine stderr. Common failure modes: +**Windows 诊断：** 若 `npx @agentmemory/agentmemory` 失败，请用 `--verbose` 重新运行以查看引擎的实际 stderr。常见失败模式： -| Symptom | Fix | +| 现象 | 处理 | |---|---| -| `iii-engine process started` then `did not become ready within 15s` | Engine crashed on startup — re-run with `--verbose`, check stderr | -| `Could not start iii-engine` | Neither `iii.exe` nor Docker is installed. See Option A or B above | -| Port conflict | `netstat -ano \| findstr :3111` to see what's bound, then kill it or use `--port ` | -| Docker fallback skipped even though Docker is installed | Make sure Docker Desktop is actually running (system tray icon) | +| `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 ` | +| 已安装 Docker 但仍跳过 Docker 回退 | 确认 Docker Desktop 实际已在运行（系统托盘图标） | -> Note: the iii **engine** is a prebuilt binary, not a cargo crate — don't try to `cargo install` it. (The iii **SDKs** are published on crates.io, npm, and PyPI, but agentmemory doesn't need them.) Supported engine install methods, all pinned to v0.11.2: the prebuilt v0.11.2 binary above, the upstream sh install script **with the version pin** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux), and the Docker image `iiidev/iii:0.11.2`. A bare `install.sh | sh` installs the **latest** engine, which agentmemory does not support — always pass `VERSION=0.11.2`. Easiest of all: just run `npx @agentmemory/agentmemory`, which fetches the pinned engine into `~/.agentmemory/bin` for you. +> 注意：iii **engine** 是预构建二进制，不是 cargo crate——不要尝试用 `cargo install` 安装它。（iii **SDK** 发布在 crates.io、npm 和 PyPI 上，但 agentmemory 不需要它们。）受支持的引擎安装方式均固定为 v0.11.2：上文的预构建 v0.11.2 二进制、带版本固定的上游 sh 安装脚本 `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh`（macOS/Linux），以及 Docker 镜像 `iiidev/iii:0.11.2`。裸运行 `install.sh | sh` 会安装**最新**引擎，而 agentmemory 不支持该版本——务必传入 `VERSION=0.11.2`。最简单的方式：直接运行 `npx @agentmemory/agentmemory`，它会将固定版本的引擎拉取到 `~/.agentmemory/bin`。 --- -

Deploy

+

部署

-One-click templates for managed hosts. Each one ships a self-contained -Dockerfile that pulls `@agentmemory/agentmemory` from npm and copies -the iii engine binary in from the official `iiidev/iii` Docker Hub -image — no pre-built agentmemory image required. Persistent storage -mounts at `/data`; the first-boot entrypoint overwrites the -npm-bundled iii config (which binds `127.0.0.1`) with a deploy-tuned -one that binds `0.0.0.0` and uses absolute `/data` paths, generates -the HMAC secret, then drops privileges from `root` to `node` via -`gosu` before exec'ing the agentmemory CLI. +面向托管平台的一键模板。每个模板都自带独立 +Dockerfile：从 npm 拉取 `@agentmemory/agentmemory`，并从官方 +`iiidev/iii` Docker Hub 镜像复制 iii 引擎二进制—— +无需预构建的 agentmemory 镜像。持久化存储 +挂载在 `/data`；首次启动的 entrypoint 会覆盖 +npm 附带的 iii 配置（其绑定 `127.0.0.1`），改为部署优化的 +配置：绑定 `0.0.0.0` 并使用绝对 `/data` 路径，生成 +HMAC 密钥，然后通过 `gosu` 将权限从 `root` 降到 `node`， +再 exec agentmemory CLI。

Deploy to fly.io Deploy to Railway

-Render's one-click deploy button requires `render.yaml` at the repository root, which we deliberately keep clean. Use the Render Blueprint flow documented in [`deploy/render/`](./deploy/render/README.md) to point at the in-repo blueprint manually. +Render 的一键部署按钮要求仓库根目录存在 `render.yaml`，而我们有意保持根目录整洁。请按 [`deploy/render/`](./deploy/render/README.md) 中记录的 Render Blueprint 流程，手动指向仓库内的 blueprint。 -Full setup details (HMAC capture, viewer SSH tunnel, rotation, backup, -cost floors) live in [`deploy/`](./deploy/README.md): +完整设置说明（HMAC 捕获、viewer SSH 隧道、轮换、备份、 +成本下限）见 [`deploy/`](./deploy/README.md)： -- [`deploy/fly`](./deploy/fly/README.md) — single machine with - `auto_stop_machines = "stop"`; cheapest idle. -- [`deploy/railway`](./deploy/railway/README.md) — Hobby plan flat fee, - volume in the dashboard. -- [`deploy/render`](./deploy/render/README.md) — Blueprint flow, - automatic disk snapshots on paid plans. -- [`deploy/coolify`](./deploy/coolify/README.md) — self-hosted on your - own VPS via [Coolify](https://coolify.io/self-hosted); same Docker - Compose stack, you own the host and the data. +- [`deploy/fly`](./deploy/fly/README.md) — 单机部署，使用 + `auto_stop_machines = "stop"`；空闲时最便宜。 +- [`deploy/railway`](./deploy/railway/README.md) — Hobby 套餐固定费用， + 在控制台配置 volume。 +- [`deploy/render`](./deploy/render/README.md) — Blueprint 流程， + 付费计划自动磁盘快照。 +- [`deploy/coolify`](./deploy/coolify/README.md) — 通过 [Coolify](https://coolify.io/self-hosted); 在自有 + VPS 上自托管；同一套 Docker + Compose 栈，主机与数据归你所有。 -Only port `3111` is published. The viewer on `3113` stays bound to -loopback inside the container — every template's README documents the -SSH-tunnel pattern for reaching it. +仅发布端口 `3111`。viewer 在 `3113` 上仍绑定到 +容器内 loopback——每个模板的 README 都记录了通过 +SSH 隧道访问它的方式。 ---

Why agentmemory

-Every coding agent forgets everything when the session ends. You waste the first 5 minutes of every session re-explaining your stack. agentmemory runs in the background and eliminates that entirely. +每个编程 agent 在会话结束时都会忘记一切。你浪费每个会话开头 5 分钟重新解释技术栈。agentmemory 在后台运行，彻底消除这一问题。 ```text Session 1: "Add auth to the API" @@ -839,24 +845,24 @@ Session 2: "Now add rate limiting" Zero re-explaining. Starts working immediately. ``` -### vs built-in agent memory +### 与内置 agent 记忆对比 -Every AI coding agent ships with built-in memory — Claude Code has `MEMORY.md`, Cursor has notepads, Cline has memory bank. These work like sticky notes. agentmemory is the searchable database behind the sticky notes. +每个 AI 编程 agent 都自带内置记忆 — Claude Code 有 `MEMORY.md`，Cursor 有 notepads，Cline 有 memory bank。它们就像便利贴。agentmemory 则是这些便利贴背后的可搜索数据库。 -| | Built-in (CLAUDE.md) | agentmemory | +| | 内置 (CLAUDE.md) | agentmemory | |---|---|---| -| Scale | 200-line cap | Unlimited | -| Search | Loads everything into context | BM25 + vector + graph (top-K only) | -| Token cost | 22K+ at 240 observations | ~1,900 tokens (92% less) | -| Cross-agent | Per-agent files | MCP + REST (any agent) | -| Coordination | None | Leases, signals, actions, routines | -| Observability | Read files manually | Real-time viewer on :3113 | +| 规模 | 200 行上限 | 无限制 | +| 搜索 | 将全部内容载入上下文 | BM25 + vector + graph（仅 top-K） | +| Token 成本 | 240 条观察记录时 22K+ | 约 1,900 tokens（减少 92%） | +| 跨 agent | 各 agent 独立文件 | MCP + REST（任意 agent） | +| 协调 | 无 | Leases、signals、actions、routines | +| 可观测性 | 手动读取文件 | :3113 上的实时查看器 | ---

How It Works

-### Memory Pipeline +### 记忆流水线 ```text PostToolUse hook fires @@ -879,178 +885,180 @@ SessionStart hook fires -> Inject into conversation ``` -### 4-Tier Memory Consolidation +### 四层记忆巩固 -Inspired by how human brains process memory — not unlike sleep consolidation. +灵感来自人脑处理记忆的方式 — 与睡眠巩固（sleep consolidation）不无相似。 -| Tier | What | Analogy | -|------|------|---------| -| **Working** | Raw observations from tool use | Short-term memory | -| **Episodic** | Compressed session summaries | "What happened" | -| **Semantic** | Extracted facts and patterns | "What I know" | -| **Procedural** | Workflows and decision patterns | "How to do it" | +| 层级 | 内容 | 类比 | +|------|------|------| +| **Working** | 工具使用产生的原始观察记录 | 短期记忆 | +| **Episodic** | 压缩后的会话摘要 | "发生了什么" | +| **Semantic** | 提取的事实与模式 | "我知道什么" | +| **Procedural** | 工作流与决策模式 | "如何做" | -Memories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Contradictions are detected and resolved. +记忆会随时间衰减（艾宾浩斯曲线，Ebbinghaus curve）。频繁访问的记忆会加强。陈旧记忆会自动淘汰。矛盾会被检测并解决。 -### What Gets Captured +### 捕获内容 -| Hook | Captures | +| Hook | 捕获内容 | |------|----------| -| `SessionStart` | Project path, session ID | -| `UserPromptSubmit` | User prompts (privacy-filtered) | -| `PreToolUse` | File access patterns + enriched context | -| `PostToolUse` | Tool name, input, output | -| `PostToolUseFailure` | Error context | -| `PreCompact` | Re-injects memory before compaction | -| `SubagentStart/Stop` | Sub-agent lifecycle | -| `Stop` | End-of-session summary | -| `SessionEnd` | Session complete marker | +| `SessionStart` | 项目路径、会话 ID | +| `UserPromptSubmit` | 用户提示词（经隐私过滤） | +| `PreToolUse` | 文件访问模式 + 增强上下文 | +| `PostToolUse` | 工具名称、输入、输出 | +| `PostToolUseFailure` | 错误上下文 | +| `PreCompact` | 压缩前重新注入记忆 | +| `SubagentStart/Stop` | 子 agent 生命周期 | +| `Stop` | 会话结束摘要 | +| `SessionEnd` | 会话完成标记 | -### Key Capabilities +### 核心能力 -| Capability | Description | +| 能力 | 说明 | |---|---| -| **Automatic capture** | Every tool use recorded via hooks — zero manual effort | -| **Semantic search** | BM25 + vector + knowledge graph with RRF fusion | -| **Memory evolution** | Versioning, supersession, relationship graphs | -| **Auto-forgetting** | TTL expiry, contradiction detection, importance eviction | -| **Privacy first** | API keys, secrets, `` tags stripped before storage | -| **Self-healing** | Circuit breaker, provider fallback chain, health monitoring | -| **Claude bridge** | Bi-directional sync with MEMORY.md | -| **Knowledge graph** | Entity extraction + BFS traversal | -| **Team memory** | Namespaced shared + private across team members | -| **Citation provenance** | Trace any memory back to source observations | -| **Git snapshots** | Version, rollback, and diff memory state | +| **自动捕获** | 通过 hooks 记录每次工具使用 — 零手动操作 | +| **语义搜索** | BM25 + vector + 知识图谱，经 RRF 融合 | +| **记忆演化** | 版本管理、替代关系、关系图谱 | +| **自动遗忘** | TTL 过期、矛盾检测、重要性淘汰 | +| **隐私优先** | API 密钥、机密信息、`` 标签在存储前剥离 | +| **自愈** | 熔断器、提供商回退链、健康监控 | +| **Claude 桥接** | 与 MEMORY.md 双向同步 | +| **知识图谱** | 实体提取 + BFS 遍历 | +| **团队记忆** | 跨团队成员的命名空间共享 + 私有记忆 | +| **引用溯源** | 将任意记忆追溯至源观察记录 | +| **Git 快照** | 版本化、回滚并 diff 记忆状态 | --- -Triple-stream retrieval combining three signals: +三路检索融合三种信号： -| Stream | What it does | When | +| 流 | 作用 | 时机 | |---|---|---| -| **BM25** | Stemmed keyword matching with synonym expansion | Always on | -| **Vector** | Cosine similarity over dense embeddings | Embedding provider configured | -| **Graph** | Knowledge graph traversal via entity matching | Entities detected in query | +| **BM25** | 词干化关键词匹配 + 同义词扩展 | 始终开启 | +| **Vector** | 稠密嵌入的余弦相似度 | 已配置嵌入提供商时 | +| **Graph** | 通过实体匹配进行知识图谱遍历 | 查询中检测到实体时 | -Fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session). +经倒数排名融合（Reciprocal Rank Fusion，RRF，k=60）融合，并按会话去重（每个会话最多 3 条结果）。 -BM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese / Japanese / Korean memories, install the optional segmenters (`npm install @node-rs/jieba tiny-segmenter`) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr. +BM25 开箱即支持希腊文、西里尔文、希伯来文、阿拉伯文及带重音符号的拉丁文分词。对于中文 / 日文 / 韩文记忆，请安装可选分词器（`npm install @node-rs/jieba tiny-segmenter`），将 CJK 连续文本切分为词级 token；未安装时，agentmemory 会软回退为整段分词，并在 stderr 打印一次性提示。 -### Embedding providers +### 嵌入提供商 -agentmemory auto-detects your provider. For best results, install local embeddings (free): +agentmemory 会自动检测你的提供商。为获得最佳效果，请安装本地嵌入（免费）： ```bash npm install @xenova/transformers ``` -| Provider | Model | Cost | Notes | +| 提供商 | 模型 | 成本 | 说明 | |---|---|---|---| -| **Local (recommended)** | `all-MiniLM-L6-v2` | Free | Offline, +8pp recall over BM25-only | -| Gemini | `gemini-embedding-001` | Free tier | 100+ languages, 768/1536/3072 dims (MRL), 2048-token input. Replaces `text-embedding-004` ([deprecated, shutdown Jan 14, 2026](https://ai.google.dev/gemini-api/docs/deprecations)) | -| OpenAI | `text-embedding-3-small` | $0.02/1M | Highest quality | -| Voyage AI | `voyage-code-3` | Paid | Optimized for code | -| Cohere | `embed-english-v3.0` | Free trial | General purpose | -| OpenRouter | Any model | Varies | Multi-model proxy | +| **Local（推荐）** | `all-MiniLM-L6-v2` | 免费 | 离线，相比仅 BM25 召回率 +8pp | +| Gemini | `gemini-embedding-001` | 免费套餐 | 100+ 语言，768/1536/3072 维（MRL），2048-token 输入。替代 `text-embedding-004`（[已弃用，2026 年 1 月 14 日关停](https://ai.google.dev/gemini-api/docs/deprecations)) | +| OpenAI | `text-embedding-3-small` | $0.02/1M | 质量最高 | +| Voyage AI | `voyage-code-3` | 付费 | 针对代码优化 | +| Cohere | `embed-english-v3.0` | 免费试用 | 通用场景 | +| OpenRouter | Any model | 不定 | 多模型代理 | ---

MCP Server

-53 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent. +53 个工具、6 个资源、3 个提示词和 15 个 skills，面向任意 agent 的最全面 MCP 记忆工具包。 -> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 53-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag — setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. +> **MCP shim 与完整服务器：** 已发布的 `@agentmemory/mcp` 包是一个轻量 shim。仅当它能通过 `AGENTMEMORY_URL` 连接到运行中的 agentmemory 服务器时（代理模式），才会暴露完整的 53 工具界面。若无法连接服务器，shim 会回退到 7 工具的本地集合（`memory_save`、`memory_recall`、`memory_smart_search`、`memory_sessions`、`memory_export`、`memory_audit`、`memory_governance_delete`）。`AGENTMEMORY_TOOLS=core|all` 环境变量是*服务端*标志 — 在 shim 的 `env` 块中设置它无效。若在 Cursor / OpenCode / Gemini CLI 中只看到 7 个工具，请启动 `npx @agentmemory/agentmemory`（或 Docker 栈），并设置 `AGENTMEMORY_URL=http://localhost:3111`。 -### 53 Tools +### 53 个工具
-Core tools (always available) +核心工具（始终可用） -| Tool | Description | -|------|-------------| -| `memory_recall` | Search past observations | -| `memory_compress_file` | Compress markdown files while preserving structure | -| `memory_save` | Save an insight, decision, or pattern | -| `memory_patterns` | Detect recurring patterns | -| `memory_smart_search` | Hybrid semantic + keyword search | -| `memory_file_history` | Past observations about specific files | -| `memory_sessions` | List recent sessions | -| `memory_timeline` | Chronological observations | -| `memory_profile` | Project profile (concepts, files, patterns) | -| `memory_export` | Export all memory data | -| `memory_relations` | Query relationship graph | +| 工具 | 说明 | +|------|------| +| `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` | 查询关系图谱 |
-Extended tools (53 total — set AGENTMEMORY_TOOLS=all) +扩展工具（共 53 个 — 设置 AGENTMEMORY_TOOLS=all） -| Tool | Description | -|------|-------------| -| `memory_patterns` | Detect recurring patterns | -| `memory_timeline` | Chronological observations | -| `memory_relations` | Query relationship graph | -| `memory_graph_query` | Knowledge graph traversal | -| `memory_consolidate` | Run 4-tier consolidation | -| `memory_claude_bridge_sync` | Sync with MEMORY.md | -| `memory_team_share` | Share with team members | -| `memory_team_feed` | Recent shared items | -| `memory_audit` | Audit trail of operations | -| `memory_governance_delete` | Delete with audit trail | -| `memory_snapshot_create` | Git-versioned snapshot | -| `memory_action_create` | Create work items with dependencies | -| `memory_action_update` | Update action status | -| `memory_frontier` | Unblocked actions ranked by priority | -| `memory_next` | Single most important next action | -| `memory_lease` | Exclusive action leases (multi-agent) | -| `memory_routine_run` | Instantiate workflow routines | -| `memory_signal_send` | Inter-agent messaging | -| `memory_signal_read` | Read messages with receipts | -| `memory_checkpoint` | External condition gates | -| `memory_mesh_sync` | P2P sync between instances | -| `memory_sentinel_create` | Event-driven watchers | -| `memory_sentinel_trigger` | Fire sentinels externally | -| `memory_sketch_create` | Ephemeral action graphs | -| `memory_sketch_promote` | Promote to permanent | -| `memory_crystallize` | Compact action chains | -| `memory_diagnose` | Health checks | -| `memory_heal` | Auto-fix stuck state | -| `memory_facet_tag` | Dimension:value tags | -| `memory_facet_query` | Query by facet tags | -| `memory_verify` | Trace provenance | +| 工具 | 说明 | +|------|------| +| `memory_patterns` | 检测重复出现的模式 | +| `memory_timeline` | 按时间顺序的观察记录 | +| `memory_relations` | 查询关系图谱 | +| `memory_graph_query` | 知识图谱遍历 | +| `memory_consolidate` | 运行四层巩固 | +| `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` | 更新 action 状态 | +| `memory_frontier` | 按优先级排序的已解除阻塞 actions | +| `memory_next` | 单一最重要的下一步 action | +| `memory_lease` | 独占 action 租约（多 agent） | +| `memory_routine_run` | 实例化工作流 routines | +| `memory_signal_send` | agent 间消息传递 | +| `memory_signal_read` | 带回执的消息读取 | +| `memory_checkpoint` | 外部条件门控 | +| `memory_mesh_sync` | 实例间 P2P 同步 | +| `memory_sentinel_create` | 事件驱动 watchers | +| `memory_sentinel_trigger` | 外部触发 sentinels | +| `memory_sketch_create` | 临时 action 图 | +| `memory_sketch_promote` | 提升为永久 | +| `memory_crystallize` | 压缩 action 链 | +| `memory_diagnose` | 健康检查 | +| `memory_heal` | 自动修复卡住状态 | +| `memory_facet_tag` | dimension:value 标签 | +| `memory_facet_query` | 按 facet 标签查询 | +| `memory_verify` | 追溯溯源 |
-### 6 Resources · 3 Prompts · 4 Skills + -| Type | Name | Description | -|------|------|-------------| -| Resource | `agentmemory://status` | Health, session count, memory count | -| Resource | `agentmemory://project/{name}/profile` | Per-project intelligence | -| Resource | `agentmemory://memories/latest` | Latest 10 active memories | -| Resource | `agentmemory://graph/stats` | Knowledge graph statistics | -| Prompt | `recall_context` | Search + return context messages | -| Prompt | `session_handoff` | Handoff data between agents | -| Prompt | `detect_patterns` | Analyze recurring patterns | -| Skill | `/recall` | Search memory | -| Skill | `/remember` | Save to long-term memory | -| Skill | `/session-history` | Recent session summaries | -| Skill | `/forget` | Delete observations/sessions | +### 6 个资源 · 3 个 Prompt · 4 个 Skill -### Standalone MCP +| 类型 | 名称 | 描述 | +|------|------|------| +| Resource | `agentmemory://status` | 健康状态、会话数量、记忆数量 | +| Resource | `agentmemory://project/{name}/profile` | 按项目的智能信息 | +| Resource | `agentmemory://memories/latest` | 最近 10 条活跃记忆 | +| Resource | `agentmemory://graph/stats` | 知识图谱统计 | +| Prompt | `recall_context` | 搜索并返回上下文消息 | +| Prompt | `session_handoff` | 在 Agent 之间传递数据 | +| Prompt | `detect_patterns` | 分析重复出现的模式 | +| Skill | `/recall` | 搜索记忆 | +| Skill | `/remember` | 保存到长期记忆 | +| Skill | `/session-history` | 最近会话摘要 | +| Skill | `/forget` | 删除观察记录/会话 | -Run without the full server — for any MCP client. Either of these works: +### 独立 MCP + +无需完整服务器即可运行 — 适用于任意 MCP 客户端。以下两种方式均可： ```bash npx -y @agentmemory/agentmemory mcp # canonical (always available) npx -y @agentmemory/mcp # shim package alias ``` -Or add to your agent's MCP config: +或添加到你的 Agent 的 MCP 配置中： -Most agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI): +大多数 Agent（Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI）： ```json { "mcpServers": { @@ -1065,9 +1073,9 @@ Most agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI): } ``` -Merge the `agentmemory` entry into your host's existing `mcpServers` object rather than replacing the file. For sandboxed clients that can't reach the host's `localhost`, add `"AGENTMEMORY_FORCE_PROXY": "1"` to the env block and set `AGENTMEMORY_URL` to a route the sandbox can reach. +将 `agentmemory` 条目合并到宿主现有的 `mcpServers` 对象中，而不是替换整个文件。对于无法访问宿主 `localhost` 的沙箱客户端，在 env 块中添加 `"AGENTMEMORY_FORCE_PROXY": "1"`，并将 `AGENTMEMORY_URL` 设置为沙箱可访问的路由。 -OpenCode (`opencode.json`): +OpenCode（`opencode.json`）： ```json { "mcp": { @@ -1081,7 +1089,7 @@ OpenCode (`opencode.json`): } ``` -Copy the plugin file from the repo: +从仓库复制插件文件： ```bash mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ @@ -1092,33 +1100,33 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/

Real-Time Viewer

-Auto-starts on port `3113`. Live observation stream, session explorer, memory browser, knowledge graph visualization, and health dashboard. +在端口 `3113` 上自动启动。提供实时观察流、会话浏览器、记忆浏览器、知识图谱可视化和健康仪表盘。 ```bash open http://localhost:3113 ``` -The viewer server binds to `127.0.0.1` by default. The REST-served `/agentmemory/viewer` endpoint follows the normal `AGENTMEMORY_SECRET` bearer-token rules. CSP headers use a per-response script nonce and disable inline handler attributes (`script-src-attr 'none'`). +查看器服务器默认绑定到 `127.0.0.1`。REST 提供的 `/agentmemory/viewer` 端点遵循常规的 `AGENTMEMORY_SECRET` Bearer 令牌规则。CSP 头使用每次响应生成的脚本 nonce，并禁用内联处理程序属性（`script-src-attr 'none'`）。 ---

iii Console

-The viewer at `:3113` shows what your agent **remembered**. The [iii console](https://iii.dev/docs/console) shows what your agent **did** — every memory op as an OpenTelemetry trace, every KV entry editable, every function invocable, every stream tappable. Two windows on the same memory: one product-shaped, one engine-shaped. +`:3113` 上的查看器展示你的 Agent **记住了什么**。[iii console](https://iii.dev/docs/console) 展示你的 Agent **做了什么** — 每次记忆操作都是一条 OpenTelemetry 追踪，每个 KV 条目可编辑，每个函数可调用，每个流可点击。同一套记忆的两种视图：一种面向产品，一种面向引擎。 -Watch a `memory_smart_search` fire and see the BM25 scan → embedding lookup → RRF fusion → reranker as a waterfall. Edit a stuck consolidation timer in the KV browser. Replay a `PostToolUse` hook with a tweaked payload. Pin the WebSocket stream and watch observations land live. +观察 `memory_smart_search` 触发，以瀑布图形式查看 BM25 扫描 → 嵌入查找 → RRF 融合 → 重排序器。在 KV 浏览器中编辑卡住的合并定时器。用调整后的载荷重放 `PostToolUse` 钩子。固定 WebSocket 流，实时观看观察记录落地。 -agentmemory ships this for free because every function call and trigger fires through iii — nothing custom, nothing to instrument. +agentmemory 免费提供此功能，因为每次函数调用和触发都通过 iii 执行 — 无需自定义，也无需额外插桩。

iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata
- Workers page: every connected worker — including agentmemory itself — with PID, function count, runtime, and last-seen. + Workers 页面：每个已连接的 worker — 包括 agentmemory 自身 — 显示 PID、函数数量、运行时信息和最后活跃时间。

-**Already installed.** The console ships with `iii` — no separate installer. +**已预装。** 控制台随 `iii` 一并提供 — 无需单独安装。 -**Launch alongside agentmemory:** +**与 agentmemory 一同启动：** ```bash # agentmemory viewer holds port 3113, so run the console on 3114. @@ -1126,9 +1134,9 @@ agentmemory ships this for free because every function call and trigger fires th iii console --port 3114 ``` -Then open `http://localhost:3114`. Add `--enable-flow` for the experimental architecture-graph page. +然后打开 `http://localhost:3114`。添加 `--enable-flow` 以启用实验性的架构图页面。 -Override engine endpoints only if you've moved them: +仅在你已迁移引擎端点时才需要覆盖： ```bash iii console --port 3114 \ @@ -1137,44 +1145,44 @@ iii console --port 3114 \ --bridge-port 49134 ``` -**What you can do from the console:** +**控制台可执行的操作：** -| Page | Use it to | -|------|-----------| -| **Workers** | See every connected worker and its live metrics — including the agentmemory worker itself. | -| **Functions** | Invoke any of agentmemory's functions directly with a JSON payload — handy for testing `memory.recall`, `memory.consolidate`, `graph.query` without wiring a client. | -| **Triggers** | Replay HTTP, cron, event, and state triggers — fire the consolidation cron manually, retry an HTTP route, emit a state change. | -| **States** | KV browser with full CRUD — sessions, memory slots, lifecycle timers, embeddings index — edit values in place. | -| **Streams** | Live WebSocket monitor for memory writes, hook events, and observation updates as they flow through iii streams. | -| **Queues** | Durable queue topics + dead-letter management. Replay or drop failed embedding / compression jobs. | -| **Traces** | OpenTelemetry waterfall / flame / service-breakdown views. Filter by `trace_id` to see exactly which functions, DB calls, and embedding requests a single `memory.search` produced. | -| **Logs** | Structured OTEL logs filtered and correlated to trace/span IDs. | -| **Config** | Runtime configuration — see exactly which workers, providers, and ports your engine is running with. | -| **Flow** | (Optional, `--enable-flow`) Interactive architecture graph of every worker, trigger, and stream. | +| 页面 | 用途 | +|------|------| +| **Workers** | 查看每个已连接的 worker 及其实时指标 — 包括 agentmemory worker 自身。 | +| **Functions** | 直接用 JSON 载荷调用 agentmemory 的任意函数 — 便于在不接入客户端的情况下测试 `memory.recall`、`memory.consolidate`、`graph.query`。 | +| **Triggers** | 重放 HTTP、cron、event 和 state 触发器 — 手动触发合并 cron、重试 HTTP 路由、发出状态变更。 | +| **States** | 支持完整 CRUD 的 KV 浏览器 — 会话、记忆槽位、生命周期定时器、嵌入索引 — 可就地编辑值。 | +| **Streams** | 通过 iii 流实时 WebSocket 监控记忆写入、钩子事件和观察更新。 | +| **Queues** | 持久化队列主题 + 死信管理。重放或丢弃失败的嵌入/压缩任务。 | +| **Traces** | OpenTelemetry 瀑布图/火焰图/服务分解视图。按 `trace_id` 筛选，精确查看单次 `memory.search` 产生了哪些函数调用、数据库请求和嵌入请求。 | +| **Logs** | 结构化 OTEL 日志，可按 trace/span ID 筛选并关联。 | +| **Config** | 运行时配置 — 精确查看引擎正在使用哪些 worker、provider 和端口。 | +| **Flow** | （可选，`--enable-flow`）每个 worker、触发器和流的交互式架构图。 |

iii console trace waterfall view showing per-span duration
- Traces: waterfall / flame / service breakdown for every memory operation. + Traces：每次记忆操作的瀑布图/火焰图/服务分解视图。

-**Traces are already on:** +**追踪已默认开启：** -`iii-config.yaml` ships with the `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 1.0`, metrics + logs). No extra config needed — the moment agentmemory starts, every memory operation emits a trace span and a structured log the console can read. +`iii-config.yaml` 随附已启用的 `iii-observability` worker（`exporter: memory`、`sampling_ratio: 1.0`，以及 metrics + logs）。无需额外配置 — agentmemory 启动瞬间，每次记忆操作都会发出控制台可读取的追踪 span 和结构化日志。 -If you want to export to Jaeger/Honeycomb/Grafana Tempo instead, change `exporter: memory` to `exporter: otlp` and set the collector endpoint per iii's observability docs. +若要导出到 Jaeger/Honeycomb/Grafana Tempo，请将 `exporter: memory` 改为 `exporter: otlp`，并按 iii 的可观测性文档设置采集器端点。 -> **Heads-up:** no auth is enforced on the console itself — keep it bound to `127.0.0.1` (the default) and never expose it publicly. +> **提示：** 控制台本身不强制认证 — 请保持绑定到 `127.0.0.1`（默认值），切勿公开暴露。 ---

Powered by iii

-agentmemory is **already a running [iii](https://iii.dev) instance**. Three primitives — worker, function, trigger — compose the runtime; KV state, streams, and OTEL traces come from iii-state, iii-stream, and iii-observability workers that ship with iii. You didn't install Postgres, Redis, Express, pm2, or Prometheus, because iii replaces them. +agentmemory **已是运行中的 [iii](https://iii.dev) 实例**。三种原语 — worker、function、trigger — 构成运行时；KV 状态、流和 OTEL 追踪来自随 iii 一并提供的 iii-state、iii-stream 和 iii-observability worker。你无需安装 Postgres、Redis、Express、pm2 或 Prometheus，因为 iii 已替代它们。 -That means one more command extends agentmemory with an entire new capability. +这意味着只需一条命令即可为 agentmemory 扩展一整项新能力。 -### Extend agentmemory with one command +### 一条命令扩展 agentmemory ```bash iii worker add iii-pubsub # fan memory writes out to every connected instance @@ -1186,57 +1194,57 @@ iii worker add iii-database # swap in a SQL-backed state adapter iii worker add mcp # generic MCP host alongside the agentmemory MCP ``` -Each `iii worker add` registers new functions and triggers into the same engine agentmemory is already running on. The viewer and console pick them up immediately — no reload, no new integration, no new container. +每个 `iii worker add` 都会在 agentmemory 已在运行的同一引擎上注册新函数与触发器。查看器（viewer）与控制台（console）会立即加载它们——无需重载、无需新集成、也无需新容器。 -| `iii worker add` | What you get on top of agentmemory | +| `iii worker add` | 在 agentmemory 之上你还能获得什么 | |---|---| -| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Multi-instance memory: every `remember` fans out, every `search` reads the union | -| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Scheduled lifecycle — nightly consolidation, weekly snapshots, decay on a fixed clock | -| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Durable retries: failed embedding + compression jobs survive restart, no lost observations | -| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | OTEL traces, metrics, logs on every function — wired in `iii-config.yaml` from day one | -| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code that came out of `memory_recall` runs inside a throwaway VM, not your shell | -| [`iii-database`](https://workers.iii.dev/workers/iii-database) | SQL-backed state adapter when you outgrow the in-memory KV defaults | -| [`mcp`](https://workers.iii.dev/workers/mcp) | Stand up extra MCP servers next to agentmemory's, share the same engine | +| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | 多实例记忆：每个 `remember` 扇出分发，每个 `search` 读取并集 | +| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | 定时生命周期——夜间合并、每周快照、按固定时钟衰减 | +| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | 持久化重试：失败的嵌入与压缩任务在重启后仍可恢复，不会丢失观测记录 | +| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | 每个函数都具备 OTEL 追踪、指标与日志——从第一天起就在 `iii-config.yaml` 中接入 | +| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | 来自 `memory_recall` 的代码在一次性 VM 中运行，而非你的 shell | +| [`iii-database`](https://workers.iii.dev/workers/iii-database) | 当你超出内存 KV 默认能力时，可使用 SQL 支撑的状态适配器 | +| [`mcp`](https://workers.iii.dev/workers/mcp) | 在 agentmemory 的 MCP 服务器旁再拉起额外 MCP 服务器，共享同一引擎 | -Full registry: [workers.iii.dev](https://workers.iii.dev). Every worker there composes through the same primitives agentmemory uses — and the agentmemory you already have is one of them. +完整注册表：[workers.iii.dev](https://workers.iii.dev). 那里的每个 worker 都通过 agentmemory 使用的同一套原语进行组合——而你已有的 agentmemory 就是其中之一。 -### What iii replaces +### iii 替代了什么 -| Traditional stack | agentmemory uses | +| 传统技术栈 | agentmemory 使用 | |---|---| | Express.js / Fastify | iii HTTP Triggers | -| SQLite / Postgres + pgvector | iii KV State + in-memory vector index | +| SQLite / Postgres + pgvector | iii KV State + 内存向量索引 | | SSE / Socket.io | iii Streams (WebSocket) | -| pm2 / systemd | iii engine worker supervision | -| Prometheus / Grafana | iii OTEL + health monitor | -| Custom plugin systems | `iii worker add ` | +| pm2 / systemd | iii 引擎 worker 监管 | +| Prometheus / Grafana | iii OTEL + 健康监控 | +| 自定义插件系统 | `iii worker add ` | -**174 source files · ~37,800 LOC · 1,423+ tests · 258 functions · 44 KV scopes** — all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself. +**174 个源文件 · ~37,800 行代码 · 1,423+ 个测试 · 258 个函数 · 44 个 KV 作用域**——全部建立在三大原语之上。没有 `agentmemory plugin install`。插件系统就是 iii 本身。 ---

Configuration

-### LLM Providers +### LLM 提供商 -agentmemory auto-detects from your environment. By default, no LLM calls are made unless you configure a provider or explicitly opt in to the Claude subscription fallback. +agentmemory 会从你的环境中自动检测。默认情况下，除非你配置了提供商或明确选择启用 Claude 订阅回退，否则不会发起任何 LLM 调用。 | Provider | Config | Notes | |----------|--------|-------| -| **No-op (default)** | No config needed | LLM-backed compress/summarize is DISABLED. Synthetic BM25 compression + recall still work. See `AGENTMEMORY_ALLOW_AGENT_SDK` below if you used to rely on the Claude-subscription fallback. | -| Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing | -| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible | -| Gemini | `GEMINI_API_KEY` | Also enables embeddings | -| OpenRouter | `OPENROUTER_API_KEY` | Any model | -| OpenAI API | `OPENAI_API_KEY` | Default `gpt-4o-mini`, override with `OPENAI_MODEL` | -| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) or `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Anything OpenAI-API-compatible. Zero cost, runs on your hardware. See [Local models](#local-models-ollama-lm-studio-vllm) below. | -| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in only. Spawns `@anthropic-ai/claude-agent-sdk` sessions — used to cause unbounded Stop-hook recursion so it is no longer the default. | +| **No-op（默认）** | 无需配置 | 基于 LLM 的压缩/摘要已禁用。合成 BM25 压缩与召回仍可正常工作。若你过去依赖 Claude 订阅回退，请参阅下文 `AGENTMEMORY_ALLOW_AGENT_SDK`。 | +| Anthropic API | `ANTHROPIC_API_KEY` | 按 token 计费 | +| MiniMax | `MINIMAX_API_KEY` | 兼容 Anthropic | +| Gemini | `GEMINI_API_KEY` | 同时启用嵌入（embeddings） | +| OpenRouter | `OPENROUTER_API_KEY` | 任意模型 | +| OpenAI API | `OPENAI_API_KEY` | 默认 `gpt-4o-mini`，可用 `OPENAI_MODEL` 覆盖 | +| **本地（Ollama / LM Studio / vLLM / llama.cpp）** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1`（Ollama）或 `http://localhost:1234/v1`（LM Studio）+ `OPENAI_MODEL=` | 任何兼容 OpenAI API 的服务均可。零成本，运行在你自己的硬件上。请参阅下文 [本地模型](#local-models-ollama-lm-studio-vllm)。 | +| Claude 订阅回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 仅可主动选择启用。会启动 `@anthropic-ai/claude-agent-sdk` 会话——过去曾导致无界 Stop-hook 递归，因此不再是默认选项。 | -### Local models (Ollama / LM Studio / vLLM) +### 本地模型（Ollama / LM Studio / vLLM） -agentmemory talks to any OpenAI-API-compatible server, so anything that exposes `/v1/chat/completions` works without code changes. No paid keys, no cloud, no rate limits — runs entirely on your hardware. +agentmemory 可与任何兼容 OpenAI API 的服务器通信，因此任何暴露 `/v1/chat/completions` 的方案都无需改代码即可使用。无需付费密钥、无需云端、无速率限制——完全在你的硬件上运行。 -**Ollama** (default port `11434`): +**Ollama**（默认端口 `11434`）： ```bash ollama pull qwen2.5-coder:7b # or llama3.2:3b, mistral:7b, etc. @@ -1250,9 +1258,9 @@ OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_MODEL=qwen2.5-coder:7b ``` -**LM Studio** (default port `1234`): +**LM Studio**（默认端口 `1234`）： -Open LM Studio → Local Server tab → Start Server. Pick any chat model from the picker (Qwen 2.5 Coder, Llama 3.2, DeepSeek, etc.). +打开 LM Studio → Local Server 标签页 → Start Server。从选择器中选择任意对话模型（Qwen 2.5 Coder、Llama 3.2、DeepSeek 等）。 ```env # ~/.agentmemory/.env @@ -1261,43 +1269,43 @@ OPENAI_BASE_URL=http://localhost:1234/v1 OPENAI_MODEL=qwen2.5-coder-7b-instruct # match the model name from LM Studio ``` -**vLLM / llama.cpp / Text Generation Inference**: same shape — point `OPENAI_BASE_URL` at whatever URL your server exposes, set `OPENAI_MODEL` to a name your server will accept. +**vLLM / llama.cpp / Text Generation Inference**：配置方式相同——将 `OPENAI_BASE_URL` 指向你的服务器暴露的 URL，将 `OPENAI_MODEL` 设为服务器可接受的模型名称。 -**Model picks for memory work**: compression and summarization are short tasks (<2K tokens in, <500 tokens out) where a 7B instruct model is plenty. Recommendations: +**记忆任务的模型选择**：压缩与摘要是短任务（输入 <2K tokens，输出 <500 tokens），7B instruct 模型已足够。推荐： | Model | Size | Why | |-------|------|-----| -| `qwen2.5-coder:7b` | ~4.7 GB | Best at code-shaped sessions; trained on programming + tool-use traces | -| `llama3.2:3b` | ~2 GB | Smallest sane option — fine for compression, weaker for graph extraction | -| `mistral:7b-instruct` | ~4.4 GB | Good general-purpose baseline if you don't want code-specific | -| `deepseek-r1:7b` | ~4.7 GB | Reasoning-tier quality at 7B; slower but cleaner extractions | +| `qwen2.5-coder:7b` | ~4.7 GB | 最擅长代码形态的会话；在编程与工具调用轨迹上训练 | +| `llama3.2:3b` | ~2 GB | 最小且仍合理的选择——压缩足够，图提取较弱 | +| `mistral:7b-instruct` | ~4.4 GB | 若不需要代码专用模型，这是不错的通用基线 | +| `deepseek-r1:7b` | ~4.7 GB | 7B 规模的推理级质量；更慢但提取更干净 | -Reasoning-class models (`o1`-style with `` blocks) can return empty `content` with a `reasoning` field your local server may not surface. If extractions come back blank, switch to a non-reasoning model first. The `OPENAI_REASONING_EFFORT=none` env can also disable thinking on Ollama Cloud thinking models that mirror the OpenAI reasoning schema. +推理类模型（带 `` 块的 `o1` 风格）可能返回空的 `content`，并带有本地服务器可能无法呈现的 `reasoning` 字段。若提取结果为空，请先切换到非推理模型。`OPENAI_REASONING_EFFORT=none` 环境变量也可在镜像 OpenAI 推理 schema 的 Ollama Cloud 思考模型上禁用 thinking。 -Local embeddings ship out of the box via `@xenova/transformers` — `EMBEDDING_PROVIDER=local` (default) gives you BGE-small entirely on-device. No extra config needed. +本地嵌入开箱即用，通过 `@xenova/transformers` 提供——`EMBEDDING_PROVIDER=local`（默认）可在设备端完全运行 BGE-small。无需额外配置。 -### Cost-aware model selection +### 成本感知的模型选择 -Background compression runs on every observation, so model choice meaningfully changes monthly spend. Captured workload data: 635 requests / 888K tokens / 35 hours of active use, run against three OpenRouter models at 2026-05-23 pricing. +后台压缩会对每条观测记录运行，因此模型选择会显著影响月度支出。已捕获的工作负载数据：635 次请求 / 888K tokens / 35 小时活跃使用，按 2026-05-23 的 OpenRouter 定价对三种模型进行测算。 | Tier | Model | Input / 1M | Output / 1M | Cost for the captured 35h | Notes | |------|-------|------------|-------------|---------------------------|-------| -| Recommended | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid compression + summarization quality at ~10× lower cost than Sonnet. | -| Recommended | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | Older but still fine for compression-only workloads. | -| Recommended | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Strong code reasoning if your sessions are heavily code-shaped. | -| Premium | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | High quality but expensive for always-on background work. | -| Premium | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | Similar tier to Sonnet. | -| Avoid | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | Reasoning-class model; massive overspend for compression. | +| Recommended | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | 压缩与摘要质量扎实，成本约为 Sonnet 的 1/10。 | +| Recommended | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | 较旧，但对纯压缩工作负载仍然够用。 | +| Recommended | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | 若会话以代码为主，代码推理能力强。 | +| Premium | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | 质量高，但对常驻后台任务来说偏贵。 | +| Premium | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | 与 Sonnet 同级。 | +| Avoid | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | 推理类模型；用于压缩会造成巨额超支。 | -agentmemory prints a runtime warning when `OPENROUTER_MODEL` matches a premium-tier pattern. Set `AGENTMEMORY_SUPPRESS_COST_WARNING=1` to silence once you've made an informed choice. +当 `OPENROUTER_MODEL` 匹配高级（premium-tier）模式时，agentmemory 会打印运行时警告。在做出知情选择后，可设置 `AGENTMEMORY_SUPPRESS_COST_WARNING=1` 以静默该警告。 -Quality vs cost tradeoff for memory work: compression is a summarization task with relatively loose quality bars (the agent re-reads the summary, not the user). DeepSeek-V4-Pro / Qwen3-Coder land within rounding error of Sonnet on this task while costing ~10× less. Save the premium-tier models for queries you read directly. +记忆任务的质量与成本权衡：压缩是一项摘要任务，质量门槛相对宽松（由 agent 重读摘要，而非用户直接阅读）。在此任务上，DeepSeek-V4-Pro / Qwen3-Coder 的质量与 Sonnet 在舍入误差范围内相当，成本却低约 10 倍。将高级模型留给你会直接阅读的查询。 -Sources: [OpenRouter pricing for Sonnet 4.6](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/). +来源：[OpenRouter pricing for Sonnet 4.6](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/). -### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) +### 多 agent 记忆（`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`） -In multi-agent setups where several roles share one agentmemory server (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` tags every write with the role that made it. `AGENTMEMORY_AGENT_SCOPE` controls whether recall filters by that tag. +在多个角色共享同一 agentmemory 服务器的多 agent 场景下（架构师 / 开发者 / 审阅者 / 研究员 / 支持 agent），`AGENT_ID` 会为每次写入打上执行该写入的角色标签。`AGENTMEMORY_AGENT_SCOPE` 控制召回时是否按该标签过滤。 ```env TEAM_ID=company @@ -1306,33 +1314,33 @@ AGENT_ID=architect AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared" ``` -Two modes: +两种模式： -| Mode | Tag writes | Filter recall | When to use | +| 模式 | 写入标签 | 过滤召回 | 适用场景 | |------|------------|---------------|-------------| -| `shared` (default) | yes | no | Cross-agent context with audit trail. Architect can see what developer noted, but every row records who said it. | -| `isolated` | yes | yes | Strict separation. Architect never sees developer's observations / memories / sessions. | +| `shared`（默认） | 是 | 否 | 带审计轨迹的跨 agent 上下文。架构师可以看到开发者记下的内容，但每一行都会记录是谁说的。 | +| `isolated` | 是 | 是 | 严格隔离。架构师永远看不到开发者的 observations / memories / sessions。 | -What gets tagged when `AGENT_ID` is set: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. The role flows from `api::session::start` → `mem::observe` → `mem::compress` → KV. +设置 `AGENT_ID` 时会打上标签的内容：`Session.agentId`、`RawObservation.agentId`、`CompressedObservation.agentId`、`Memory.agentId`。角色按 `api::session::start` → `mem::observe` → `mem::compress` → KV 传递。 -What gets filtered in isolated mode: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Each endpoint accepts `?agentId=` to override per-request, and `?agentId=*` to opt out of the env scope entirely. `/memories` also accepts `?includeOrphans=true` to surface pre-AGENT_ID memories whose `agentId` is undefined. +隔离模式下会被过滤的内容：`mem::smart-search`、`/agentmemory/memories`、`/agentmemory/observations`、`/agentmemory/sessions`。每个端点都接受 `?agentId=` 以按请求覆盖，以及 `?agentId=*` 以完全退出环境作用域。`/memories` 还接受 `?includeOrphans=true`，用于展示在 AGENT_ID 之前、其 `agentId` 为 undefined 的 memories。 -Per-call override at the SDK / REST layer: every mutating endpoint (`/session/start`, `/remember`) accepts an `agentId` field in the request body that wins over the env. Useful for runtimes routing many roles through one server process. +在 SDK / REST 层的按次覆盖：每个变更类端点（`/session/start`、`/remember`）在请求体中都接受 `agentId` 字段，其优先级高于环境变量。适用于在一个服务进程中为多个角色做路由的运行时。 -When `AGENT_ID` is unset, memory remains unscoped (legacy behavior, no tags, no filters). +当 `AGENT_ID` 未设置时，memory 保持无作用域（旧版行为，无标签、无过滤）。 -### Ports +### 端口 -agentmemory + iii-engine bind four ports by default. If a restart fails with `port in use`, this table tells you which process to look for. +agentmemory + iii-engine 默认绑定四个端口。若重启因 `port in use` 失败，下表可帮助你定位应对应的进程。 -| Port | Process | Purpose | Env override | +| 端口 | 进程 | 用途 | 环境变量覆盖 | |------|---------|---------|--------------| | `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` | -| `3112` | iii-engine | Internal streams worker (consumed by agentmemory + viewer) | `III_STREAMS_PORT` | -| `3113` | agentmemory | Real-time viewer (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` | -| `49134` | iii-engine | WebSocket — workers register here, OTel telemetry flows over it | `III_ENGINE_URL` (full URL, default `ws://localhost:49134`) | +| `3112` | iii-engine | 内部 streams worker（由 agentmemory + viewer 消费） | `III_STREAMS_PORT` | +| `3113` | agentmemory | 实时 viewer（`http://localhost:3113`） | `AGENTMEMORY_VIEWER_PORT` | +| `49134` | iii-engine | WebSocket — worker 在此注册，OTel 遥测经此传输 | `III_ENGINE_URL`（完整 URL，默认 `ws://localhost:49134`） | -Stale-process cleanup when ports stay bound after a crashed run: +崩溃后端口仍被占用时的陈旧进程清理： ```bash # macOS / Linux — find whatever is on each port and kill it @@ -1345,38 +1353,38 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134" taskkill /F /PID ``` -`agentmemory stop` reaps both the worker and the engine pidfile cleanly on graceful shutdown. The manual cleanup above is only for the post-crash case where neither pidfile is left behind. +`agentmemory stop` 在优雅关闭时会干净地回收 worker 与 engine 的 pidfile。上面的手动清理仅适用于崩溃后两个 pidfile 都未留下的情况。 -### Config File +### 配置文件 -Put agentmemory runtime configuration in `~/.agentmemory/.env` instead of exporting variables in every shell. If the viewer shows a setup hint like `export ANTHROPIC_API_KEY=...`, copy it into this file as `ANTHROPIC_API_KEY=...` without the `export` prefix, then restart agentmemory. +将 agentmemory 运行时配置写入 `~/.agentmemory/.env`，而不是在每个 shell 中 export 变量。若 viewer 显示类似 `export ANTHROPIC_API_KEY=...` 的设置提示，请将其复制到该文件中，写成不带 `export` 前缀的 `ANTHROPIC_API_KEY=...`，然后重启 agentmemory。 -Process environment variables still work and take precedence over values in the file. +进程环境变量仍然有效，且优先级高于文件中的值。 -On Windows, the same file lives at `%USERPROFILE%\.agentmemory\.env`: +在 Windows 上，同一文件位于 `%USERPROFILE%\.agentmemory\.env`： ```powershell New-Item -ItemType Directory -Force $HOME\.agentmemory notepad $HOME\.agentmemory\.env ``` -To test with a Claude Code Pro/Max subscription instead of an API key, opt in explicitly: +若要用 Claude Code Pro/Max 订阅而不是 API key 进行测试，请显式选择启用： ```env AGENTMEMORY_ALLOW_AGENT_SDK=true AGENTMEMORY_AUTO_COMPRESS=true ``` -Consolidation (graph nodes, lessons, crystals) is on by default whenever an LLM provider is configured. Explicitly opt out with `CONSOLIDATION_ENABLED=false` if you want LLM-free operation. Graph extraction is a separate flag: +只要配置了 LLM 提供商，Consolidation（图节点、lessons、crystals）默认开启。若希望完全不使用 LLM，请用 `CONSOLIDATION_ENABLED=false` 显式退出。图提取是一个独立开关： ```env GRAPH_EXTRACTION_ENABLED=true # CONSOLIDATION_ENABLED=false # opt out of auto-consolidation ``` -### Environment Variables +### 环境变量 -Create `~/.agentmemory/.env`: +创建 `~/.agentmemory/.env`： ```env # LLM provider (pick one — default is the no-op provider: no LLM calls) @@ -1501,30 +1509,30 @@ Create `~/.agentmemory/.env`:

API

-128 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers. +在端口 `3111` 上提供 128 个端点。REST API 默认绑定到 `127.0.0.1`。受保护的端点在设置 `AGENTMEMORY_SECRET` 时需要 `Authorization: Bearer `，mesh 同步端点则要求两端对等节点均提供 `AGENTMEMORY_SECRET`。
-Key endpoints +关键端点 -| Method | Path | Description | +| 方法 | 路径 | 说明 | |--------|------|-------------| -| `GET` | `/agentmemory/health` | Health check (always public) | -| `POST` | `/agentmemory/session/start` | Start session + get context | -| `POST` | `/agentmemory/session/end` | End session | -| `POST` | `/agentmemory/observe` | Capture observation | -| `POST` | `/agentmemory/smart-search` | Hybrid search | -| `POST` | `/agentmemory/context` | Generate context | -| `POST` | `/agentmemory/remember` | Save to long-term memory | -| `POST` | `/agentmemory/forget` | Delete observations | -| `POST` | `/agentmemory/enrich` | File context + memories + bugs | -| `GET` | `/agentmemory/profile` | Project profile | -| `GET` | `/agentmemory/export` | Export all data | -| `POST` | `/agentmemory/import` | Import from JSON | -| `POST` | `/agentmemory/graph/query` | Knowledge graph query | -| `POST` | `/agentmemory/team/share` | Share with team | -| `GET` | `/agentmemory/audit` | Audit trail | +| `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` | 文件上下文、记忆与缺陷 | +| `GET` | `/agentmemory/profile` | 项目配置文件 | +| `GET` | `/agentmemory/export` | 导出全部数据 | +| `POST` | `/agentmemory/import` | 从 JSON 导入 | +| `POST` | `/agentmemory/graph/query` | 知识图谱查询 | +| `POST` | `/agentmemory/team/share` | 与团队共享 | +| `GET` | `/agentmemory/audit` | 审计追踪 | -Full endpoint list: [`src/triggers/api.ts`](src/triggers/api.ts) +完整端点列表：[`src/triggers/api.ts`](src/triggers/api.ts)
@@ -1539,7 +1547,7 @@ npm test # 1,423+ tests npm run test:integration # API tests (requires running services) ``` -**Prerequisites:** Node.js >= 20, [iii-engine](https://iii.dev/docs) or Docker +**前置要求：** Node.js >= 20、[iii-engine](https://iii.dev/docs) 或 Docker

License