rohitg00--agentmemory/README.md

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

<p align="center">
  <img src="assets/banner.png" alt="agentmemory — 面向 AI 编程智能体的持久化记忆" width="720" />
</p>

<p align="center">
  <strong>
    你的编程智能体会记住一切。再也不用重复解释。
    基于 <a href="https://github.com/iii-hq/iii">iii engine</a> 构建
  </strong><br/>
  为 Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode 及任意 MCP 客户端提供持久化记忆。
</p>

<p align="center">
  <a href="README.md">English</a> |
  <a href="READMEs/README.zh-CN.md">简体中文</a> |
  <a href="READMEs/README.zh-TW.md">繁體中文</a> |
  <a href="READMEs/README.ja-JP.md">日本語</a> |
  <a href="READMEs/README.ko-KR.md">한국어</a> |
  <a href="READMEs/README.es-ES.md">Español</a> |
  <a href="READMEs/README.tr-TR.md">Türkçe</a> |
  <a href="READMEs/README.ru-RU.md">Русский</a> |
  <a href="READMEs/README.hi-IN.md">हिन्दी</a> |
  <a href="READMEs/README.pt-BR.md">Português</a> |
  <a href="READMEs/README.fr-FR.md">Français</a> |
  <a href="READMEs/README.de-DE.md">Deutsch</a>
</p>

<p align="center">
  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
</p>

<p align="center">
  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
      <img alt="Star 历史图表" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
    </picture>
  </a>
</p>

<p align="center">
  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1.3k%20stars%20%2F%20182%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="设计文档：gist 上 1.3k stars / 182 forks" /></a>
</p>

<p align="center">
  <em>该 gist 在 Karpathy 的 LLM Wiki 模式上扩展了置信度评分、生命周期、知识图谱与混合搜索：agentmemory 即其实现。</em>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
</p>

<p align="center">
  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-recall.svg"><img src="assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tokens.svg"><img src="assets/tags/stat-tokens.svg" alt="减少 92% token" height="38" /></picture>
  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tools.svg"><img src="assets/tags/stat-tools.svg" alt="53 个 MCP 工具" height="38" /></picture>
  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-hooks.svg"><img src="assets/tags/stat-hooks.svg" alt="12 个自动 hooks" height="38" /></picture>
  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-deps.svg"><img src="assets/tags/stat-deps.svg" alt="0 个外部数据库" height="38" /></picture>
  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="1,423+ 项测试通过" height="38" /></picture>
</p>

<p align="center">
  <img src="assets/demo.gif" alt="agentmemory 演示" width="720" />
</p>

<p align="center">
  <a href="#install">安装</a> &bull;
  <a href="#quick-start">快速开始</a> &bull;
  <a href="#benchmarks">基准测试</a> &bull;
  <a href="#vs-competitors">与竞品对比</a> &bull;
  <a href="#works-with-every-agent">智能体</a> &bull;
  <a href="#how-it-works">工作原理</a> &bull;
  <a href="#mcp-server">MCP</a> &bull;
  <a href="#real-time-viewer">查看器</a> &bull;
  <a href="#iii-console">iii Console</a> &bull;
  <a href="#powered-by-iii">由 iii 驱动</a> &bull;
  <a href="#configuration">配置</a> &bull;
  <a href="#api">API</a>
</p>

---

## 安装

若你使用编程智能体，最快方式是：把下面这一条指令交给它，即可端到端完成 agentmemory 的安装、接入与验证。

> 请获取并遵循以下位置的说明：https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md

