agentmemory 是一个面向 AI 编程智能体的持久化记忆系统，目标是解决编程智能体每次会话都需要重新解释架构、重新发现缺陷、重新教授偏好的问题。传统内置记忆如 CLAUDE.md、.cursorrules 受限于约 200 行且容易过时，agentmemory 通过自动捕获智能体行为、压缩为可检索记忆，并在下一次会话开始时注入正确上下文来改善这一状况。项目基于 iii 引擎构建，当前版本针对 iii-sdk 0.22.1 并锁定 iii-engine v0.22.1。
用途与主要能力 agentmemory 可用于为多种编程智能体提供跨会话的持久记忆。它支持 Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode 以及任何支持 MCP 的客户端。所有智能体共享同一个记忆服务器。它提供静默捕获智能体操作、压缩为可搜索记忆、在会话启动时注入上下文等能力。它还提供记忆查看器、重放时间线、导入旧版 Claude Code JSONL 转录、技能注入等功能。据资料显示，它包含 9 个可调用技能如 /recall、/remember、/session-history、/forget、/recap、/handoff、/lesson、/commit-context、/commit-history，以及 8 个按需加载的参考技能。
使用方式 安装需要 Node.js 20 或更新版本，并具备 npm 和 npx。macOS/Linux 自动安装 iii 引擎还需要 curl、POSIX sh 和 tar。原生 Windows 需要手动安装锁定版本的 iii-engine v0.22.1 iii.exe，WSL2 或 Docker Desktop 是其他支持路径。标准全新安装命令为 npx -y @agentmemory/agentmemory@latest。首次运行是交互式设置：选择要连接的智能体、选择 LLM 提供商或保持无密钥、种子配置、启动记忆服务器及其锁定的 iii 引擎，并可选择全局安装。y 接受 npx 包提示，@latest 避免使用旧缓存版本。设置提供商后可使用 LLM 功能，但 LLM 编写的观察压缩仅在同时设置 AGENTMEMORY_AUTO_COMPRESS=true 时启动。无密钥模式禁用向量嵌入，memory_recall（mem::search 路径）使用 BM25，memory_smart_search 在图数据已存在时还可融合结构图匹配。如需免费设备端语义召回，可在 ~/.agentmemory/.env 中设置 EMBEDDING_PROVIDER=local 并重启。首次嵌入请求会下载 Xenova/all-MiniLM-L6-v2，之后推理在本地运行。
本地运行时使用四个端口：3111 用于 REST/MCP HTTP，3112 用于 iii 流，3113 用于查看器，49134 用于 iii 工作器 WebSocket。持久化 iii 状态按平台存储在 macOS 的 ~/Library/Application Support/agentmemory，Linux 的 $XDG_DATA_HOME/agentmemory 或 ~/.local/share/agentmemory，Windows 的 %APPDATA%\agentmemory。可用 --data-dir <path> 或 AGENTMEMORY_DATA_DIR 覆盖，并在每次重启时复用相同值。为向后兼容，现有的 ./data/state_store.db 或 ./data/iii-config.yaml 对实例 0 优先于平台默认值；显式标志或环境覆盖仍然优先。可通过 agentmemory connect <agent> 随时连接更多智能体，支持 20 个适配器。Windows 快速路径是 WSL2，原生 Windows 引擎设置需手动下载锁定 v0.22.1 ZIP 并解压 iii.exe，CLI 不会自动解压。Docker Desktop 也受支持。
日常使用与维护 每个会话都可重放。打开查看器，选择 Replay 标签，可拖动时间线查看提示、工具调用、工具结果和响应等离散事件，支持播放/暂停、0.5x 到 4x 速度控制以及键盘快捷键。导入旧版 Claude Code JSONL 转录后，导入的会话会与原生会话一起出现在 Replay 选择器中，底层通过 mem::replay::load、mem::replay::sessions 和 mem::replay::import-jsonl iii 函数路由。每个导入的转录会被索引用于搜索，标记来源通道导入，并挖掘会话水晶和课程。注意：Claude Code 的 cleanupPeriodDays（位于 ~/.claude/settings.json，默认 30）会自动删除超过该窗口的 JSONL 转录。如果在新安装时导入数月前的历史，超过 30 天的内容已在首次导入前消失。可运行 import-jsonl 的 cron、提高 cleanupPeriodDays，或接入自动捕获钩子。升级/维护命令用于有意更新本地运行时，会变更当前工作区/运行时，可能更新 JavaScript 依赖并拉取锁定的 iiidev/iii:0.22.1 Docker 镜像，从不安装未锁定或更新版本的 iii 引擎。
基准与对比 项目提供检索准确性基准。coding-agent-life-v1 是内部语料库，在沙箱中可复现，报告称 P@5 达到该语料库数学上限 100% 命中率（0.240，见评分卡）。混合检索能检索到每个金标准会话；grep 在多会话时间查询中漏掉 2 个金标准中的 1 个。提升在于召回 + 时间，而非聚合精度。该基准较小且金标准稀疏；更大的 LongMemEval-S 区分度更好。LongMemEval-S 是 ICLR 2025 的 500 个问题，嵌入模型为 all-MiniLM-L6-v2（本地、免费、无需 API 密钥）。完整报告见 benchmark/LONGMEMEVAL.md、benchmark/QUALITY.md、benchmark/SCALE.md。竞品对比见 benchmark/COMPARISON.md，涵盖 agentmemory 与 mem0、Letta、Khoj、supermemory、TencentDB Agent Memory、MemPalace、Zep/Graphiti、Cognee、Hippo 等。基准说明：只有 agentmemory 的 R@5 是自身测量结果（LongMemEval-S，可从 benchmark/COMPARISON.md 复现）。mem0 和 Letta 的数字是它们发布的 LoCoMo 数字（不同数据集）；MemPalace、supermemory、TencentDB（PersonaMem）和 oracleagentmemory 的数字是供应商自我报告的说法，尚未独立复现（oracleagentmemory 的运行使用 GPT-5.5 针对 Oracle AI Database）。并排展示仅供大致参考，不是相同数据上的正面交锋。星标数约为近似值，会随时间漂移。
兼容性与限制 此版本针对 iii-sdk 0.22.1 并锁定 iii-engine v0.22.1，不会附加到不同版本。agentmemory 可与任何支持钩子、MCP 或 REST API 的智能体配合。Codex 插件与 Claude Code 插件来自同一 plugin/ 目录，注册捆绑的 stdio MCP 桥接、6 个生命周期钩子，以及技能；Codex 的钩子引擎会向钩子子进程注入 CLAUDE_PLUGIN_ROOT，因此相同钩子脚本可在两个宿主间工作而无需重复。Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure 事件仅限 Claude Code，不为 Codex 注册。原生插件钩子分发已在 Codex CLI 0.150.1 验证。桌面行为取决于其捆绑运行时；启用变通方法前检查 /hooks 并确认捕获事件。如果宿主需要全局钩子，可将命令镜像到 ~/.codex/hooks.json。Claude Code 推荐使用 /plugin install 路径。如果直接通过 ~/.claude.json 连接 agentmemory 的 MCP 服务器，Claude Code 永远不会解析 ${CLAUDE_PLUGIN_ROOT}，必须将钩子脚本指向 ~/.claude/settings.json 中的绝对路径；这些路径通常嵌入 agentmemory 版本，下一次升级会静默破坏每个钩子。升级 agentmemory 后需重新运行命令以刷新路径。对于远程或受保护部署，可设置 AGENTMEMORY_URL 和 AGENTMEMORY_SECRET。
该项目在 GitHub 上拥有 5000+ Stars，采用免费模式。以上为资料中明确提供的信息，其他功能、收费、价格、平台、效果或使用步骤暂未提供。
