agentmemory connect 全解析为 21 种 AI 编码 Agent 一键接入持久记忆服务器【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryagentmemory connect是 agentmemory 项目基于真实世界基准构建的 AI 编码 Agent 持久记忆方案的核心接入命令它把内存服务器合并进宿主 Agent 的配置同时保留宿主已有的其他 MCP 服务器底层以 REST 为主协议、为仅支持 MCP 的宿主自动桥接 stdio MCP。读完本文你将掌握 connect 的完整适配器清单、命令行选项、底层接线原理配置合并、备份、校验、guideline 注入、验证与排障方法以及它与 skills 的分工边界可直接上手把 agentmemory 接入 Claude Code、Cursor、Codex、Gemini CLI 等主流编码 Agent。一、connect 的设计定位REST 为主、MCP 为桥在深入命令用法之前先理解 connect 的协议哲学。agentmemory 的内存服务运行在本地 daemon默认http://localhost:3111上REST API 是主交互面而绝大多数宿主编码 Agent 只认 MCP。因此 connect 的核心职责是agentmemory connect agent将内存服务器合并进宿主 Agent 的配置并保留任何已存在的服务器REST 是底层协议对于仅支持 MCP 的宿主适配器会接上 stdio MCP 桥接层。这一设计在 src/cli/connect/types.ts 中有明确体现每个适配器ConnectAdapter都带一个protocolNote字段说明该宿主走的是 REST hooks 还是 MCP 桥并在任何配置写入之前打印给用户category字段区分 native自带第一方插件/生命周期 hooks如 pi、OpenHuman、Claude Code与 mcp仅接 MCP 服务器如 Cursor、Zed。二、快速开始agentmemory connect claude-code # 或 cursor、codex、gemini-cli 等接线完成后需要重启宿主或执行其 MCP 重载例如在 Claude Code 中运行/mcp以让新服务器生效然后确认 Agent 的工具体列表中出现了 agentmemory 的工具。注意若只看到 7 个工具说明 MCP shim 未能连上服务器详见下文验证与故障排查一节。三、完整适配器清单21 个下表完整列出 REFERENCE 中由源码自动生成的 21 个适配器。该表来自 plugin/skills/agentmemory-agents/REFERENCE.md并由 scripts/skills/generate.ts 从 src/cli/connect/index.ts 中的ADAPTERS数组自动生成新增/删除适配器后需运行npm run skills:gen同步npm run skills:check可校验漂移。Agent命令名协议与说明Antigravityantigravity通过mcp_config.json走 MCP。Antigravity 取代了 Gemini CLI2026-06-18 起停服Antigravity CLI (agy)antigravity-cli通过~/.gemini/config/mcp_config.json走 MCPagy CLI非 Antigravity IDEIDE 用connect antigravity。agy 内/mcp斜杠命令可列出已配置服务器。传--with-hooks可同时安装原生~/.gemini/config/hooks.json自动捕获 hooksClaude Codeclaude-code走 MCP另有 hooks 可用见 plugin/hooks/hooks.jsonClinecline通过~/.cline/mcp.jsonCLI走 MCP。VS Code 用户可在 Cline Settings → MCP Servers → Edit JSON 中添加相同配置块Codex CLIcodex走 MCP。hooks 随 Codex 插件分发在 Codex Desktop 上还需传--with-hooks以安装全局 hooks.json 规避已知问题Continuecontinue通过~/.continue/config.yaml优先或config.json仅当无 yaml 时的遗留路径走 MCPGitHub Copilot CLIcopilot-cli走 MCP。建议同时安装插件以获得完整 hooks/skills 覆盖Cursorcursor走 MCPCursor 唯一支持的协议底层内存桥运行在:3111Devin CLIdevin通过用户配置走 MCP。新版 Devin CLI 会把 mcpServers 迁移进mcp_config.json。传--with-hooks启用原生自动捕获Droid (Factory.ai)droid通过~/.factory/mcp.json走 MCP。droid 内/mcp斜杠命令可列出服务器。传--with-hooks同时安装原生~/.factory/hooks.json自动捕获 hooksDeepSeek Harnessdsh通过$DSH_HOME/cordis.patch.yml每个 profile 都会加载的 home 级 patch 层走 MCP。工具显示为mcp__agentmemory__*。传--with-hooks可经 Harness 的 Claude Code hook 桥接自动捕获Gemini CLIgemini-cli走 MCPGemini CLI 唯一支持的协议底层内存桥运行在:3111Hermes Agenthermes走 MCP另有 hooks 可用见 integrations/hermes/README.mdKirokiro通过~/.kiro/settings/mcp.json用户级走 MCP工作区级覆盖位于.kiro/settings/mcp.jsonOpenClawopenclaw走 MCP另有 hooks 可用见 integrations/openclaw/README.mdOpenCodeopencode通过~/.config/opencode/opencode.json顶层mcp键走 MCP。要完整自动捕获还需安装 plugin/opencode/ 下的插件OpenHumanopenhuman使用原生 hooksREST API 位于:3111不需要 MCPpipi使用针对 REST API:3111的原生生命周期 hooksAgent 启动时 recall、结束时 capture、提供记忆工具不需要 MCPQwen Codeqwen通过~/.qwen/settings.json走 MCP。Qwen Code 的 hook 系统可另行接线Warpwarp通过~/.warp/.mcp.json走 MCP。若同时安装了 Claude Code 插件skills 会从.claude/skills/自动发现Zedzed通过~/.config/zed/settings.json键名context_servers走 MCP四、标准接入工作流SKILL.md 给出了三段式工作流这也是 Agent 判断当前宿主是谁、该跑哪条命令的决策依据检测调用者识别当前是哪个 Agent若无法识别默认回退到claude-code。执行接线按上表从 REFERENCE 中选取对应命令名运行agentmemory connect name。验证宿主应显示完整工具集且服务器处于运行状态只有 7 个工具说明 MCP shim 无法连上服务器见 plugin/skills/_shared/TROUBLESHOOTING.md。这条流程在 src/cli/connect/index.ts 的runConnect中逐层实现无位置参数时自动detect()本机已安装的 Agent 并弹出多选列表传--all时接线所有检测到的 Agent传单个名字时先resolveAdapter(name)解析未知名字会报错并列出全部支持项随后调用runAdapter执行检测 → 安装 → guideline 写入。五、命令行选项详解parseFlags见 src/cli/connect/index.ts支持以下选项可组合使用选项作用--dry-run预演模式只打印将写入哪个配置文件的哪个键不落盘用于安全审查--force强制重装。默认行为是检测到已有agentmemory条目时直接返回already-wired不再写入加此选项则覆盖重写--all自动接线本机检测到的全部受支持 Agent跳过未安装的--with-hooks在 MCP 接线之外额外安装宿主的原生自动捕获 hooks仅对带 hooks 安装器的适配器生效见下文--no-guidelines关闭记忆使用 guideline自动写入默认开启见下文ConnectOptions的类型定义在 src/cli/connect/types.tswithHooks覆盖 Codex~/.codex/hooks.json、Claude Code~/.claude/settings.json、Droid~/.factory/hooks.json、DeepSeek Harness$DSH_HOME下的 hooks 配置等guidelines默认true。六、connect 的底层执行机制合并、备份、校验以 Claude Code 适配器src/cli/connect/claude-code.ts为例可以看到每个适配器安装的标准流程这也是runAdapter通用骨架的体现检测detect()检查宿主配置文件目录是否存在Claude Code 检查~/.claude是否存在。合并而非覆盖读取~/.claude.json将其现有mcpServers对象浅拷贝后仅新增/替换agentmemory一个键。这正是 SKILL.md 强调preserves any existing servers的代码依据。对于 Zed 这类非标准键名宿主json-mcp-adapter.ts 通过wrapperKey参数支持context_serversDroid 通过extraEntryFields额外注入type: stdio。备份写入前把原配置复制到~/.agentmemory/backups/backupFile见 src/cli/connect/util.ts文件名带 ISO 时间戳如claude-code-2026-09-10T01-17-41.000Z.json。原子写入writeJsonAtomic先写临时文件再rename避免写一半损坏配置。写后校验重新读取配置文件确认mcpServers.agentmemory确实存在entryMatches检查 command 为npx且 args 含agentmemory/mcp校验失败则返回verification-failed并跳过。安装结果通过四种kind汇总输出summarizeinstalled绿色 ✓ 写入路径、already-wired已接线、stub需手动安装黄色 ⚠、skipped未检测到或异常红色 ✗。接线成功后会提示下一步Next: install agentmemorys 17 skills into the same agent(s) so they know when to call the tools: npx skills add rohitg00/agentmemory -y七、MCP 桥接块环境变量默认值的学问所有 JSON MCP 类适配器写入的agentmemory条目统一来自AGENTMEMORY_MCP_BLOCKsrc/cli/connect/util.ts{ 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 展开让被接线的 MCP 条目继承用户 shell 中导出的AGENTMEMORY_URL/AGENTMEMORY_SECRET/AGENTMEMORY_TOOLS变量未设置时也不至于解析失败。源码注释记录了历史教训早期${VAR}形式在用户未导出环境变量时会导致 Claude Code 静默丢弃该服务器按 Claude Code MCP 文档必需环境变量无默认值时会解析失败。默认值即文档化运行时localhost:3111无鉴权、全部工具。这样一个条目同时覆盖本地与远程Kubernetes/反向代理部署。有一个值得注意的例外OpenCode 适配器src/cli/connect/opencode.ts故意不写environment块因为 OpenCode 不展开 shell 风格${VAR:-default}原样写入会覆盖用户真实环境stdio 子进程继承 shell 环境agentmemory/mcpshim 自身会对未设置变量取默认值。这体现了每个适配器针对宿主差异的精细处理。八、guideline 注入让无 hooks 的 Agent 主动用记忆runAdapter在 MCP/hooks 接线成功后还会把一段记忆使用指南写入宿主的原生规则文件writeGuideline见 src/cli/connect/guidelines.ts从而让没有自动捕获 hooks 的 Agent 也能主动调用记忆工具。指南正文如下你有通过 agentmemory MCP 服务器的持久长期记忆。工具memory_recall、memory_smart_search、memory_save、memory_sessions。任务开始时先调用memory_recall或memory_smart_search加载相关历史决策、修复与偏好不要重复向用户提问。学到持久性知识决策、修复、坑、用户偏好、项目约定时调用memory_save持久化。优先回忆而非重新推导保存简洁可复用的事实而非转录。针对不同宿主的规则机制guideline 有四种落盘格式block在共享指令文件中插入!-- agentmemory:start --/!-- agentmemory:end --标记块幂等更新只动自己的块保留用户内容检测到孤立/错位标记时不动文件以防误删用户内容用于 Zed~/.config/zed/AGENTS.md、Warp项目AGENTS.md、Gemini CLI~/.gemini/GEMINI.md、Qwen~/.qwen/QWEN.md、OpenCode、Droid、Antigravity、Copilot CLI 等mdcCursor 项目规则写入.cursor/rules/agentmemory.mdcfrontmatter 带alwaysApply: trueCursor 的用户规则仅 UI 管理无全局文件steeringKiro steering 文件写入.kiro/steering/agentmemory.mdfrontmatter 带inclusion: alwaysrule独立常开 Markdown 规则文件用于 Cline.clinerules/agentmemory.md和 Continue.continue/rules/00-agentmemory.md。所有目标路径与格式均按各 Agent 官方文档核实源码中逐条注明source。Claude Code / Codex 不在其列因为它们已通过生命周期 hooks 自动捕获。该步骤是 best-effort失败不会导致整个 connect 失败。九、--with-hookshooks 与 MCP 的联动对支持原生 hooks 的宿主--with-hooks会在 MCP 接线之外额外安装自动捕获 hooks。以 Claude Code 为例其 hooks 回退安装器src/cli/connect/claude-code.ts 中的installClaudeHooks把随包分发的 plugin/hooks/hooks.json 合并进~/.claude/settings.json的顶层hooks字段并将${CLAUDE_PLUGIN_ROOT}展开为绝对路径。hooks.json 注册了 12 个生命周期事件SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、PreCompact、SubagentStart、SubagentStop、Notification、TaskCompleted、Stop、SessionEnd对应 plugin/scripts/ 下的各 mjs 脚本实现观察自动捕获。这一回退方案用于 agentmemory 未通过/plugin marketplace add安装的场景issue #508 的规避重装时会剥离指向本插件scripts/目录的旧条目、保留用户自己的 hooks升级 agentmemory 后重跑connect claude-code --with-hooks即可刷新这些绝对路径。十、原生 REST 类宿主pi 与 OpenHuman不是所有宿主都走 MCP。pi适配器src/cli/connect/pi.ts走原生生命周期 hooks REST APIMCP 不是必需它把随包分发的扩展integrations/pi/index.ts、security.ts即 integrations/pi/ 目录复制到~/.pi/agent/extensions/agentmemory/——pi 会自动发现该目录下的扩展因此无需改动任何 settings.json。运行中的 pi 可用/reload加载并用/agentmemory-status验证。安装前后会做内容比对与写后校验逐字节验证与随包扩展一致。OpenHuman适配器src/cli/connect/openhuman.ts目前返回stub仓库中尚无integrations/openhuman/预期接线方式是:3111REST 代理 OpenHuman 侧 Memory trait 实现待集成落地后自动完成。十一、验证与故障排查接线完成后按 SKILL.md 验证宿主应显示完整工具集且服务器运行中。若memory_*工具不出现说明 stdio MCP shim 从未启动表现为只有 7 个工具按 plugin/skills/_shared/TROUBLESHOOTING.md 依次排查在宿主中运行/plugin list确认agentmemory处于启用状态重启宿主——插件的.mcp.json只在启动时读取新装/重启用插件不会在会话中途注册工具检查/mcp确认agentmemory服务器显示为活跃连接。若 MCP 工具始终不可用但 daemon 在运行可降级直连 REST API设置AGENTMEMORY_URL默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才加Authorization: Bearer $AGENTMEMORY_SECRET默认 localhost daemon 是开放的乱加头反而会被拒绝。各 skill 对应的 REST 端点SkillREST 调用rememberPOST /agentmemory/rememberrecallPOST /agentmemory/smart-searchrecapGET /agentmemory/sessionsPOST /agentmemory/smart-searchhandoffGET /agentmemory/sessionsPOST /agentmemory/smart-searchsession-historyGET /agentmemory/sessionscommit-contextGET /agentmemory/session/by-commit?shashacommit-historyGET /agentmemory/commits所有查询参数需 URL 编码注意 daemon 只在启动时读取.mcp.json因此任何端口或鉴权变更都需要先重启 daemon两条通道MCP 与 REST才能看到新配置。十二、connect 与 skills 的分工SKILL.md 明确指出一条重要边界connect让工具可用skills 教 Agent 何时使用它们。动作类 skillsremember、recall 等通过npx skills add rohitg00/agentmemory单独安装connect只负责把内存服务器接入宿主配置。二者配合的完整链路是connect 接线 → 工具出现在宿主中 → skills 指导 Agent 在合适的时机调用memory_recall/memory_save从而实现接得上、用得好。相关的 mcp-tools、rest-api、hooks 技能文档分别位于 plugin/skills/agentmemory-mcp-tools/、plugin/skills/agentmemory-rest-api/、plugin/skills/agentmemory-hooks/。十三、平台与测试保障Windows 支持SKILL.md 与 src/cli/connect/index.ts 一致——Windows 上请使用 WSL2原生 Windows 可以运行服务器但不支持connect唯一的例外是connect copilot-cli它在 Windows 上会用cmd.exe /d /s /c npx ...包装启动见 src/cli/connect/util.ts 的AGENTMEMORY_COPILOT_MCP_BLOCK。其余场景下源码会直接打印Windows: manual install required并退出。测试覆盖test/cli-connect.test.ts 覆盖了 connect 调度器dispatch、Claude Code 适配器mock 文件系统、OpenCode 适配器、Copilot CLI 适配器mock 文件系统以及 stub 类适配器Hermes、OpenHuman的日志与返回行为可作为理解各适配器行为边界的参考实现。适配器清单由 scripts/skills/generate.ts 与 REFERENCE.md 保持同步npm run skills:gen生成、npm run skills:check校验确保文档中的 21 个适配器与源码ADAPTERS数组永远一致。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 14:58:14 · 阅读 1.2k agentmemory connect 全解析：为 21 种 AI 编码 Agent 一键接入持久记忆服务器
agentmemory connect 全解析为 21 种 AI 编码 Agent 一键接入持久记忆服务器【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryagentmemory connect是 agentmemory 项目基于真实世界基准构建的 AI 编码 Agent 持久记忆方案的核心接入命令它把内存服务器合并进宿主 Agent 的配置同时保留宿主已有的其他 MCP 服务器底层以 REST 为主协议、为仅支持 MCP 的宿主自动桥接 stdio MCP。读完本文你将掌握 connect 的完整适配器清单、命令行选项、底层接线原理配置合并、备份、校验、guideline 注入、验证与排障方法以及它与 skills 的分工边界可直接上手把 agentmemory 接入 Claude Code、Cursor、Codex、Gemini CLI 等主流编码 Agent。一、connect 的设计定位REST 为主、MCP 为桥在深入命令用法之前先理解 connect 的协议哲学。agentmemory 的内存服务运行在本地 daemon默认http://localhost:3111上REST API 是主交互面而绝大多数宿主编码 Agent 只认 MCP。因此 connect 的核心职责是agentmemory connect agent将内存服务器合并进宿主 Agent 的配置并保留任何已存在的服务器REST 是底层协议对于仅支持 MCP 的宿主适配器会接上 stdio MCP 桥接层。这一设计在 src/cli/connect/types.ts 中有明确体现每个适配器ConnectAdapter都带一个protocolNote字段说明该宿主走的是 REST hooks 还是 MCP 桥并在任何配置写入之前打印给用户category字段区分 native自带第一方插件/生命周期 hooks如 pi、OpenHuman、Claude Code与 mcp仅接 MCP 服务器如 Cursor、Zed。二、快速开始agentmemory connect claude-code # 或 cursor、codex、gemini-cli 等接线完成后需要重启宿主或执行其 MCP 重载例如在 Claude Code 中运行/mcp以让新服务器生效然后确认 Agent 的工具体列表中出现了 agentmemory 的工具。注意若只看到 7 个工具说明 MCP shim 未能连上服务器详见下文验证与故障排查一节。三、完整适配器清单21 个下表完整列出 REFERENCE 中由源码自动生成的 21 个适配器。该表来自 plugin/skills/agentmemory-agents/REFERENCE.md并由 scripts/skills/generate.ts 从 src/cli/connect/index.ts 中的ADAPTERS数组自动生成新增/删除适配器后需运行npm run skills:gen同步npm run skills:check可校验漂移。Agent命令名协议与说明Antigravityantigravity通过mcp_config.json走 MCP。Antigravity 取代了 Gemini CLI2026-06-18 起停服Antigravity CLI (agy)antigravity-cli通过~/.gemini/config/mcp_config.json走 MCPagy CLI非 Antigravity IDEIDE 用connect antigravity。agy 内/mcp斜杠命令可列出已配置服务器。传--with-hooks可同时安装原生~/.gemini/config/hooks.json自动捕获 hooksClaude Codeclaude-code走 MCP另有 hooks 可用见 plugin/hooks/hooks.jsonClinecline通过~/.cline/mcp.jsonCLI走 MCP。VS Code 用户可在 Cline Settings → MCP Servers → Edit JSON 中添加相同配置块Codex CLIcodex走 MCP。hooks 随 Codex 插件分发在 Codex Desktop 上还需传--with-hooks以安装全局 hooks.json 规避已知问题Continuecontinue通过~/.continue/config.yaml优先或config.json仅当无 yaml 时的遗留路径走 MCPGitHub Copilot CLIcopilot-cli走 MCP。建议同时安装插件以获得完整 hooks/skills 覆盖Cursorcursor走 MCPCursor 唯一支持的协议底层内存桥运行在:3111Devin CLIdevin通过用户配置走 MCP。新版 Devin CLI 会把 mcpServers 迁移进mcp_config.json。传--with-hooks启用原生自动捕获Droid (Factory.ai)droid通过~/.factory/mcp.json走 MCP。droid 内/mcp斜杠命令可列出服务器。传--with-hooks同时安装原生~/.factory/hooks.json自动捕获 hooksDeepSeek Harnessdsh通过$DSH_HOME/cordis.patch.yml每个 profile 都会加载的 home 级 patch 层走 MCP。工具显示为mcp__agentmemory__*。传--with-hooks可经 Harness 的 Claude Code hook 桥接自动捕获Gemini CLIgemini-cli走 MCPGemini CLI 唯一支持的协议底层内存桥运行在:3111Hermes Agenthermes走 MCP另有 hooks 可用见 integrations/hermes/README.mdKirokiro通过~/.kiro/settings/mcp.json用户级走 MCP工作区级覆盖位于.kiro/settings/mcp.jsonOpenClawopenclaw走 MCP另有 hooks 可用见 integrations/openclaw/README.mdOpenCodeopencode通过~/.config/opencode/opencode.json顶层mcp键走 MCP。要完整自动捕获还需安装 plugin/opencode/ 下的插件OpenHumanopenhuman使用原生 hooksREST API 位于:3111不需要 MCPpipi使用针对 REST API:3111的原生生命周期 hooksAgent 启动时 recall、结束时 capture、提供记忆工具不需要 MCPQwen Codeqwen通过~/.qwen/settings.json走 MCP。Qwen Code 的 hook 系统可另行接线Warpwarp通过~/.warp/.mcp.json走 MCP。若同时安装了 Claude Code 插件skills 会从.claude/skills/自动发现Zedzed通过~/.config/zed/settings.json键名context_servers走 MCP四、标准接入工作流SKILL.md 给出了三段式工作流这也是 Agent 判断当前宿主是谁、该跑哪条命令的决策依据检测调用者识别当前是哪个 Agent若无法识别默认回退到claude-code。执行接线按上表从 REFERENCE 中选取对应命令名运行agentmemory connect name。验证宿主应显示完整工具集且服务器处于运行状态只有 7 个工具说明 MCP shim 无法连上服务器见 plugin/skills/_shared/TROUBLESHOOTING.md。这条流程在 src/cli/connect/index.ts 的runConnect中逐层实现无位置参数时自动detect()本机已安装的 Agent 并弹出多选列表传--all时接线所有检测到的 Agent传单个名字时先resolveAdapter(name)解析未知名字会报错并列出全部支持项随后调用runAdapter执行检测 → 安装 → guideline 写入。五、命令行选项详解parseFlags见 src/cli/connect/index.ts支持以下选项可组合使用选项作用--dry-run预演模式只打印将写入哪个配置文件的哪个键不落盘用于安全审查--force强制重装。默认行为是检测到已有agentmemory条目时直接返回already-wired不再写入加此选项则覆盖重写--all自动接线本机检测到的全部受支持 Agent跳过未安装的--with-hooks在 MCP 接线之外额外安装宿主的原生自动捕获 hooks仅对带 hooks 安装器的适配器生效见下文--no-guidelines关闭记忆使用 guideline自动写入默认开启见下文ConnectOptions的类型定义在 src/cli/connect/types.tswithHooks覆盖 Codex~/.codex/hooks.json、Claude Code~/.claude/settings.json、Droid~/.factory/hooks.json、DeepSeek Harness$DSH_HOME下的 hooks 配置等guidelines默认true。六、connect 的底层执行机制合并、备份、校验以 Claude Code 适配器src/cli/connect/claude-code.ts为例可以看到每个适配器安装的标准流程这也是runAdapter通用骨架的体现检测detect()检查宿主配置文件目录是否存在Claude Code 检查~/.claude是否存在。合并而非覆盖读取~/.claude.json将其现有mcpServers对象浅拷贝后仅新增/替换agentmemory一个键。这正是 SKILL.md 强调preserves any existing servers的代码依据。对于 Zed 这类非标准键名宿主json-mcp-adapter.ts 通过wrapperKey参数支持context_serversDroid 通过extraEntryFields额外注入type: stdio。备份写入前把原配置复制到~/.agentmemory/backups/backupFile见 src/cli/connect/util.ts文件名带 ISO 时间戳如claude-code-2026-09-10T01-17-41.000Z.json。原子写入writeJsonAtomic先写临时文件再rename避免写一半损坏配置。写后校验重新读取配置文件确认mcpServers.agentmemory确实存在entryMatches检查 command 为npx且 args 含agentmemory/mcp校验失败则返回verification-failed并跳过。安装结果通过四种kind汇总输出summarizeinstalled绿色 ✓ 写入路径、already-wired已接线、stub需手动安装黄色 ⚠、skipped未检测到或异常红色 ✗。接线成功后会提示下一步Next: install agentmemorys 17 skills into the same agent(s) so they know when to call the tools: npx skills add rohitg00/agentmemory -y七、MCP 桥接块环境变量默认值的学问所有 JSON MCP 类适配器写入的agentmemory条目统一来自AGENTMEMORY_MCP_BLOCKsrc/cli/connect/util.ts{ 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 展开让被接线的 MCP 条目继承用户 shell 中导出的AGENTMEMORY_URL/AGENTMEMORY_SECRET/AGENTMEMORY_TOOLS变量未设置时也不至于解析失败。源码注释记录了历史教训早期${VAR}形式在用户未导出环境变量时会导致 Claude Code 静默丢弃该服务器按 Claude Code MCP 文档必需环境变量无默认值时会解析失败。默认值即文档化运行时localhost:3111无鉴权、全部工具。这样一个条目同时覆盖本地与远程Kubernetes/反向代理部署。有一个值得注意的例外OpenCode 适配器src/cli/connect/opencode.ts故意不写environment块因为 OpenCode 不展开 shell 风格${VAR:-default}原样写入会覆盖用户真实环境stdio 子进程继承 shell 环境agentmemory/mcpshim 自身会对未设置变量取默认值。这体现了每个适配器针对宿主差异的精细处理。八、guideline 注入让无 hooks 的 Agent 主动用记忆runAdapter在 MCP/hooks 接线成功后还会把一段记忆使用指南写入宿主的原生规则文件writeGuideline见 src/cli/connect/guidelines.ts从而让没有自动捕获 hooks 的 Agent 也能主动调用记忆工具。指南正文如下你有通过 agentmemory MCP 服务器的持久长期记忆。工具memory_recall、memory_smart_search、memory_save、memory_sessions。任务开始时先调用memory_recall或memory_smart_search加载相关历史决策、修复与偏好不要重复向用户提问。学到持久性知识决策、修复、坑、用户偏好、项目约定时调用memory_save持久化。优先回忆而非重新推导保存简洁可复用的事实而非转录。针对不同宿主的规则机制guideline 有四种落盘格式block在共享指令文件中插入!-- agentmemory:start --/!-- agentmemory:end --标记块幂等更新只动自己的块保留用户内容检测到孤立/错位标记时不动文件以防误删用户内容用于 Zed~/.config/zed/AGENTS.md、Warp项目AGENTS.md、Gemini CLI~/.gemini/GEMINI.md、Qwen~/.qwen/QWEN.md、OpenCode、Droid、Antigravity、Copilot CLI 等mdcCursor 项目规则写入.cursor/rules/agentmemory.mdcfrontmatter 带alwaysApply: trueCursor 的用户规则仅 UI 管理无全局文件steeringKiro steering 文件写入.kiro/steering/agentmemory.mdfrontmatter 带inclusion: alwaysrule独立常开 Markdown 规则文件用于 Cline.clinerules/agentmemory.md和 Continue.continue/rules/00-agentmemory.md。所有目标路径与格式均按各 Agent 官方文档核实源码中逐条注明source。Claude Code / Codex 不在其列因为它们已通过生命周期 hooks 自动捕获。该步骤是 best-effort失败不会导致整个 connect 失败。九、--with-hookshooks 与 MCP 的联动对支持原生 hooks 的宿主--with-hooks会在 MCP 接线之外额外安装自动捕获 hooks。以 Claude Code 为例其 hooks 回退安装器src/cli/connect/claude-code.ts 中的installClaudeHooks把随包分发的 plugin/hooks/hooks.json 合并进~/.claude/settings.json的顶层hooks字段并将${CLAUDE_PLUGIN_ROOT}展开为绝对路径。hooks.json 注册了 12 个生命周期事件SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、PreCompact、SubagentStart、SubagentStop、Notification、TaskCompleted、Stop、SessionEnd对应 plugin/scripts/ 下的各 mjs 脚本实现观察自动捕获。这一回退方案用于 agentmemory 未通过/plugin marketplace add安装的场景issue #508 的规避重装时会剥离指向本插件scripts/目录的旧条目、保留用户自己的 hooks升级 agentmemory 后重跑connect claude-code --with-hooks即可刷新这些绝对路径。十、原生 REST 类宿主pi 与 OpenHuman不是所有宿主都走 MCP。pi适配器src/cli/connect/pi.ts走原生生命周期 hooks REST APIMCP 不是必需它把随包分发的扩展integrations/pi/index.ts、security.ts即 integrations/pi/ 目录复制到~/.pi/agent/extensions/agentmemory/——pi 会自动发现该目录下的扩展因此无需改动任何 settings.json。运行中的 pi 可用/reload加载并用/agentmemory-status验证。安装前后会做内容比对与写后校验逐字节验证与随包扩展一致。OpenHuman适配器src/cli/connect/openhuman.ts目前返回stub仓库中尚无integrations/openhuman/预期接线方式是:3111REST 代理 OpenHuman 侧 Memory trait 实现待集成落地后自动完成。十一、验证与故障排查接线完成后按 SKILL.md 验证宿主应显示完整工具集且服务器运行中。若memory_*工具不出现说明 stdio MCP shim 从未启动表现为只有 7 个工具按 plugin/skills/_shared/TROUBLESHOOTING.md 依次排查在宿主中运行/plugin list确认agentmemory处于启用状态重启宿主——插件的.mcp.json只在启动时读取新装/重启用插件不会在会话中途注册工具检查/mcp确认agentmemory服务器显示为活跃连接。若 MCP 工具始终不可用但 daemon 在运行可降级直连 REST API设置AGENTMEMORY_URL默认http://localhost:3111仅当设置了AGENTMEMORY_SECRET时才加Authorization: Bearer $AGENTMEMORY_SECRET默认 localhost daemon 是开放的乱加头反而会被拒绝。各 skill 对应的 REST 端点SkillREST 调用rememberPOST /agentmemory/rememberrecallPOST /agentmemory/smart-searchrecapGET /agentmemory/sessionsPOST /agentmemory/smart-searchhandoffGET /agentmemory/sessionsPOST /agentmemory/smart-searchsession-historyGET /agentmemory/sessionscommit-contextGET /agentmemory/session/by-commit?shashacommit-historyGET /agentmemory/commits所有查询参数需 URL 编码注意 daemon 只在启动时读取.mcp.json因此任何端口或鉴权变更都需要先重启 daemon两条通道MCP 与 REST才能看到新配置。十二、connect 与 skills 的分工SKILL.md 明确指出一条重要边界connect让工具可用skills 教 Agent 何时使用它们。动作类 skillsremember、recall 等通过npx skills add rohitg00/agentmemory单独安装connect只负责把内存服务器接入宿主配置。二者配合的完整链路是connect 接线 → 工具出现在宿主中 → skills 指导 Agent 在合适的时机调用memory_recall/memory_save从而实现接得上、用得好。相关的 mcp-tools、rest-api、hooks 技能文档分别位于 plugin/skills/agentmemory-mcp-tools/、plugin/skills/agentmemory-rest-api/、plugin/skills/agentmemory-hooks/。十三、平台与测试保障Windows 支持SKILL.md 与 src/cli/connect/index.ts 一致——Windows 上请使用 WSL2原生 Windows 可以运行服务器但不支持connect唯一的例外是connect copilot-cli它在 Windows 上会用cmd.exe /d /s /c npx ...包装启动见 src/cli/connect/util.ts 的AGENTMEMORY_COPILOT_MCP_BLOCK。其余场景下源码会直接打印Windows: manual install required并退出。测试覆盖test/cli-connect.test.ts 覆盖了 connect 调度器dispatch、Claude Code 适配器mock 文件系统、OpenCode 适配器、Copilot CLI 适配器mock 文件系统以及 stub 类适配器Hermes、OpenHuman的日志与返回行为可作为理解各适配器行为边界的参考实现。适配器清单由 scripts/skills/generate.ts 与 REFERENCE.md 保持同步npm run skills:gen生成、npm run skills:check校验确保文档中的 21 个适配器与源码ADAPTERS数组永远一致。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考