在 Windows 上，快速路径是 WSL2。原生 Windows 引擎需手动配置（约 10 至 20 分钟），且 `agentmemory connect` 目前尚不支持。分步说明见下方 [Windows 说明](#windows)。

```bash
npm install -g @agentmemory/agentmemory   # once — bare `agentmemory` on PATH
# If you hit EACCES on macOS/Linux system Node installs, retry with:
# sudo npm install -g @agentmemory/agentmemory
agentmemory                                      # start the memory server on :3111
agentmemory demo                                 # seed sample sessions + prove recall
agentmemory demo --serve                         # one command: boot server, run demo, tear down (no second terminal)
agentmemory connect claude-code                  # wire MCP into your agent (also: copilot-cli, codex, cursor, gemini-cli, ...)
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
```

或通过 `npx`（无需安装）：

```bash
npx @agentmemory/agentmemory
```

提示 — 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` 命令即可在各处生效。

已在运行自己的 `iii` 引擎？agentmemory 固定使用 iii-engine v0.11.2，不会挂接到其他版本（worker 无法与另一引擎的协议通信）。请先停止其他引擎，再运行 `npx -y @agentmemory/agentmemory@latest` —— 它会在 `~/.agentmemory/bin` 中安装并运行固定的 v0.11.2，不会动你自己的 `iii`。

完整选项见下方 [Quick Start](#quick-start)。各 Agent 的接入方式见 [Works with every agent](#works-with-every-agent)。

---

<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-agents.svg"><img src="assets/tags/section-agents.svg" alt="适用于所有 Agent" height="32" /></picture></h2>

agentmemory 可与任何支持 hooks、MCP 或 REST API 的 Agent 配合使用。所有 Agent 共享同一套 memory server。

<table>
<tr>
<td align="center" width="12.5%">
<a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
<strong>Claude Code</strong><br/>
<sub>原生 plugin + 12 个 hooks + MCP</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
<strong>Codex CLI</strong><br/>
<sub>原生 plugin + 6 个 hooks + MCP</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/features/copilot"><img src="https://github.githubassets.com/images/modules/site/copilot/copilot.png" alt="GitHub Copilot CLI" width="48" height="48" /></a><br/>
<strong>GitHub Copilot CLI</strong><br/>
<sub>MCP + plugin hooks/skills</sub>
</td>
<td align="center" width="12.5%">
<a href="integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
<strong>OpenClaw</strong><br/>
<sub>原生 plugin + MCP</sub>
</td>
<td align="center" width="12.5%">
<a href="integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
<strong>Hermes</strong><br/>
<sub>原生 plugin + MCP</sub>
</td>
<td align="center" width="12.5%">
<a href="integrations/pi/"><img src="assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
<sub>原生 plugin + MCP</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
<strong>OpenHuman</strong><br/>
<sub>原生 Memory trait 后端</sub>
</td>
<td align="center" width="12.5%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
<sub>MCP server</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
<strong>Gemini CLI</strong><br/>
<sub>MCP server</sub>
</td>
</tr>
<tr>
<td align="center" width="12.5%">
<a href="https://github.com/opencode-ai/opencode"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/opencode-dark.svg"><img src="https://svgl.app/library/opencode.svg" alt="OpenCode" width="48" height="48" /></picture></a><br/>
<strong>OpenCode</strong><br/>
<sub>22 个 hooks + MCP + plugin</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
<strong>Cline</strong><br/>
<sub>MCP server</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
<strong>Goose</strong><br/>
<sub>MCP server</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
<strong>Kilo Code</strong><br/>
<sub>MCP server</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
<strong>Aider</strong><br/>
<sub>REST API</sub>
</td>
<td align="center" width="12.5%">
<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
<strong>Claude Desktop</strong><br/>
<sub>MCP server</sub>
</td>
<td align="center" width="12.5%">
<a href="https://windsurf.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/windsurf-dark.svg"><img src="https://svgl.app/library/windsurf-light.svg" alt="Windsurf" width="48" height="48" /></picture></a><br/>
<strong>Windsurf</strong><br/>
<sub>MCP server</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
<strong>Roo Code</strong><br/>
<sub>MCP server</sub>
</td>
</tr>
<tr>
<td align="center" width="12.5%">
<a href="https://www.warp.dev"><img src="https://github.com/warpdotdev.png?size=120" alt="Warp" width="48" height="48" /></a><br/>
<strong>Warp</strong><br/>
<sub>connect + MCP + skills</sub>
</td>
</tr>
</table>

<p align="center">
  <sub>适用于说 MCP 或 HTTP 的<strong>任何</strong> agent。一个服务器，所有 agent 共享记忆。</sub>
</p>

---

每个会话你都要重复解释同一套架构。你重新发现同样的 bug。你反复教授同样的偏好。内置记忆（CLAUDE.md、.cursorrules）上限约 200 行且会过时。agentmemory 解决了这个问题。它会静默捕获 agent 的行为，压缩为可搜索的记忆，并在下次会话开始时注入合适的上下文。一条命令。跨 agent 通用。

**会有什么变化：** 第 1 次会话你配置 JWT auth。第 2 次会话你要求 rate limiting。agent 已经知道你的 auth 在 `src/middleware/auth.ts` 中使用 jose 中间件，测试覆盖 token 验证，且你因 Edge 兼容性选择 jose 而非 jsonwebtoken。无需重复解释。无需复制粘贴。agent 就是*知道*。

```bash
npx @agentmemory/agentmemory
```

最新发布说明：[CHANGELOG.md](CHANGELOG.md)。

---

<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-benchmarks.svg"><img src="assets/tags/section-benchmarks.svg" alt="基准测试" height="32" /></picture></h2>

<table>
<tr>
<td width="50%">

### 检索准确率

**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 |

在此语料库上达到 **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 道题）

| System | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| BM25-only fallback | 86.2% | 94.6% | 71.5% |

</td>
<td width="50%">

### Token 节省

| Approach | Tokens/yr | Cost/yr |
|---|---|---|
| Paste full context | 19.5M+ | Impossible (exceeds window) |
| LLM-summarized | ~650K | ~$500 |
| **agentmemory** | **~170K** | **~$10** |
| agentmemory + local embeddings | ~170K | **$0** |

</td>
</tr>
</table>

> 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。

**本地复现：** [`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/)。

**搭配 [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)。

---

<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-competitors.svg"><img src="assets/tags/section-competitors.svg" alt="与竞品对比" height="32" /></picture></h2>

<table>
<tr>
<th></th>
<th>agentmemory</th>
<th>mem0 (58K ⭐)</th>
<th>Letta / MemGPT (23K ⭐)</th>
<th>Khoj (35K ⭐)</th>
<th>supermemory (26K ⭐)</th>
<th>MemPalace (54K ⭐)</th>
<th>oracleagentmemory</th>
<th>Hippo</th>
<th>Built-in (CLAUDE.md)</th>
</tr>
<tr>
<td><strong>类型</strong></td>
<td>Memory engine + MCP server</td>
<td>Memory layer API</td>
<td>Full agent runtime</td>
<td>Personal AI</td>
<td>Memory API + app</td>
<td>Vector memory (OSS)</td>
<td>Memory engine (Oracle DB)</td>
<td>Memory system</td>
<td>Static file</td>
</tr>
<tr>
<td><strong>检索 R@5</strong></td>
<td><strong>95.2%</strong></td>
<td>68.5% (LoCoMo)</td>
<td>83.2% (LoCoMo)</td>
<td>N/A</td>
<td>Self-reported</td>
<td>~96.6% (self-reported)</td>
<td>94.4% (self-reported)</td>
<td>N/A</td>
<td>N/A (grep)</td>
</tr>
<tr>
<td><strong>自动捕获</strong></td>
<td>12 hooks（零手动操作）</td>
<td>Manual <code>add()</code> calls</td>
<td>Agent self-edits</td>
<td>Manual</td>
<td>API-side extraction</td>
<td>Manual</td>
<td>API extraction</td>
<td>Manual</td>
<td>Manual editing</td>
</tr>
<tr>
<td><strong>搜索</strong></td>
<td>BM25 + Vector + Graph (RRF fusion)</td>
<td>Vector + Graph</td>
<td>Vector (archival)</td>
<td>Semantic</td>
<td>Vector + RAG</td>
<td>Vector-only</td>
<td>Vector + semantic</td>
<td>Decay-weighted</td>
<td>Loads everything into context</td>
</tr>
<tr>
<td><strong>多 agent</strong></td>
<td>MCP + REST + leases + signals</td>
<td>API (no coordination)</td>
<td>Within Letta runtime only</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>Scoped only</td>
<td>Multi-agent shared</td>
<td>Per-agent files</td>
</tr>
<tr>
<td><strong>框架锁定</strong></td>
<td>None (any MCP client)</td>
<td>None</td>
<td>High (must use Letta)</td>
<td>Standalone</td>
<td>None</td>
<td>None</td>
<td>Oracle Database</td>
<td>None</td>
<td>Per-agent format</td>
</tr>
<tr>
<td><strong>外部依赖</strong></td>
<td>None (SQLite + iii-engine)</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector DB</td>
<td>Multiple</td>
<td>Managed cloud</td>
<td>Vector store</td>
<td>Oracle AI Database</td>
<td>None</td>
<td>None</td>
</tr>
<tr>
<td><strong>记忆生命周期</strong></td>
<td>4-tier consolidation + decay + auto-forget</td>
<td>Passive extraction</td>
<td>Agent-managed</td>
<td>Manual</td>
<td>Auto-forget</td>
<td>None</td>
<td>Not stated</td>
<td>Decay + consolidation</td>
<td>Manual pruning</td>
</tr>
<tr>
<td><strong>Token 效率</strong></td>
<td>~1,900 tokens/session ($10/yr)</td>
<td>Varies by integration</td>
<td>Core memory in context</td>
<td>Varies</td>
<td>Cloud pricing</td>
<td>No token budget</td>
<td>LLM-backed (varies)</td>
<td>Varies</td>
<td>22K+ tokens at 240 obs</td>
</tr>
<tr>
<td><strong>实时查看器</strong></td>
<td>Yes (port 3113)</td>
<td>Cloud dashboard</td>
<td>Cloud dashboard</td>
<td>Web UI</td>
<td>Cloud dashboard</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td><strong>自托管</strong></td>
<td>Yes (default)</td>
<td>Optional</td>
<td>Optional</td>
<td>Yes</td>
<td>No (cloud-only)</td>
<td>Yes</td>
<td>Yes (Oracle DB)</td>
<td>Yes</td>
<td>Yes</td>
</tr>
</table>

