agentmemory connect 适配器全解析：21 种 AI 编码 Agent 的一键接入指南
【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory
agentmemory 通过agentmemory connect <agent>命令，将持久化记忆服务器自动接线到主流 AI 编码 Agent 的配置中，覆盖 21 种宿主工具。本文以 agentmemory-agents 参考文档 为骨架，结合 src/cli/connect 目录下适配器源码，完整讲解每条适配器的接入协议、目标配置文件、命令行参数与底层实现，读完即可上手接入任意受支持的 Agent，并掌握验证、排障与回滚方法。
connect 是什么：把记忆服务"接线"进宿主 Agent
agentmemory connect <agent>是一条自动接线命令：它会读取目标 Agent 的配置文件，将 agentmemory 的记忆服务条目合并进去，并且保留用户已有的全部服务器配置（不会覆盖或破坏既有条目）。接入完成后，Agent 即可调用memory_*工具读写持久化记忆。
从架构上看，agentmemory 的服务端核心是运行在localhost:3111的 REST 守护进程（默认AGENTMEMORY_URL=http://localhost:3111，无鉴权、开放全部工具）；对于只认 MCP 协议的宿主，connect 适配器会写入一个 stdio 模式的 MCP 桥接条目，把 MCP 工具调用转发到后端的 REST 服务。这一"REST 为主、MCP 为桥"的双层模型在 src/cli/connect/types.ts 的protocolNote字段注释中有明确说明。
每个适配器在代码中统一实现为ConnectAdapter接口（见 src/cli/connect/types.ts）：
name/displayName：命令别名与展示名；protocolNote：一行说明该适配器走 REST hooks 还是 MCP，以及原因；category：集成风格，"native" 表示宿主自带第一方插件/生命周期 hooks，"mcp" 表示只接线 MCP 服务器（默认值）；detect()：探测本机是否安装了该 Agent；install(opts)：执行实际的配置写入，返回ConnectResult。
ConnectResult有四种形态：installed（成功写入并可能附带mutatedPath与backupPath）、already-wired（已接入，配合--force可重装）、stub（需要手工安装）、skipped（未检测到或异常）。
21 个适配器全表
以下表格完整转录自 plugin/skills/agentmemory-agents/REFERENCE.md，该文档由 src/cli/connect/index.ts 自动生成，与代码中的ADAPTERS数组一一对应：
| Agent | 命令名 | 接入协议说明 |
|---|---|---|
| Antigravity | antigravity | 通过 mcp_config.json 使用 MCP。Antigravity 取代了 Gemini CLI（2026-06-18 停用）。 |
| Antigravity CLI (agy) | antigravity-cli | 通过~/.gemini/config/mcp_config.json使用 MCP（注意这是 agy 命令行工具，不是 Antigravity IDE——IDE 对应connect antigravity）。agy 内部的/mcp斜杠命令可列出已配置的服务器。加--with-hooks还会安装原生的~/.gemini/config/hooks.json自动捕获 hooks。 |
| Claude Code | claude-code | 使用 MCP，同时提供 hooks（接入后可用/mcp重载）。 |
| Cline | cline | 通过~/.cline/mcp.json使用 MCP（CLI 场景）。VS Code 用户可在 Cline 设置 → MCP Servers → Edit JSON 中粘贴同一配置块。 |
| Codex CLI | codex | 使用 MCP，hooks 随 Codex 插件分发；在 Codex Desktop 上还需加--with-hooks安装全局 hooks.json 以规避 openai/codex#16430。 |
| Continue | continue | 通过~/.continue/config.yaml（推荐）或 config.json（旧版，仅在无 yaml 时）使用 MCP。 |
| GitHub Copilot CLI | copilot-cli | 使用 MCP。建议同时安装插件以获得完整的 hooks/skills 覆盖。 |
| Cursor | cursor | 使用 MCP（Cursor 唯一支持的协议），底层记忆桥运行在 :3111。 |
| Devin CLI | devin | 通过用户配置使用 MCP，新版本 Devin CLI 会将 mcpServers 迁移进 mcp_config.json。加--with-hooks启用原生自动捕获。 |
| Droid (Factory.ai) | droid | 通过~/.factory/mcp.json使用 MCP，droid 内/mcp可列出已配置服务器。加--with-hooks安装原生~/.factory/hooks.json自动捕获 hooks。 |
| DeepSeek Harness | dsh | 通过$DSH_HOME/cordis.patch.yml（每个 profile 都会加载的 home 级补丁层）使用 MCP，工具以mcp__agentmemory__*形式出现。加--with-hooks会通过 Harness 的 Claude Code hook 桥接入自动捕获。 |
| Gemini CLI | gemini-cli | 使用 MCP（Gemini CLI 唯一支持的协议），底层记忆桥运行在 :3111。 |
| Hermes Agent | hermes | 使用 MCP，同时提供 hooks。 |
| Kiro | kiro | 通过~/.kiro/settings/mcp.json（用户级）使用 MCP，工作区覆盖配置位于.kiro/settings/mcp.json。 |
| OpenClaw | openclaw | 使用 MCP，同时提供 hooks。 |
| OpenCode | opencode | 通过~/.config/opencode/opencode.json（顶层mcp键）使用 MCP。要获得完整自动捕获，还需安装 plugin/opencode 目录下的内置插件。 |
| OpenHuman | openhuman | 使用原生 hooks（REST API 位于 :3111），不需要 MCP。 |
| pi | pi | 使用针对 :3111 REST API 的原生生命周期 hooks（Agent 启动时 recall、结束时 capture、记忆工具），不需要 MCP。 |
| Qwen Code | qwen | 通过~/.qwen/settings.json使用 MCP。Qwen Code 的 hook 系统也可单独接线，见官方文档。 |
| Warp | warp | 通过~/.warp/.mcp.json使用 MCP。若同时安装了 Claude Code 插件，skills 会从.claude/skills/自动发现。 |
| Zed | zed | 通过~/.config/zed/settings.json（键名为context_servers）使用 MCP。 |
注意：接入后可配合 plugin/skills/agentmemory-agents/SKILL.md 使用——connect 负责让工具可用，skills 负责教会 Agent 何时调用它们（详见下文"与 skills 的分工"）。
快速开始：一条命令接入
在 plugin/skills/agentmemory-agents/SKILL.md 中给出了最小可用示例：
agentmemory connect claude-code # 或 cursor、codex、gemini-cli 等任意受支持名称接入完成后需要两步确认：
- 重启宿主或运行其 MCP 重载命令（例如 Claude Code 中的
/mcp），让新服务器生效； - 在 Agent 中确认能列出 agentmemory 的完整工具集。
在 src/cli/connect/index.ts 中可以看到完整流程（runConnect）：
- 解析命令行参数；
- 若未指定 Agent 名称且未加
--all，自动探测本机已安装的 Agent，并以多选交互界面询问要接入哪些（p.multiselect）； - 逐个执行
runAdapter：先detect()探测，再打印协议说明protocolNote，随后install()写入配置； - 写入成功后自动打印
mutatedPath（被修改的文件路径）与备份路径； - 汇总输出。
runAdapter中还有一个关键细节：MCP/hooks 接线完成后，只要宿主缺少自动捕获 hooks，就会尝试向该 Agent 的原生规则文件写入一条"记忆使用指引"（见下文"记忆使用指引自动激活"），该步骤是 best-effort，失败不会让整个 connect 报错。
命令行参数详解
connect 的参数解析在 src/cli/connect/index.ts 的parseFlags中实现，可用参数如下：
| 参数 | 含义 | 源码行为 |
|---|---|---|
agentmemory connect <name> | 指定要接入的 Agent 名称（对应上表"命令名"列） | 通过resolveAdapter按小写名称精确匹配，未知名称会报错并列出全部受支持名称 |
--dry-run | 预演模式，只打印将要写入的位置与内容，不实际修改任何文件 | 各适配器输出[dry-run] Would ...日志并返回installed结果 |
--force | 即使已接入也强制重装 | 覆盖already-wired短路逻辑 |
--all | 接入本机探测到的全部 Agent | 遍历ADAPTERS.filter(a => a.detect())逐个执行 |
--with-hooks | 在 MCP 之外额外安装宿主的原生 hooks 配置 | 对 Codex 写入~/.codex/hooks.json（openai/codex#16430 变通方案）、对 Claude Code 写入~/.claude/settings.json（#508 变通方案）、对 Droid 写入~/.factory/hooks.json、对 DeepSeek Harness 写入$DSH_HOME/agentmemory.hooks.json并追加 hooks-claude-code 补丁行；对没有 hooks 安装器的适配器为 no-op（见 src/cli/connect/types.ts） |
--no-guidelines | 关闭默认开启的记忆使用指引写入 | 见 src/cli/connect/types.ts 的guidelines字段说明 |
从源码看，guidelines默认开启（let guidelines = true），即每次接线后都会自动写入使用指引；--no-guidelines可显式关闭。
底层机制一：统一的 MCP 配置块
所有走 MCP 的适配器写入的服务器条目都来自 src/cli/connect/util.ts 中定义的AGENTMEMORY_MCP_BLOCK：
{ "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL:-http://localhost:3111}", "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET:-}", "AGENTMEMORY_TOOLS": "${AGENTMEMORY_TOOLS:-all}" } }这段配置有两个值得注意的设计点：
- 环境变量使用
${VAR:-default}展开形式：配置会继承用户 shell 中的AGENTMEMORY_URL/AGENTMEMORY_SECRET/AGENTMEMORY_TOOLS，变量未设置时也不会解析失败。源码注释（#510）解释了原因：早期${VAR}形式在用户没有 shell 级导出时会导致 Claude Code 静默丢弃该服务器——按 Claude Code 的 MCP 文档，必需环境变量缺失且无默认值时配置解析会失败。 - 默认值即本机运行形态：
localhost:3111、无鉴权、全部工具（all）。同一配置条目可同时服务于本地与远程（Kubernetes / 反向代理）部署，且不会触发 doctor 的重复配置告警（#375），对未导出环境变量的新安装也不会解析失败（#510）。
对 GitHub Copilot CLI，另有AGENTMEMORY_COPILOT_MCP_BLOCK（src/cli/connect/util.ts），在 Windows 上会把启动命令换成cmd.exe /d /s /c npx -y @agentmemory/mcp，并带上"type": "local"与"tools": ["*"]。
底层机制二：JSON MCP 适配器工厂
大量 Agent（Cursor、Cline、Zed、Kiro、Warp、Droid、OpenCode、Continue、Devin、Qwen 等）共用同一个createJsonMcpAdapter工厂（src/cli/connect/json-mcp-adapter.ts），只需声明差异即可：
detectDir/configPath：探测目录与要写入的配置文件；wrapperKey：服务器列表的包裹键，默认mcpServers，Zed 使用context_servers；extraEntryFields：额外字段，例如 Droid 需要type: "stdio"；installHooks：可选的原生 hooks 安装器，配合--with-hooks调用。
工厂的install()有一个统一的安全写入流程：
- 读取现有配置（JSON 解析失败时视为空）；
- 合并已存在的服务器，绝不丢用户条目；
- 检查是否已包含 agentmemory 条目（通过
command === "npx"且 args 含@agentmemory/mcp识别），已存在且未加--force时直接返回already-wired； - 写入前将原文件备份到
~/.agentmemory/backups/（时间戳命名，见 src/cli/connect/util.ts 的backupFile）； - 通过临时文件 +
renameSync实现原子写入； - 写入后回读校验，若配置中未出现预期的 agentmemory 条目则返回
skipped: verification-failed。
以 Cursor 为例，完整适配器仅声明了 5 行（src/cli/connect/cursor.ts）：探测~/.cursor、写入~/.cursor/mcp.json，协议说明为"MCP（Cursor 唯一支持的协议），底层记忆桥运行在 :3111"。
底层机制三：原生 hooks 类适配器
与"写一份 MCP 配置"不同，部分适配器走的是原生集成：
pi（src/cli/connect/pi.ts）：pi 会自动发现~/.pi/agent/extensions/*/index.ts，因此 connect 的安装动作是把仓库内置的扩展复制进去——源文件来自 integrations/pi 的index.ts与security.ts，目标为~/.pi/agent/extensions/agentmemory/。已是最新版本时返回already-wired；文件内容不一致时先备份再覆盖，最后同样做回读校验。接入后 pi 下次启动自动发现扩展，运行中的 pi 可用/reload热加载，用/agentmemory-status验证。
Claude Code（src/cli/connect/claude-code.ts）：MCP 条目写入~/.claude.json的mcpServers；若加--with-hooks，还会把 plugin/hooks/hooks.json 合并进~/.claude/settings.json的顶层hooks字段（#508 变通方案），并把${CLAUDE_PLUGIN_ROOT}解析为内置 plugin 目录的绝对路径，使脚本路径不依赖环境变量展开。重新安装会先剥离旧的 agentmemory 条目（识别依据是命令路径指向<pluginRoot>/scripts/），再以幂等方式合并，用户的其他 hook 条目不受影响。
Codex / Droid / DeepSeek Harness的 hooks 同样由 src/cli/connect/codex-hooks.ts 的buildMergedHooks统一合并引擎驱动——findPluginRoot会从模块位置向上最多 12 层查找同时包含plugin/scripts与plugin/hooks的目录，兼容打包后的dist/cli.mjs与开发态两种布局。
记忆使用指引自动激活
这是 connect 一个容易被忽略但很实用的默认行为：对没有自动捕获 hooks的 Agent，接线完成后会自动向该 Agent 的原生规则机制写入一条指引（src/cli/connect/guidelines.ts），让 Agent 主动调用记忆工具。指引正文如下：
- 任务开始时先调用
memory_recall（或memory_smart_search）加载相关的历史决策、修复与偏好，避免让用户重复描述；- 学到持久性知识（决策、修复、坑、用户偏好、项目约定）时调用
memory_save持久化；- 优先 recall 而非重新推导，保存简洁可复用的要点而非完整记录。
写入选址按 Agent 各自的官方规则机制而定，分为四种格式（block/mdc/steering/rule）：
- Cursor：项目级
.cursor/rules/agentmemory.mdc（带alwaysApply: truefrontmatter）； - Cline：项目级
.clinerules/agentmemory.md； - Continue：项目级
.continue/rules/00-agentmemory.md； - Zed / Gemini CLI / Qwen Code / OpenCode / Droid / Antigravity / Copilot CLI：优先用户全局规则文件（如
~/.config/zed/AGENTS.md、~/.gemini/GEMINI.md、~/.qwen/QWEN.md、~/.config/opencode/AGENTS.md、~/.factory/AGENTS.md、~/.copilot/copilot-instructions.md），项目级文件兜底； - Kiro：steering 文件（带
inclusion: alwaysfrontmatter）； - Warp：项目级
AGENTS.md。
对共享指令文件（block格式），写入采用<!-- agentmemory:start -->/<!-- agentmemory:end -->标记块进行幂等 upsert：重复运行只更新标记块内的内容，用户写在标记外的内容保留；检测到孤立的残缺标记时则放弃写入以免误删用户内容（src/cli/connect/guidelines.ts）。Claude Code 与 Codex 不在此列——它们已通过生命周期 hooks 自动捕获记忆。
验证与排障
接入是否成功，判定标准在 plugin/skills/agentmemory-agents/SKILL.md 中写得很清楚：宿主应显示完整工具集且服务器运行中。一个典型的失败信号是——只有 7 个工具，这说明 MCP 桥无法触达后端服务器。
排障步骤（详见 plugin/skills/_shared/TROUBLESHOOTING.md）：
- 在宿主中运行
/plugin list确认 agentmemory 已启用； - 重启宿主——插件与 MCP 配置只在启动时读取，会话中途重装不会注册工具；
- 运行
/mcp确认agentmemory服务器连接正常。
如果 MCP 工具始终不可用但守护进程在跑，可以直接走 REST 兜底：设置AGENTMEMORY_URL（默认http://localhost:3111），仅当AGENTMEMORY_SECRET已设置时才加Authorization: Bearer $AGENTMEMORY_SECRET请求头——默认本机守护进程是开放的，多余的请求头反而会被拒绝。常用端点例如POST /agentmemory/remember、POST /agentmemory/smart-search、GET /agentmemory/sessions等。
另外，命令退出时的汇总输出会区分四种状态（src/cli/connect/index.ts）：绿色✓ installed（含写入路径）、绿色✓ already wired、黄色⚠ stub（需手工安装）、红色✗ skipped。任何成功接入的汇总末尾都会提示下一步：安装 skills 让 Agent 知道何时调用工具。
与 skills 的分工
agentmemory connect只负责让工具可用（写入配置、暴露memory_*工具）；行为技能（remember、recall 等）需要单独安装：
npx skills add rohitg00/agentmemory用 SKILL.md 的原话："connect makes tools available; skills teach the agent when to use them."。完整技能清单与各自的使用方式见 plugin/skills 目录，每个技能都配有 SKILL.md 与（部分）EXAMPLES.md。
平台与版本注意
- Windows：请使用 WSL2。原生 Windows 上服务端可以运行，但
connect命令不受支持——src/cli/connect/index.ts 中有一个例外：当且仅当目标是copilot-cli时才允许在原生 Windows 上执行自动接线，其余情况都会提示手工安装（见官方文档的 manual install 步骤）。 - 适配器清单由代码自动生成：REFERENCE.md 中的表格由 scripts/skills/generate.ts 从 src/cli/connect/index.ts 生成，新增或移除适配器后需运行
npm run skills:gen重新生成，因此"文档即代码、代码即真相"，两者永远保持一致。
【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
