agentmemory 独立 MCP 服务器agentmemory/mcp 薄封装包安装、接入与运行原理全解析【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读agentmemory/mcp是 agentmemory 项目发布的一个独立 MCPModel Context Protocol服务器包它本身不包含任何业务实现而是把主包agentmemory/agentmemory的独立 MCP 入口点重新暴露出来让任何 MCP 客户端Claude Desktop、OpenClaw、Cursor、Codex 等都能通过一行npx -y agentmemory/mcp直接接入 agentmemory 的持久记忆能力。读完本文你将掌握该包的安装接入方式、两种运行模式代理模式与本地降级模式的原理、全部可调环境变量以及背后的实现与测试细节。这个包是什么一个刻意保持薄的转发封装agentmemory/mcp在官方描述中被明确定义为thin shim package薄封装/垫片包。所谓薄指的是它不复制、不内嵌任何记忆检索或向量索引逻辑只做一件事把主包agentmemory/agentmemory中编译产物dist/standalone.mjs的独立 MCP 入口点重新暴露出来。它解决的是 MCP 生态里一个很现实的接入问题MCP 客户端的配置里通常只写command和args如果直接依赖完整主包客户端需要先安装整个 agentmemory 才能启动 MCP 服务。而有了这个独立包MCP 客户端配置里写npx agentmemory/mcp就能开箱即用无需预先手动安装完整包——这正是packages/mcp/README.md中 work out of the box without installing the full package first 的承诺。从源码可以看到这个转发是字面意义上的入口文件 packages/mcp/bin.mjs 的全部逻辑就是动态导入主包入口并在加载失败时给出明确诊断信息#!/usr/bin/env node import(agentmemory/agentmemory/dist/standalone.mjs).catch((err) { console.error( [agentmemory/mcp] Failed to load standalone entrypoint from agentmemory/agentmemory., ); console.error( [agentmemory/mcp] Try installing manually: npm i -g agentmemory/agentmemory, ); console.error(err instanceof Error ? err.stack || err.message : String(err)); process.exit(1); });相应地packages/mcp/package.json 声明了依赖agentmemory/agentmemory: ~0.9.0并把bin字段映射到./bin.mjs同时要求 Node.js 版本20.0.0。也就是说npm 安装该包时会自动带上主包依赖agentmemory-mcp这个命令名也会被注册到 PATH 中。快速开始一条命令拉起独立 MCP 服务器最直接的启动方式是在终端执行首次运行会由npx -y自动下载npx -y agentmemory/mcp启动后会在 stderr 输出类似下面的标识信息源码见 src/mcp/standalone.ts[agentmemory/mcp] Standalone MCP server vversion starting...随后进程进入 stdio 监听状态等待 MCP 客户端通过标准输入输出进行 JSON-RPC 2.0 通信。接入任意 MCP 客户端文档给出了标准的 MCP 客户端配置片段适用于 Claude Desktop、OpenClaw、Cursor、Codex 等支持mcpServers配置的客户端{ mcpServers: { agentmemory: { command: npx, args: [-y, agentmemory/mcp] } } }配置要点说明command: npx配合args: [-y, agentmemory/mcp]-y让 npx 自动确认安装保证首次运行时不会因为交互提示而卡住服务名本例为agentmemory可以自定义客户端会用它在工具面板中分组展示所有memory_*工具若客户端配置系统会自动展开\${VAR}形式的占位符也可以在环境变量中注入AGENTMEMORY_URL等参数详见下文环境变量章节。等效命令直接调用主包入口如果你已经在本地安装了agentmemory/agentmemory也可以跳过 shim 包直接调用同一个独立入口npx agentmemory/agentmemory mcp官方文档明确说明Both commands do the same thing.两条命令做的事情完全一样。二者殊途同归shim 包转发到主包的dist/standalone.mjs而npx agentmemory/agentmemory mcp也是解析到同一个入口因此接入效果完全等价。运行时原理代理模式与本地降级模式尽管 shim 包本身很薄但它转发到的独立入口 src/mcp/standalone.ts 是一个功能完整的 MCP 服务器其核心设计是**先探活再决定模式**启动时或首次工具调用时通过resolveHandle()对AGENTMEMORY_URL指向的 agentmemory 服务发起GET /agentmemory/livez健康探针实现见 src/mcp/rest-proxy.ts探针成功 →代理模式proxystdio 收到的 MCP 工具调用被转成 HTTP 请求转发给后台 agentmemory 服务器从而获得完整的 54 个工具面探针失败 →本地降级模式local fallback使用内置的InMemoryKV提供 7 个核心工具的简化实现保证没有后台服务也能先用起来。启动日志会明确告知当前处于哪种模式src/mcp/standalone.ts[agentmemory/mcp] proxying to agentmemory server at http://localhost:3111或[agentmemory/mcp] no server reachable at http://localhost:3111; running reduced LOCAL FALLBACK with 7 of N tools. Start npx agentmemory/agentmemory (and point AGENTMEMORY_URL at it) to unlock all N tools.代理模式下的完整工具面在代理模式下shim 不再局限于自身内置的工具清单对未内置实现的所有工具会通过POST /agentmemory/mcp/call泛化转发给后台服务器执行handleProxyGeneric见 src/mcp/standalone.ts工具清单也优先通过GET /agentmemory/mcp/tools从服务器拉取。这样非 Claude 类客户端也能访问 lessons、sentinels、slots、signals、graph 等全部高级工具而不会被 shim 内置的 7 个工具限制住。完整的工具注册表定义在 src/mcp/tools-registry.ts按版本演进划分为多组分组代表工具覆盖能力CORE_TOOLS14 个memory_recall、memory_save、memory_smart_search、memory_compress_file、memory_vision_search、memory_timeline、memory_relations、memory_commits等记忆的保存、召回、混合检索、文件历史、时间线、关系图谱V040_TOOLSmemory_consolidate、memory_graph_query、memory_team_share、memory_audit、memory_governance_delete、memory_snapshot_create等四层记忆整合、知识图谱、团队共享、审计与治理V050_TOOLSmemory_action_create、memory_frontier、memory_next、memory_lease、memory_signal_send、memory_checkpoint、memory_mesh_sync等可执行动作、租约、信号、检查点、多实例同步V051_TOOLSmemory_sentinel_create、memory_sketch_create、memory_crystallize、memory_diagnose、memory_facet_tag等事件驱动哨兵、探索草图、诊断自愈、多维标签V061_TOOLSmemory_verify记忆溯源验证V070_TOOLSmemory_lesson_save、memory_lesson_recall、memory_obsidian_export等经验教训与 Obsidian 导出V073_TOOLSmemory_reflect、memory_insight_list图谱反思与高阶洞察V010_SLOTS_TOOLSmemory_slot_list、memory_slot_get、memory_slot_append等可编辑、有大小限制的插槽记忆注工具清单会随版本持续演进具体以当前仓库 src/mcp/tools-registry.ts 中getAllTools()的实际输出为准。本地降级模式的 7 个内置工具本地降级模式由IMPLEMENTED_TOOLS集合圈定src/mcp/standalone.ts只包含 7 个工具数据存储依赖 src/mcp/in-memory-kv.ts 实现的InMemoryKVmemory_save写入记忆自动生成mem_前缀 ID标题取内容前 80 字符默认strength: 7、version: 1、isLatest: true写入后立即persist()落盘memory_recall / memory_smart_search在本地降级模式下均退化为全量子串匹配——把标题、内容、文件、概念、会话 ID 拼接后按空格分词逐词匹配结果上限由limit控制默认 10上限 100memory_sessions列出已保存的会话默认上限 20memory_export导出全部记忆与会话的 JSON含版本号memory_audit查询审计日志默认上限 50memory_governance_delete按 ID 数组删除记忆并记录 reason静默跳过不存在的 ID。本地数据默认持久化到~/.agentmemory/standalone.json路径解析见 src/config.ts可通过STANDALONE_PERSIST_PATH环境变量覆盖。进程收到SIGINT/SIGTERM时会先persist()再退出避免数据丢失src/mcp/standalone.ts。探针缓存与失效机制resolveHandle()会缓存探测结果本地模式下缓存 30 秒LOCAL_MODE_TTL_MS后自动重新探测代理模式下缓存长期有效一旦代理调用失败HTTP 非 2xx 或超时会调用invalidateHandle()清空缓存并回退到本地 KV。这意味着后台服务器中途宕机时MCP 连接不会立即崩掉而是平滑降级。关键环境变量一览结合 src/mcp/rest-proxy.ts 与 src/mcp/standalone.ts以下是接入时最常用到的环境变量环境变量默认值作用AGENTMEMORY_URLhttp://localhost:3111后台 agentmemory 服务器地址决定代理模式的目标。若值为未展开的\${AGENTMEMORY_URL}字面占位符会被识别并回退到默认值AGENTMEMORY_SECRET无后台服务器的 Bearer 鉴权密钥设置后所有代理请求自动携带authorization: Bearer secretAGENTMEMORY_FORCE_PROXY无设为1或true时跳过 livez 探针强制走代理模式AGENTMEMORY_PROBE_TIMEOUT_MS2000livez 健康探针超时毫秒用于适配慢启动的服务器AGENTMEMORY_TOOLSall设为core时仅暴露 8 个核心工具ESSENTIAL_TOOLS见 src/mcp/tools-registry.tsAGENTMEMORY_DEBUG无设为1或true时输出tools/list的详细调试日志STANDALONE_PERSIST_PATH~/.agentmemory/standalone.json本地降级模式的数据持久化文件路径其中AGENTMEMORY_URL与AGENTMEMORY_SECRET的解析在 src/mcp/rest-proxy.ts 中完成resolveEnvOrEmpty会剥离未展开的\${VAR}占位符——这是为了兼容那些不会展开占位符的 MCP 宿主如果不剥离字面量${AGENTMEMORY_URL}会被当作真实地址请求导致 DNS 解析失败。为什么这个包存在npm 命名冲突的来龙去脉官方文档packages/mcp/README.md记载了这段历史最初计划以不带 scope 的agentmemory-mcp包名发布但 npm 的name-similarity policy名称相似性策略因为已存在一个无关包agent-memory-mcp而拒绝了该名称。于是项目改在agentmemoryscope 下发布既绕开了命名冲突又保留了独立专用包的使用体验——npx agentmemory/mcp只比npx agentmemory-mcp多一个字符且能在 npm 官方 registry 上正常工作。这一设计还体现在 packages/mcp/package.json 的publishConfig中access: public保证包对公众可见provenance: true为发布产物开启供应链来源证明。MCP 协议与传输层实现独立入口的 stdio 传输层实现在 src/mcp/transport.ts它严格遵循 JSON-RPC 2.0 与 MCP 传输契约双格式解析消息解析器createMessageParser同时支持两类 stdio 帧——Content-Length头定长的 framed 格式以及传统换行分隔的 JSON Lines 格式并能自动识别客户端当前使用的格式isFramed()决定响应回包格式通知不发响应按 JSON-RPC 2.0 规范无id的请求视为通知服务器不得回包。这一点在注释中特别提到是为兼容 Codex CLI 等严格客户端相关 issue 编号 agentmemory#129错误码规范解析失败返回-32700 Parse error非法请求返回-32600 Invalid Request处理器异常返回-32603协议版本协商initialize阶段支持2025-11-25、2025-06-18、2025-03-26、2024-11-05四个版本客户端请求的版本在支持列表内则原样回显否则回退到最新支持版本src/mcp/standalone.ts。验证与测试覆盖仓库用 test/mcp-standalone.test.ts 对该入口做了较完整的单元测试可作为理解行为的活文档协议协商支持版本回显、不支持版本回退、缺失版本回退等四种场景参数校验memory_save缺少content时抛错、memory_smart_search拒绝空查询防止误触发全量匹配、parseLimit把恶意/异常 limit 钳制到安全区间数据语义memory_save支持数组与逗号分隔字符串两种concepts/files输入格式兼容插件 skill 格式与遗留格式、memory_recall的召回匹配、memory_governance_delete按 ID 数组/CSV 删除且静默跳过未知 ID探针可替换setLivezProbe允许测试注入假探针避免真实 2 秒超时竞态对应 issue #449持久化memory_save后立即落盘、无持久化路径时不触发写盘。许可与使用前提agentmemory/mcp以Apache-2.0协议发布见 packages/mcp/LICENSE 与 packages/mcp/package.json 的license字段。使用前提小结Node.js 版本需满足20.0.0本地降级模式开箱即用但要解锁完整 54 个工具的高级能力图形检索、动作规划、哨兵、插槽、课程学习等需要先启动 agentmemory 服务器npx agentmemory/agentmemory并配置AGENTMEMORY_URL指向它所有配置均通过环境变量注入无需修改任何项目文件即可完成接入。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考