<sub>基准测试说明：仅 agentmemory 的 R@5 为我们自行测量的结果（LongMemEval-S，可从 <a href="benchmark/COMPARISON.md"><code>benchmark/COMPARISON.md</code></a> 复现）。mem0 与 Letta 的数据为其公布的 LoCoMo 数字（不同数据集）；MemPalace、supermemory 与 oracleagentmemory 的数据为厂商自行报告、我们尚未独立复现的声明（oracleagentmemory 的运行使用 GPT-5.5 搭配 Oracle AI Database）。并列展示仅供粗略参考，并非在相同数据上的正面交锋。Star 数量为近似值，会随时间变化。</sub>

---

<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-quickstart.svg"><img src="assets/tags/section-quickstart.svg" alt="快速开始" height="32" /></picture></h2>

兼容性：本版本面向稳定的 `iii-sdk` `^0.11.0` 与 iii-engine v0.11.x。

### 30 秒快速体验

```bash
# Terminal 1: start the server
npx @agentmemory/agentmemory

# Terminal 2: seed sample data and see recall in action
npx @agentmemory/agentmemory demo
```

`demo` 会初始化 3 个真实会话（JWT auth、N+1 查询修复、rate limiting），并对它们运行语义搜索。当你搜索「database performance optimization」时，它会找到「N+1 query fix」——关键词匹配做不到这一点。

打开 `http://localhost:3113` 实时观看 memory 构建过程。

### 推荐：全局安装

`npx` 会按版本缓存。如果你上周运行过 `npx @agentmemory/agentmemory@0.9.14`，裸用的 `npx @agentmemory/agentmemory` 可能仍会从 `~/.npm/_npx/` 提供过时的 0.9.14，而不是最新发布版。全局安装一次后，裸用的 `agentmemory` 命令即可随处使用：

```bash
npm install -g @agentmemory/agentmemory
# If you hit EACCES on macOS/Linux system Node installs, retry with:
# sudo npm install -g @agentmemory/agentmemory
agentmemory                    # start the server (same as the npx form)
agentmemory stop               # tear it down
agentmemory remove             # uninstall everything we created
agentmemory connect claude-code   # wire one agent
agentmemory doctor             # interactive diagnostics + fix prompts
```

从 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)
```

在 Windows / PowerShell 上，等效的缓存清理命令是 `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"`——上文中的 `npx -y ...@latest` 形式是跨平台方案。

### 会话回放（Session Replay）

agentmemory 记录的每个会话都可回放。打开查看器，选择 **Replay** 标签页，在时间轴上拖动浏览：prompts、tool calls、tool results 和 responses 会渲染为离散事件，支持播放/暂停、速度控制（0.5×–4×）以及键盘快捷键（空格切换播放，方向键逐步前进）。

已有较旧的 Claude Code JSONL 转录文件想要导入？

```bash
# Import everything under the default ~/.claude/projects
npx @agentmemory/agentmemory import-jsonl

# Or import a single file
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```

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

> **若你依赖 `import-jsonl` 作为主要采集路径，请注意：** Claude Code 的 `cleanupPeriodDays`（位于 `~/.claude/settings.json`，默认 **30**）会自动从 `~/.claude/projects/` 删除早于该时间窗口的 JSONL 转录文件。如果你在数月前的 Claude Code 历史上全新安装 agentmemory，首次导入前，超过 30 天的内容早已不存在。可任选其一：用 cron 定期运行 `import-jsonl`、将 `cleanupPeriodDays` 调高，或接入自动采集 hooks（默认插件安装路径），让每一轮在会话进行中就写入 agentmemory，这样 JSONL 清理就不再重要。

### 升级 / 维护

当你有意更新本地运行时时，使用维护命令：

```bash
npx @agentmemory/agentmemory upgrade
```

警告：该命令会修改当前工作区/运行时。它可能更新 JavaScript 依赖并拉取已固定版本的 `iiidev/iii:0.11.2` Docker 镜像。它绝不会安装未固定版本或更新的 iii 引擎。

实现细节见 `src/cli.ts`（参见 `runUpgrade` 中 `src/cli.ts:544-595` 区域附近）。

### 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 不通过插件安装（MCP 独立路径）

若你通过 `~/.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。

变通方案：

```bash
agentmemory connect claude-code --with-hooks
```

这会将相同的 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 插件平台）

```bash
# 1. start the memory server in a separate terminal
npx @agentmemory/agentmemory

# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
```

Codex 插件与 Claude Code 插件出自同一 `plugin/` 目录。它注册：

- `@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 的 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：插件 hooks 当前静默（有变通方案）

