人工智能AI AgentAgent 记忆RAG后端MCP 服务【免费下载链接】honchoMemory library for building stateful agents项目地址https://gitcode.com/gh_mirrors/hon/honcho点击查看免费下载honcho-mcp是 Honcho 官方的 Model Context ProtocolMCP服务器实现它以 Cloudflare Worker 为托管形态同时支持 stdio 与 Streamable HTTPBun两种运行方式把 Honcho 的记忆能力peers、sessions、conclusions、scopes、dreams以标准 MCP 工具的形式暴露给任意 MCP 客户端。本篇文章以 mcp/CHANGELOG.md 为骨架结合 mcp/README.md 与 mcp/src 下的源码实现逐版本拆解从 0.1.0 到 3.0.1 的能力迭代作用域Scope如何从只读查询演进为可配置的召回边界、结论Conclusion如何获得可审计的溯源能力、证据Evidence如何在不增加模型 token 的前提下支撑答案审计以及长期困扰chat工具的超时问题是如何被根治的。读完你将理解每个版本升级带来的实际能力边界并能在自托管或托管环境中把这些能力真正用起来。版本脉络速览独立版本线的四个里程碑honcho-mcp遵循 Keep a Changelog 格式与 Semantic Versioning并且与 Honcho API、honcho-ai/sdk及宿主插件独立版本化见 mcp/CHANGELOG.md。截至当前仓库其版本演进如下版本发布日期核心主题0.1.02026-09-09作用域只读查询、workspace_chat跨 peer 推理、列表分页、身份头0.1.12026-09-11作用域生命周期管理增删查/回填状态、读工具全面支持作用域参数0.2.02026-09-17结论溯源attribution、双向推理链遍历、include_evidence证据审计3.0.12026-09-22MCP 工具注解、双模式指令、chat超时治理、list_peers分页当前包版本为 3.0.1依赖honcho-ai/sdk2.5.0 与modelcontextprotocol/sdk1.26.0见 mcp/package.json。下面按版本逐一深入。1. 0.1.0作用域、跨 peer 推理与分页的地基0.1.0 是honcho-mcp的首次能力交付它奠定了服务器的大部分工具面作用域只读工具list_scopes、get_scope_sessions以及chat上的scope/sessions参数对应 Honcho v3.1.0。作用域Scope在本仓库的语义是一个命名会话集合作为召回边界recall boundary——在chat上指定scopename后回答只基于该作用域内会话的知识。workspace_chat针对跨所有 peer 的推理问答Honcho v3.1.0用于跨 peer 分析、共性主题或不绑定单个 peer 的问题。其实现位于 mcp/src/tools/workspace.ts通过ctx.clientFor(workspace_id).chat(query, options)直接走 SDK 的工作区级对话接口。分页list_sessions与get_session_messages支持分页。这一模式在后续版本被推广到list_peers、list_conclusions等所有列表工具。身份头每个 Honcho API 请求携带X-Honcho-Host: honcho-mcp/versionX-Honcho-Plugin原样透传调用方的User-Agentstdio 下或调用方未发送时缺省X-Honcho-Agent-Model从不发送。实现细节身份头如何在源码中落地在 mcp/src/config.ts 中identityHeaders()把两个头打包为每个请求的默认头export function identityHeaders(userAgent?: string | null): Recordstring, string { const headers: Recordstring, string { [HEADER_HOST]: HOST_VALUE }; const plugin userAgent?.replace(/\s/g, ).trim().slice(0, MAX_PLUGIN_LEN); if (plugin) headers[HEADER_PLUGIN] plugin; return headers; }其中MAX_PLUGIN_LEN 256是对齐 Honcho API 对客户端请求头 256 字符的长度上限源码注释明确说明了这一点。随后createClient()通过defaultHeaders: headers把身份头注入 SDK 客户端使所有经由此连接发出的 API 请求都带有可观测的宿主标识。2. 0.1.1作用域从只能读到可管理0.1.1 的关键变化是补齐了作用域的生命周期管理工具让客户端可以主动配置召回边界而不仅仅是读取它们create_scopeget-or-create 一个作用域可选 metadata如标签、描述、示例查询。add_sessions_to_scope把已有会话加入作用域单次最多 100 个重复加入是 no-op已含消息的会话会被异步回填backfill因此依赖作用域召回前应轮询get_scope_status。remove_session_from_scope把会话移出作用域会话本身不受影响但作为成员期间派生的结论会被异步调和reconcile移除。get_scope_status按会话 ID 查看回填进度每个条目为pending/completed/failed用于区分作用域尚未赶上与本来就没有可召回内容。同时读工具全面接入作用域选项Honcho v3.1.0create_session上的scopes、get_representation上的scope/sessions、search上的scope以及get_session_context上的peer_target/peer_perspective/scope/limit_to_session——当给定 target 时get_session_context还会额外返回peer_representation与peer_card。实现细节existingScope 如何避免副作用值得注意的一个工程细节在 mcp/src/tools/scopes.tsfunction existingScope(honcho: Honcho, scopeId: string): Scope { return new Scope(scopeIdSchema.parse(scopeId), honcho.workspaceId, honcho.http); }注释解释了动机honcho.scope()在 SDK 里是 get-or-create 语义会带来一次多余往返而remove_session_from_scope、get_scope_status、get_scope_sessions这类读/删工具如果调用它会以副作用的方式凭空创建不存在的 scope。因此这里绕过 SDK 校验直接用Scope构造器引用现有作用域服务端在作用域不存在时返回 404。作用域 ID 也被约束为[a-zA-Z0-9_-]长度上限为 512 -scope..length。3. 0.2.0结论溯源与证据审计记忆从此可解释0.2.0 是功能密度最高的一次迭代它让 Honcho 的记忆从黑盒结论变成了可追溯、可验证、可审计的推理链。3.1 结论归属字段level / source_ids / times_derivedlist_conclusions与query_conclusions现在随内容一同返回三个归属字段Honcho v3.2.0level结论的生成方式。explicit表示直接从消息中提取的事实deductive、inductive、contradiction表示在 dream记忆巩固过程中派生的结论。客户端由此可以区分提取的事实与推断的猜想。source_ids派生结论所基于的前提结论 ID 列表explicit结论该字段为 null。times_derivedHoncho 独立得出同一结论的次数是粗略的置信度信号。这三个字段的描述在 mcp/src/tools/conclusions.ts 中被封装为ATTRIBUTION_NOTE注入到所有结论工具的 description 中确保 MCP 客户端即模型每次调用都理解其语义。3.2 双向遍历推理树get_conclusions 与 get_derived_conclusionsget_conclusions按 ID 从工作区任意位置取结论不需要 observer/observed 对并会报告所请求 ID 中哪些已不存在missing数组。把某结论的source_ids喂给它就能向下走完整条推理链直到它依赖的显式事实。get_derived_conclusions沿同一条边向上走列出以给定结论为前提派生了哪些新结论即在其source_ids中命名了该结论的那些结论。实现上就是一次带过滤器{ source_ids: { contains: conclusion_id } }的conclusions.list调用见 mcp/src/tools/conclusions.ts。实操建议纠正一个事实前先向下走链看它支撑了什么删除一个结论前先向上走链看什么建立在它之上。3.3 include_evidence零 token 成本的答案审计chat与workspace_chat新增include_evidence开关Honcho v3.2.0。开启后返回的不再是裸答案而是{ content, evidence }结构答案 Agent 实际读取的结论与消息、以及它调用过的工具用于审计这个答案是基于什么构建的。其关键设计有三点见 mcp/src/tools/peers.ts 的工具描述证据来自实际访问而非模型自述由 MCP 服务器在 Agent 执行期间整理其读取过的内容不依赖模型报告因此会过度报告over-reports——列出的结论只代表读过不代表答案真的依赖它不消耗额外模型 token证据是从 Agent 访问轨迹中归集的而非让模型再生成一遍默认关闭、行为不变不带该标志时两个工具与以前一样只返回裸答案content为空时返回None。未开启时的返回逻辑同样清晰peer.chat(query, options)的字符串结果直接透传?? None兜底见 mcp/src/tools/peers.ts。3.4 list_conclusions 分页与过滤list_conclusions新增page、size、reverse、session_id与filters透传。此前它永远只返回第一页 50 条、无法收窄——现在可以用session_id只看绑定到某会话的结论用filters做精确过滤例如{level: inductive}只看模式结论或{source_ids: {contains: id}}看由某结论派生的内容size上限 100、page从 1 开始、reverse控制新旧顺序。3.5 SDK 版本要求0.2.0 将依赖从honcho-ai/sdk2.4.0 提升到2.5.0因为归属字段与携带证据的 chat 响应都依赖该版本的 SDK 类型与客户端能力——这体现了 MCP 工具面与 SDK 数据模型之间的强绑定。4. 3.0.1工具注解、双模式指令与超时根治3.0.1 在元数据与稳定性上做了三项重要收敛。4.1 list_peers 分页list_peers新增page、size最大 100与reverse客户端可以翻页遍历全部 peer。实现位于 mcp/src/tools/peers.ts返回{ peers, total, page, pages }结构。4.2 MCP 工具注解readOnlyHint 与 destructiveHint每个工具现在携带 MCP 注解title人类可读的标题、readOnlyHint或destructiveHint。这使宿主如 Claude Desktop、各类 MCP 客户端能够在界面上为工具显示友好名称明确区分只读查询与有副作用/破坏性操作从而在调用前给予用户确认或提示。在源码中只读工具如list_conclusions、list_peers、chat、search标注readOnlyHint: true写操作如set_peer_card、delete_session、delete_conclusion、schedule_dream标注destructiveHint: true详见 mcp/src/tools/scopes.ts、mcp/src/tools/conclusions.ts 等各工具注册处。4.3 双模式指令Recall 与 Memory-Store服务器指令mcp/instructions.md被重构为两种模式Recall 模式默认只读取 Honcho 已知道的内容涉及chat、workspace_chat、search及其它读工具不写入任何东西。适用场景用户自己的应用负责写入 Honcho本对话只从中读取。Memory-store 模式本对话本身就是 Honcho 的学习来源仅在用户明确要求记录对话、或把 Honcho 设为该助手的记忆时启用。在此模式下额外启用create_session、create_peer、add_peers_to_session、add_messages_to_session。指令同时删除了逐工具的冗长清单工具描述本身已承载这些信息并明确要求用户未要求记录对话时保持在 Recall 模式。4.4 chat 超时治理HONCHO_TIMEOUT_MSchat/workspace_chat走的是一个会使用工具的 Agent其耗时可能远超普通 API 调用。3.0.1 修复了两类超时导致的失败Bun 宿主在 10 秒后断开空闲连接idle timeout任意宿主上 SDK 默认 60 秒超时导致 chat 被重试。修复方式是Honcho API 请求统一超时为 5 分钟可通过HONCHO_TIMEOUT_MS配置。在 mcp/src/config.ts 中定义了默认值/** Chat runs a tool-using agent that can outlast the SDKs 60s default. */ const DEFAULT_TIMEOUT_MS 300_000;parseTimeoutMs()只接受有限的正数见 mcp/src/config.ts随后注入 SDK 客户端的timeout字段见 mcp/src/config.ts。如果自托管环境使用 HTTP 宿主前置反向代理的读取超时至少要与该值对齐否则代理层会先于 Honcho 客户端断开。5. 底层实现印证六个工具族的注册与配置解析CHANGELOG 描述的所有能力最终都落在 mcp/src/server.ts 的createServer()中const server new McpServer( { name: Honcho MCP Server, version: pkg.version }, { instructions }, ); registerWorkspaceTools(server, ctx); registerPeerTools(server, ctx); registerSessionTools(server, ctx); registerScopeTools(server, ctx); registerConclusionTools(server, ctx); registerSystemTools(server, ctx);六个工具族分别对应 mcp/src/tools 下的workspace.ts、peers.ts、sessions.ts、scopes.ts、conclusions.ts、system.ts。指令文件instructions.md通过打包器的 Markdown loader 作为{ instructions }注入这是 3.0.1 双模式指令生效的机制。配置解析分两条路径mcp/src/config.ts运行形态配置来源必需项Worker / HTTP请求头Authorization: Bearer key、可选X-Honcho-Workspace-IDBearer token缺失直接抛错stdio进程环境变量HONCHO_API_KEY、可选HONCHO_API_URL/HONCHO_WORKSPACE_ID/HONCHO_TIMEOUT_MSHONCHO_API_KEY缺失直接抛错HONCHO_API_URL未设置时默认https://api.honcho.dev用于把服务器指向自托管 Honcho它刻意不作为请求头暴露——把公共请求路由到内部 URL 是延迟与安全上的双重倒退源码注释明确说明。工作区解析由resolveWorkspaceId()完成工具参数优先其次回退到X-Honcho-Workspace-ID头 /HONCHO_WORKSPACE_ID两者皆无则抛出MISSING_WORKSPACE_ID_MESSAGEmcp/src/config.ts。HTTP 宿主mcp/src/http.ts把会话保存在进程内存中空闲超过MCP_SESSION_IDLE_MS默认 30 分钟的会话被清扫MCP_SESSION_MAX默认 128限制并发会话数——这也是 README 强调跑单实例、不要无状态多副本的原因。6. 升级与兼容性清单综合 CHANGELOG 与当前仓库状态可以整理出以下部署与升级要点SDK 跟随要使用 0.2.0 起的溯源与证据能力必须使用honcho-ai/sdk≥ 2.5.0当前 package.json 即锁定该版本。Honcho API 版本前提作用域工具0.1.x依赖 Honcho v3.1.0结论溯源与include_evidence0.2.0依赖 Honcho v3.2.0。自托管时请确认 API 版本满足这些下限。超时配置长chat场景建议显式设置HONCHO_TIMEOUT_MS默认 300000 即 5 分钟HTTP 宿主前的反向代理读取超时不能短于它。作用域副作用提醒读/删类作用域工具不会隐式创建作用域先create_scopeadd_sessions_to_scope再轮询get_scope_status等待回填完成最后才做基于作用域的召回。审计与纠错工作流开启include_evidence审计答案删除/修正结论前分别用get_derived_conclusions与get_conclusions走完推理链。工具注解红利升级到 3.0.1 后MCP 宿主可以依据readOnlyHint/destructiveHint对工具做读写区分与二次确认降低误操作风险。结语从 CHANGELOG 看一个 MCP 服务器的成熟路径纵观 0.1.0 → 3.0.1honcho-mcp的演进脉络非常清晰先搭起作用域与跨 peer 推理的基础工具面再补齐作用域的生命周期管理与全量分页随后为结论引入归属字段与双向推理链遍历、为答案引入零成本的证据审计最后通过工具注解、双模式指令与可配置超时把服务器打磨到生产可用。对使用者而言CHANGELOG 的每一条Added / Changed / Fixed都对应着可验证的源码实现与可落地的操作姿势——本文即是把这条路线图还原成可执行的升级与使用手册。赞分享人工智能AI AgentAgent 记忆RAG后端MCP 服务【免费下载链接】honchoMemory library for building stateful agents项目地址https://gitcode.com/gh_mirrors/hon/honcho点击查看免费下载相关推荐honcho-cli 版本演进全解读从结论归因、证据溯源到本地堆栈管理honcho cli 版本演进全解读从结论归因、证据溯源到本地堆栈管理 本篇文章以 honcho cli/CHANGELOG.md https://link.人工智能AI AgentAgent 记忆RAG后端MCP 服务xManager解锁免费Spotify高级功能的终极指南xManager解锁免费Spotify高级功能的终极指南 在音乐流媒体成为现代生活标配的今天Spotify以其海量曲库和智能推荐赢得了全球用户的青睐。然而开发工具Honcho TypeScript SDK 演进全览从 1.1.0 到 2.5.1 的能力地图与源码解读Honcho TypeScript SDK 演进全览从 1.1.0 到 2.5.1 的能力地图与源码解读 本文以 Honcho TypeScript SDK人工智能AI AgentAgent 记忆RAG后端MCP 服务上一篇终极指南使用Windows Defender Remover工具高效移除系统安全组件下一篇淘宝任务自动化工具从时间消耗到效率革命的技术实现与实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考