`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 仍可用；仅缺少生命周期观测。

在上游修复落地前，将相同的 hook 命令镜像到全局 `~/.codex/hooks.json`：

```bash
agentmemory connect codex --with-hooks
```

这会在 `~/.codex/hooks.json` 中添加一个幂等块，引用捆绑脚本的绝对路径（用户作用域无需 `${CLAUDE_PLUGIN_ROOT}` 展开）。升级 agentmemory 后请重新运行同一命令以刷新路径。同一文件中的用户条目会保留；仅会替换先前的 agentmemory 条目。

### GitHub Copilot CLI

```bash
# MCP-only wiring
agentmemory connect copilot-cli

# Full hooks/skills plugin from the GitHub subdir
copilot plugin install rohitg00/agentmemory:plugin
```

`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 体验，也请安装该插件。

<details>
<summary><b>OpenClaw（粘贴此提示词）</b></summary>

```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:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

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`.
```

完整指南：[`integrations/openclaw/`](integrations/openclaw/)

</details>

<details>
<summary><b>Hermes Agent（粘贴此提示词）</b></summary>

```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:

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

memory:
  provider: agentmemory

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.
```

完整指南：[`integrations/hermes/`](integrations/hermes/)

</details>

### 其他 Agent

启动 memory 服务器：`npx @agentmemory/agentmemory`

#### 通过 `npx skills add` 使用原生 skills（50+ 个 Agent）

agentmemory 以 Claude Code 风格的 `<dir>/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
npx skills add rohitg00/agentmemory -y -a warp  # explicit agent
npx skills add rohitg00/agentmemory -y -a '*'   # install to every installed agent
```

这与 `agentmemory connect <agent>` **互为补充**：

- `agentmemory connect <agent>` 会写入 MCP 服务器配置，使工具可用。
- `npx skills add rohitg00/agentmemory` 会安装 skills，使 Agent 知道何时调用它们。

对于 skills CLI 尚未覆盖的少数 Agent（Zed v1.3.x 及更低版本），请自行将 15 个 SKILL.md 文件放入该 Agent 的原生 skill 目录——相同格式在各处均适用。

#### 标准 MCP 配置块

在所有采用 `mcpServers` 结构的宿主上，agentmemory 条目均为**相同的 MCP 服务器配置块**（Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI、OpenClaw）：

```json
"agentmemory": {
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  "env": {
    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
  }
}
```

**将此条目合并进宿主配置文件中的现有 `mcpServers` 对象**——不要替换整个文件。若文件已有其他服务器，请在 `mcpServers` 内将 `agentmemory` 作为另一个键添加在它们旁边。若完全缺少 `mcpServers`，请将配置块粘贴到 `{ "mcpServers": { ... } }` 内。`${VAR}` 占位符会在 MCP 服务器启动时从 shell 继承 `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`——未设置的变量会传入空字符串，shim 会回退到 `http://localhost:3111`。一条已接入的配置即可同时覆盖本地与远程（k8s / 反向代理）部署。

| Agent | 配置文件 | 说明 |
|---|---|---|
| **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` 配置块。项目级覆盖配置放在 `<repo>/.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` 会自动检测宿主并合并。 |

**沙箱化 MCP 客户端**（Flatpak / Snap / 受限容器）无法访问宿主机的 `localhost` 时：请同时在 `env` 块中设置 `"AGENTMEMORY_FORCE_PROXY": "1"`，并将 `AGENTMEMORY_URL` 指向沙箱实际可访问的路由（例如你的局域网 IP）。

### 编程式访问（Python / Rust / Node）

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
cargo add iii-sdk           # Rust
npm  install iii-sdk        # Node
```

```python
from iii import register_worker

iii = register_worker("ws://localhost:49134")
iii.connect()

iii.trigger({
    "function_id": "mem::smart-search",
    "payload": {"project": "demo", "query": "how do tokens refresh"},
})
```

完整示例：[`examples/python/`](examples/python/)（快速入门 + observation/recall 流程）。对于没有 iii 运行时的主机，`:3111` 上的 REST 仍然可用。

### 从源码安装

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

若已安装 `iii`，将使用本地的 `iii-engine` 启动 agentmemory；否则在 Docker 可用时回退到 Docker Compose。REST、streams 与 viewer 默认绑定到 `127.0.0.1`。

请手动安装 `iii-engine`。**agentmemory 目前将 `iii-engine` 固定为 `v0.11.2`**——`v0.11.6` 引入了全新的「一切经 `iii worker add` 沙箱化」模型，而 agentmemory 尚未为此完成重构。重构落地后会解除版本固定。若你已手动迁移到该沙箱模型，可用 `AGENTMEMORY_III_VERSION=<version>` 覆盖。

- **macOS arm64：** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64：** 将 `aarch64-apple-darwin` 替换为 `x86_64-apple-darwin`
- **Linux x64：** 替换为 `x86_64-unknown-linux-gnu`
- **Linux arm64：** 替换为 `aarch64-unknown-linux-gnu`
- **Windows：** 从 [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), 下载 `iii-x86_64-pc-windows-msvc.zip`，解压 `iii.exe`，并加入 PATH

也可使用 Docker（附带的 `docker-compose.yml` 会拉取 `iiidev/iii:0.11.2`）。完整文档：[iii.dev/docs](https://iii.dev/docs).

### Windows

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

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

```powershell
# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
#     model that engine v0.11.6+ requires)
# 2. Download iii-x86_64-pc-windows-msvc.zip
#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe somewhere on PATH, or place it at:
#    %USERPROFILE%\.local\bin\iii.exe
#    (agentmemory checks that location automatically)
# 4. Verify:
iii --version
# Should print: 0.11.2

# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory
```

**选项 B — Docker Desktop：**

```powershell
# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Run agentmemory — it will auto-start the bundled compose file:
npx -y @agentmemory/agentmemory
```

**选项 C — 仅独立 MCP（无引擎）：** 若你只需要供 agent 使用的 MCP 工具，而不需要 REST API、viewer 或 cron 任务，可完全跳过引擎：

```powershell
npx -y @agentmemory/agentmemory mcp
# or via the shim package:
npx -y @agentmemory/mcp
```

**Windows 诊断：** 若 `npx @agentmemory/agentmemory` 失败，请用 `--verbose` 重新运行以查看引擎的实际 stderr。常见失败模式：

| 现象 | 处理 |
|---|---|
| `iii-engine process started` 随后 `did not become ready within 15s` | 引擎启动时崩溃——用 `--verbose` 重新运行并检查 stderr |
| `Could not start iii-engine` | 既未安装 `iii.exe`，也未安装 Docker。参见上方选项 A 或 B |
| 端口冲突 | 用 `netstat -ano \| findstr :3111` 查看占用情况，然后结束进程或使用 `--port <N>` |
| 已安装 Docker 但仍跳过 Docker 回退 | 确认 Docker Desktop 实际已在运行（系统托盘图标） |

> 注意：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`。

---

<h2 id="deploy">部署</h2>

面向托管平台的一键模板。每个模板都自带独立
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。

<p>
  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>

Render 的一键部署按钮要求仓库根目录存在 `render.yaml`，而我们有意保持根目录整洁。请按 [`deploy/render/`](./deploy/render/README.md) 中记录的 Render Blueprint 流程，手动指向仓库内的 blueprint。

完整设置说明（HMAC 捕获、viewer SSH 隧道、轮换、备份、
成本下限）见 [`deploy/`](./deploy/README.md)：

- [`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 栈，主机与数据归你所有。

仅发布端口 `3111`。viewer 在 `3113` 上仍绑定到
容器内 loopback——每个模板的 README 都记录了通过
SSH 隧道访问它的方式。

---

<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-why.svg"><img src="assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>

每个编程 agent 在会话结束时都会忘记一切。你浪费每个会话开头 5 分钟重新解释技术栈。agentmemory 在后台运行，彻底消除这一问题。

```text
Session 1: "Add auth to the API"
  Agent writes code, runs tests, fixes bugs
  agentmemory silently captures every tool use
  Session ends -> observations compressed into structured memory

Session 2: "Now add rate limiting"
  Agent already knows:
    - Auth uses JWT middleware in src/middleware/auth.ts
    - Tests in test/auth.test.ts cover token validation
    - You chose jose over jsonwebtoken for Edge compatibility
  Zero re-explaining. Starts working immediately.
```

### 与内置 agent 记忆对比

每个 AI 编程 agent 都自带内置记忆 — Claude Code 有 `MEMORY.md`，Cursor 有 notepads，Cline 有 memory bank。它们就像便利贴。agentmemory 则是这些便利贴背后的可搜索数据库。

| | 内置 (CLAUDE.md) | agentmemory |
|---|---|---|
| 规模 | 200 行上限 | 无限制 |
| 搜索 | 将全部内容载入上下文 | BM25 + vector + graph（仅 top-K） |
| Token 成本 | 240 条观察记录时 22K+ | 约 1,900 tokens（减少 92%） |
| 跨 agent | 各 agent 独立文件 | MCP + REST（任意 agent） |
| 协调 | 无 | Leases、signals、actions、routines |
| 可观测性 | 手动读取文件 | :3113 上的实时查看器 |

---

<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-how.svg"><img src="assets/tags/section-how.svg" alt="How It Works" height="32" /></picture></h2>

### 记忆流水线

```text
PostToolUse hook fires
  -> SHA-256 dedup (5min window)
  -> Privacy filter (strip secrets, API keys)
  -> Store raw observation
  -> LLM compress -> structured facts + concepts + narrative
  -> Vector embedding (6 providers + local)
  -> Index in BM25 + vector

Stop / SessionEnd hook fires
  -> Summarize session
  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)

SessionStart hook fires
  -> Load project profile (top concepts, files, patterns)
  -> Hybrid search (BM25 + vector + graph)
  -> Token budget (default: 2000 tokens)
  -> Inject into conversation
```

### 四层记忆巩固

灵感来自人脑处理记忆的方式 — 与睡眠巩固（sleep consolidation）不无相似。

| 层级 | 内容 | 类比 |
|------|------|------|
| **Working** | 工具使用产生的原始观察记录 | 短期记忆 |
| **Episodic** | 压缩后的会话摘要 | "发生了什么" |
| **Semantic** | 提取的事实与模式 | "我知道什么" |
| **Procedural** | 工作流与决策模式 | "如何做" |

记忆会随时间衰减（艾宾浩斯曲线，Ebbinghaus curve）。频繁访问的记忆会加强。陈旧记忆会自动淘汰。矛盾会被检测并解决。

### 捕获内容

| Hook | 捕获内容 |
|------|----------|
| `SessionStart` | 项目路径、会话 ID |
| `UserPromptSubmit` | 用户提示词（经隐私过滤） |
| `PreToolUse` | 文件访问模式 + 增强上下文 |
| `PostToolUse` | 工具名称、输入、输出 |
| `PostToolUseFailure` | 错误上下文 |
| `PreCompact` | 压缩前重新注入记忆 |
| `SubagentStart/Stop` | 子 agent 生命周期 |
| `Stop` | 会话结束摘要 |
| `SessionEnd` | 会话完成标记 |

### 核心能力

| 能力 | 说明 |
|---|---|
| **自动捕获** | 通过 hooks 记录每次工具使用 — 零手动操作 |
| **语义搜索** | BM25 + vector + 知识图谱，经 RRF 融合 |
| **记忆演化** | 版本管理、替代关系、关系图谱 |
| **自动遗忘** | TTL 过期、矛盾检测、重要性淘汰 |
| **隐私优先** | API 密钥、机密信息、`<private>` 标签在存储前剥离 |
| **自愈** | 熔断器、提供商回退链、健康监控 |
| **Claude 桥接** | 与 MEMORY.md 双向同步 |
| **知识图谱** | 实体提取 + BFS 遍历 |
| **团队记忆** | 跨团队成员的命名空间共享 + 私有记忆 |
| **引用溯源** | 将任意记忆追溯至源观察记录 |
| **Git 快照** | 版本化、回滚并 diff 记忆状态 |

---

<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-search.svg"><img src="assets/tags/section-search.svg" alt="Search" height="32" /></picture></h2>

三路检索融合三种信号：

| 流 | 作用 | 时机 |
|---|---|---|
| **BM25** | 词干化关键词匹配 + 同义词扩展 | 始终开启 |
| **Vector** | 稠密嵌入的余弦相似度 | 已配置嵌入提供商时 |
| **Graph** | 通过实体匹配进行知识图谱遍历 | 查询中检测到实体时 |

经倒数排名融合（Reciprocal Rank Fusion，RRF，k=60）融合，并按会话去重（每个会话最多 3 条结果）。

BM25 开箱即支持希腊文、西里尔文、希伯来文、阿拉伯文及带重音符号的拉丁文分词。对于中文 / 日文 / 韩文记忆，请安装可选分词器（`npm install @node-rs/jieba tiny-segmenter`），将 CJK 连续文本切分为词级 token；未安装时，agentmemory 会软回退为整段分词，并在 stderr 打印一次性提示。

### 嵌入提供商

agentmemory 会自动检测你的提供商。为获得最佳效果，请安装本地嵌入（免费）：

```bash
npm install @xenova/transformers
```

| 提供商 | 模型 | 成本 | 说明 |
|---|---|---|---|
| **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 | 不定 | 多模型代理 |

---

<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-mcp.svg"><img src="assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>

53 个工具、6 个资源、3 个提示词和 15 个 skills，面向任意 agent 的最全面 MCP 记忆工具包。

> **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 个工具

<details>
<summary>核心工具（始终可用）</summary>

| 工具 | 说明 |
|------|------|
| `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` | 查询关系图谱 |

</details>

<details>
<summary>扩展工具（共 53 个 — 设置 AGENTMEMORY_TOOLS=all）</summary>

| 工具 | 说明 |
|------|------|
| `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` | 追溯溯源 |

</details>

</details>

### 6 个资源 · 3 个 Prompt · 4 个 Skill

| 类型 | 名称 | 描述 |
|------|------|------|
| 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` | 删除观察记录/会话 |

### 独立 MCP

无需完整服务器即可运行 — 适用于任意 MCP 客户端。以下两种方式均可：

```bash
npx -y @agentmemory/agentmemory mcp   # canonical (always available)
npx -y @agentmemory/mcp                # shim package alias
```

或添加到你的 Agent 的 MCP 配置中：

大多数 Agent（Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI）：
```json
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}
```

将 `agentmemory` 条目合并到宿主现有的 `mcpServers` 对象中，而不是替换整个文件。对于无法访问宿主 `localhost` 的沙箱客户端，在 env 块中添加 `"AGENTMEMORY_FORCE_PROXY": "1"`，并将 `AGENTMEMORY_URL` 设置为沙箱可访问的路由。

OpenCode（`opencode.json`）：
```json
{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  },
  "plugin": ["./plugins/agentmemory-capture.ts"]
}
```

从仓库复制插件文件：
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```

---

<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-viewer.svg"><img src="assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>

在端口 `3113` 上自动启动。提供实时观察流、会话浏览器、记忆浏览器、知识图谱可视化和健康仪表盘。

```bash
open http://localhost:3113
```

查看器服务器默认绑定到 `127.0.0.1`。REST 提供的 `/agentmemory/viewer` 端点遵循常规的 `AGENTMEMORY_SECRET` Bearer 令牌规则。CSP 头使用每次响应生成的脚本 nonce，并禁用内联处理程序属性（`script-src-attr 'none'`）。

---

<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-viewer.svg"><img src="assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>

`:3113` 上的查看器展示你的 Agent **记住了什么**。[iii console](https://iii.dev/docs/console) 展示你的 Agent **做了什么** — 每次记忆操作都是一条 OpenTelemetry 追踪，每个 KV 条目可编辑，每个函数可调用，每个流可点击。同一套记忆的两种视图：一种面向产品，一种面向引擎。

观察 `memory_smart_search` 触发，以瀑布图形式查看 BM25 扫描 → 嵌入查找 → RRF 融合 → 重排序器。在 KV 浏览器中编辑卡住的合并定时器。用调整后的载荷重放 `PostToolUse` 钩子。固定 WebSocket 流，实时观看观察记录落地。

agentmemory 免费提供此功能，因为每次函数调用和触发都通过 iii 执行 — 无需自定义，也无需额外插桩。

<p align="center">
  <img src="assets/iii-console/workers.png" alt="iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
  <br/>
  <em>Workers 页面：每个已连接的 worker — 包括 agentmemory 自身 — 显示 PID、函数数量、运行时信息和最后活跃时间。</em>
</p>

**已预装。** 控制台随 `iii` 一并提供 — 无需单独安装。

**与 agentmemory 一同启动：**

```bash
# agentmemory viewer holds port 3113, so run the console on 3114.
# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
iii console --port 3114
```

然后打开 `http://localhost:3114`。添加 `--enable-flow` 以启用实验性的架构图页面。

仅在你已迁移引擎端点时才需要覆盖：

```bash
iii console --port 3114 \
  --engine-port 3111 \
  --ws-port 3112 \
  --bridge-port 49134
```

**控制台可执行的操作：**

| 页面 | 用途 |
|------|------|
| **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、触发器和流的交互式架构图。 |

<p align="center">
  <img src="assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
  <br/>
  <em>Traces：每次记忆操作的瀑布图/火焰图/服务分解视图。</em>
</p>

**追踪已默认开启：**

`iii-config.yaml` 随附已启用的 `iii-observability` worker（`exporter: memory`、`sampling_ratio: 1.0`，以及 metrics + logs）。无需额外配置 — agentmemory 启动瞬间，每次记忆操作都会发出控制台可读取的追踪 span 和结构化日志。

若要导出到 Jaeger/Honeycomb/Grafana Tempo，请将 `exporter: memory` 改为 `exporter: otlp`，并按 iii 的可观测性文档设置采集器端点。

> **提示：** 控制台本身不强制认证 — 请保持绑定到 `127.0.0.1`（默认值），切勿公开暴露。

---

<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-architecture.svg"><img src="assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>

agentmemory **已是运行中的 [iii](https://iii.dev) 实例**。三种原语 — worker、function、trigger — 构成运行时；KV 状态、流和 OTEL 追踪来自随 iii 一并提供的 iii-state、iii-stream 和 iii-observability worker。你无需安装 Postgres、Redis、Express、pm2 或 Prometheus，因为 iii 已替代它们。

这意味着只需一条命令即可为 agentmemory 扩展一整项新能力。

### 一条命令扩展 agentmemory

```bash
iii worker add iii-pubsub          # fan memory writes out to every connected instance
iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
iii worker add iii-queue           # durable retries for embedding + compression jobs
iii worker add iii-observability   # OTEL traces on every memory op (default on)
iii worker add iii-sandbox         # run recalled code inside an isolated microVM
iii worker add iii-database        # swap in a SQL-backed state adapter
iii worker add mcp                 # generic MCP host alongside the agentmemory MCP
```

每个 `iii worker add` 都会在 agentmemory 已在运行的同一引擎上注册新函数与触发器。查看器（viewer）与控制台（console）会立即加载它们——无需重载、无需新集成、也无需新容器。

| `iii worker add` | 在 agentmemory 之上你还能获得什么 |
|---|---|
| [`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 服务器，共享同一引擎 |

完整注册表：[workers.iii.dev](https://workers.iii.dev). 那里的每个 worker 都通过 agentmemory 使用的同一套原语进行组合——而你已有的 agentmemory 就是其中之一。

### iii 替代了什么

| 传统技术栈 | agentmemory 使用 |
|---|---|
| Express.js / Fastify | iii HTTP Triggers |
| SQLite / Postgres + pgvector | iii KV State + 内存向量索引 |
| SSE / Socket.io | iii Streams (WebSocket) |
| pm2 / systemd | iii 引擎 worker 监管 |
| Prometheus / Grafana | iii OTEL + 健康监控 |
| 自定义插件系统 | `iii worker add <name>` |

**174 个源文件 · ~37,800 行代码 · 1,423+ 个测试 · 258 个函数 · 44 个 KV 作用域**——全部建立在三大原语之上。没有 `agentmemory plugin install`。插件系统就是 iii 本身。

---

<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-config.svg"><img src="assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>

### LLM 提供商

agentmemory 会从你的环境中自动检测。默认情况下，除非你配置了提供商或明确选择启用 Claude 订阅回退，否则不会发起任何 LLM 调用。

| Provider | Config | Notes |
|----------|--------|-------|
| **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=<your model>` | 任何兼容 OpenAI API 的服务均可。零成本，运行在你自己的硬件上。请参阅下文 [本地模型](#local-models-ollama-lm-studio-vllm)。 |
| Claude 订阅回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 仅可主动选择启用。会启动 `@anthropic-ai/claude-agent-sdk` 会话——过去曾导致无界 Stop-hook 递归，因此不再是默认选项。 |

### 本地模型（Ollama / LM Studio / vLLM）

agentmemory 可与任何兼容 OpenAI API 的服务器通信，因此任何暴露 `/v1/chat/completions` 的方案都无需改代码即可使用。无需付费密钥、无需云端、无速率限制——完全在你的硬件上运行。

**Ollama**（默认端口 `11434`）：

```bash
ollama pull qwen2.5-coder:7b   # or llama3.2:3b, mistral:7b, etc.
ollama serve
```

```env
# ~/.agentmemory/.env
OPENAI_API_KEY=ollama                          # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen2.5-coder:7b
```

**LM Studio**（默认端口 `1234`）：

打开 LM Studio → Local Server 标签页 → Start Server。从选择器中选择任意对话模型（Qwen 2.5 Coder、Llama 3.2、DeepSeek 等）。

```env
# ~/.agentmemory/.env
OPENAI_API_KEY=lmstudio                        # any non-empty string; LM Studio ignores it
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**：配置方式相同——将 `OPENAI_BASE_URL` 指向你的服务器暴露的 URL，将 `OPENAI_MODEL` 设为服务器可接受的模型名称。

**记忆任务的模型选择**：压缩与摘要是短任务（输入 <2K tokens，输出 <500 tokens），7B instruct 模型已足够。推荐：

| Model | Size | Why |
|-------|------|-----|
| `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 规模的推理级质量；更慢但提取更干净 |

推理类模型（带 `<think>` 块的 `o1` 风格）可能返回空的 `content`，并带有本地服务器可能无法呈现的 `reasoning` 字段。若提取结果为空，请先切换到非推理模型。`OPENAI_REASONING_EFFORT=none` 环境变量也可在镜像 OpenAI 推理 schema 的 Ollama Cloud 思考模型上禁用 thinking。

本地嵌入开箱即用，通过 `@xenova/transformers` 提供——`EMBEDDING_PROVIDER=local`（默认）可在设备端完全运行 BGE-small。无需额外配置。

### 成本感知的模型选择

后台压缩会对每条观测记录运行，因此模型选择会显著影响月度支出。已捕获的工作负载数据：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 | 压缩与摘要质量扎实，成本约为 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+ | 推理类模型；用于压缩会造成巨额超支。 |

当 `OPENROUTER_MODEL` 匹配高级（premium-tier）模式时，agentmemory 会打印运行时警告。在做出知情选择后，可设置 `AGENTMEMORY_SUPPRESS_COST_WARNING=1` 以静默该警告。

记忆任务的质量与成本权衡：压缩是一项摘要任务，质量门槛相对宽松（由 agent 重读摘要，而非用户直接阅读）。在此任务上，DeepSeek-V4-Pro / Qwen3-Coder 的质量与 Sonnet 在舍入误差范围内相当，成本却低约 10 倍。将高级模型留给你会直接阅读的查询。

来源：[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/).

### 多 agent 记忆（`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`）

在多个角色共享同一 agentmemory 服务器的多 agent 场景下（架构师 / 开发者 / 审阅者 / 研究员 / 支持 agent），`AGENT_ID` 会为每次写入打上执行该写入的角色标签。`AGENTMEMORY_AGENT_SCOPE` 控制召回时是否按该标签过滤。

```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"
```

两种模式：

| 模式 | 写入标签 | 过滤召回 | 适用场景 |
|------|------------|---------------|-------------|
| `shared`（默认） | 是 | 否 | 带审计轨迹的跨 agent 上下文。架构师可以看到开发者记下的内容，但每一行都会记录是谁说的。 |
| `isolated` | 是 | 是 | 严格隔离。架构师永远看不到开发者的 observations / memories / sessions。 |

设置 `AGENT_ID` 时会打上标签的内容：`Session.agentId`、`RawObservation.agentId`、`CompressedObservation.agentId`、`Memory.agentId`。角色按 `api::session::start` → `mem::observe` → `mem::compress` → KV 传递。

隔离模式下会被过滤的内容：`mem::smart-search`、`/agentmemory/memories`、`/agentmemory/observations`、`/agentmemory/sessions`。每个端点都接受 `?agentId=<role>` 以按请求覆盖，以及 `?agentId=*` 以完全退出环境作用域。`/memories` 还接受 `?includeOrphans=true`，用于展示在 AGENT_ID 之前、其 `agentId` 为 undefined 的 memories。

在 SDK / REST 层的按次覆盖：每个变更类端点（`/session/start`、`/remember`）在请求体中都接受 `agentId` 字段，其优先级高于环境变量。适用于在一个服务进程中为多个角色做路由的运行时。

当 `AGENT_ID` 未设置时，memory 保持无作用域（旧版行为，无标签、无过滤）。

### 端口

agentmemory + iii-engine 默认绑定四个端口。若重启因 `port in use` 失败，下表可帮助你定位应对应的进程。

| 端口 | 进程 | 用途 | 环境变量覆盖 |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `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`） |

崩溃后端口仍被占用时的陈旧进程清理：

```bash
# macOS / Linux — find whatever is on each port and kill it
lsof -i :3111,3112,3113,49134
pkill -f agentmemory || true
pkill -f 'iii ' || true

# Windows
netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID <pid>
```

`agentmemory stop` 在优雅关闭时会干净地回收 worker 与 engine 的 pidfile。上面的手动清理仅适用于崩溃后两个 pidfile 都未留下的情况。

### 配置文件

将 agentmemory 运行时配置写入 `~/.agentmemory/.env`，而不是在每个 shell 中 export 变量。若 viewer 显示类似 `export ANTHROPIC_API_KEY=...` 的设置提示，请将其复制到该文件中，写成不带 `export` 前缀的 `ANTHROPIC_API_KEY=...`，然后重启 agentmemory。

进程环境变量仍然有效，且优先级高于文件中的值。

在 Windows 上，同一文件位于 `%USERPROFILE%\.agentmemory\.env`：

```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```

若要用 Claude Code Pro/Max 订阅而不是 API key 进行测试，请显式选择启用：

```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```

只要配置了 LLM 提供商，Consolidation（图节点、lessons、crystals）默认开启。若希望完全不使用 LLM，请用 `CONSOLIDATION_ENABLED=false` 显式退出。图提取是一个独立开关：

```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false   # opt out of auto-consolidation
```

### 环境变量

创建 `~/.agentmemory/.env`：

```env
# LLM provider (pick one — default is the no-op provider: no LLM calls)
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...
# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
#                                          # OpenAI LLM provider (here) AND the OpenAI
#                                          # embedding provider (further below). Set
#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
#                                          # to embeddings only.
# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
#                                          # Auto-detected from `.openai.azure.com` hostname; uses
#                                          # api-key header + api-version query param.
# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
#                                          # for back-compat with v0.9.17. New configs should
#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
#                                          # Honored only by OpenAI's reasoning models (o1, o3,
#                                          # gpt-*-reasoning) and providers that mirror that
#                                          # schema (Ollama Cloud thinking models). Standard
#                                          # chat models reject this field with 400. Set to
#                                          # "none" for thinking models that return reasoning
#                                          # but no content.
# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
#                                          # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true

# Embedding provider (auto-detected, or override)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table

# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
                                          # embedding). For the OpenAI LLM path, the
                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
                                          # takes precedence when set, for back-compat
                                          # with v0.9.17.
                                          # Increase for slow networks or large batch calls;
                                          # decrease to fail-fast on rate-limit holds.

# Search tuning
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000

# Auth
# AGENTMEMORY_SECRET=your-secret

# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111

# Features
# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default. When on,
                                   # every PostToolUse hook calls your
                                   # LLM provider to compress the
                                   # observation — expect significant
                                   # token spend on active sessions.
# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
                                   # memory slots — persona,
                                   # user_preferences, tool_guidelines,
                                   # project_context, guidance,
                                   # pending_items, session_patterns,
                                   # self_notes. Size-limited; agent
                                   # edits via memory_slot_* tools.
                                   # Pinned slots addressable for
                                   # SessionStart injection.
# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
                                   # Stop hook fires mem::slot-reflect:
                                   # scans recent observations, auto-
                                   # appends TODOs to pending_items,
                                   # counts patterns in
                                   # session_patterns, records touched
                                   # files in project_context. Fire-
                                   # and-forget; does not block.
# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
                                   # - SessionStart may inject ~1-2K
                                   #   chars of project context into
                                   #   the first turn of each session
                                   #   (this is what actually reaches
                                   #   the model — Claude Code treats
                                   #   SessionStart stdout as context)
                                   # - PreToolUse fires /agentmemory/enrich
                                   #   on every file-touching tool call
                                   #   (resource cleanup, not a token
                                   #   fix — PreToolUse stdout is debug
                                   #   log only per Claude Code docs)
                                   # Observations are still captured via
                                   # PostToolUse regardless of this flag.
# GRAPH_EXTRACTION_ENABLED=false
# CONSOLIDATION_ENABLED=false   # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false

# Team
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private

# Tool visibility: "core" (8 tools, lean fallback) or "all" (53 tools)
# AGENTMEMORY_TOOLS=core
```

---

<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-api.svg"><img src="assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>

在端口 `3111` 上提供 128 个端点。REST API 默认绑定到 `127.0.0.1`。受保护的端点在设置 `AGENTMEMORY_SECRET` 时需要 `Authorization: Bearer <secret>`，mesh 同步端点则要求两端对等节点均提供 `AGENTMEMORY_SECRET`。

<details>
<summary>关键端点</summary>

| 方法 | 路径 | 说明 |
|--------|------|-------------|
| `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` | 审计追踪 |

完整端点列表：[`src/triggers/api.ts`](src/triggers/api.ts)

</details>

---

<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-development.svg"><img src="assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>

```bash
npm run dev               # Hot reload
npm run build             # Production build
npm test                  # 1,423+ tests
npm run test:integration  # API tests (requires running services)
```

**前置要求：** Node.js >= 20、[iii-engine](https://iii.dev/docs) 或 Docker

<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-license.svg"><img src="assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>

[Apache-2.0](LICENSE)