架构选型三个开源项目的上下文管理哲学——Hermes、CoPaw 与 WeClaw 的横向对比专栏信息《从零到一构建跨平台 AI 助手WeClaw 实战指南》专栏本文是模块八第 2 篇深入对比三个开源项目的上下文管理架构设计帮助你为自己的 Agent 项目做出正确的技术选型。作者与项目作者简介翁勇刚 WENG YONGGANG新概念龙虾-WeClaw 开发团队负责人一群专注于跨平台 AI 应用的实践者理念“再复杂的技术也能用代码讲清楚”项目地址https://github.com/wyg5208/weclaw.git官网地址https://weclaw.link作者 CSDNhttps://blog.csdn.net/yweng18PyPI[待发布]欢迎 Star、Fork、贡献代码摘要本文结构概览本文从三个开源项目的源码出发逐层剖析 Hermes-Agent 的一体化压缩流水线、CoPaw 的记忆分层架构、WeClaw 旧方案的截断优先策略通过关键差异表揭示各自的架构哲学最后给出 WeClaw 选择借鉴 Hermes 流水线模式的完整决策推导。背景上下文管理是 LLM Agent 的核心基础设施不同项目基于各自的场景特点做出了截然不同的架构选择。理解这些差异是做出正确技术选型的前提。核心问题三种架构的压缩时机、容灾策略、Tool 保护、成本控制有何不同在什么场景下应该选择哪种方案解决方案提炼出 7 个关键维度进行横向对比结合代码级分析给出选型指南。关键成果完整剖析三种架构的核心设计差异给出可复用的上下文管理选型决策矩阵明确 WeClaw 的技术选型推导过程适合读者正在构建 LLM Agent 项目、需要做上下文管理技术选型的架构师和开发者阅读时长约 12 分钟关键词架构对比、Hermes-Agent、CoPaw、压缩流水线、记忆分层、技术选型一、三个项目三种哲学[图片: 三架构对比图 | 生成方式: 文生图 PROMPT: “Three architecture diagrams side by side: Left shows a linear pipeline flow (compress after each call), Center shows a three-layer memory stack (working/episodic/semantic), Right shows a simple truncation bar, each with distinct color coding and flow arrows, clean technical style, white background”]1.1 项目背景速览项目定位技术栈核心场景Hermes-Agent通用 AI Agent 框架Python LiteLLM多工具编排的复杂任务CoPaw桌面 AI 助手TypeScript AgentScope日常对话长期记忆WeClaw跨平台 AI 助手Python PySide6 FastAPI桌面端PWACLI 多端协同三个项目的共同点都面临上下文窗口不够用的问题。但各自的解决思路截然不同。二、Hermes-Agent一体化压缩流水线2.1 核心架构Hermes 采用Pluggable Engine架构上下文管理核心由两个组件协作ContextEngine抽象基类207 行定义压缩接口支持插件替换ContextCompressor核心实现1415 行包含完整的压缩逻辑# Hermes 的压缩触发时机每次 API 调用之后classPluggableEngine:asyncdefrun(self,messages):whilenotdone:# 1. 调用 LLMresponseawaitself.call_llm(messages)# 2. 执行工具resultsawaitself.execute_tools(response)# 3. 追加结果messages.extend(results)# 4. 关键每轮结束后触发压缩检查messagesawaitself.context_engine.compress(messages)returnresponse2.2 三阶段预处理在调用 LLM 生成摘要之前Hermes 先做三轮无损预处理降低 LLM 输入 token原始消息 → [Pass 1: MD5 去重] → [Pass 2: 信息摘要替换] → [Pass 3: 参数截断] → LLM 摘要Pass 1相同 tool_result 只保留最后一条基于 MD5 哈希Pass 2为 20 种高频工具生成一行摘要如search → 搜索 python async返回 5 条结果Pass 3截断超过 500 字符的 tool_call arguments2.3 三级容灾Level 1: 辅助模型 (AuxiliaryClient) ↓ 失败/超时 Level 2: 主模型重试 (30s 超时, 429/503 快速跳过) ↓ 也失败 Level 3: 静态回退 (提取文件路径工具名, 零 LLM 成本)这是 Hermes 最精妙的设计无论如何都不会让压缩失败导致上下文丢失。2.4 设计哲学总结“宁可多花一分钱也不丢一条消息”—— 以可靠性为第一优先级通过容灾和预处理控制成本三、CoPaw记忆分层架构3.1 核心架构CoPaw 基于 AgentScope 框架上下文管理由MemoryCompactionHook214 行驱动委托给ReMeLightMemoryManager391 行执行。┌──────────────────────────────────────┐ │ 工作记忆 (Working Memory) │ │ 当前会话的最近 N 轮消息 │ │ recent_n 参数控制保留数量 │ ├──────────────────────────────────────┤ │ 情景记忆 (Episodic Memory) │ │ 历史对话的结构化摘要 │ │ 异步生成持久化到文件系统 │ ├──────────────────────────────────────┤ │ 语义记忆 (Semantic Memory) │ │ 长期知识库向量全文检索 │ │ 基于 ChromaDB / local store │ └──────────────────────────────────────┘3.2 双压缩通道CoPaw 的压缩分为两条并行通道通道 ATool Result Compact工具结果压缩# 对旧消息中的 tool_result 做专门处理defcompact_tool_results(self,messages,recent_n20):old_messagesmessages[:-recent_n]formsginold_messages:ifmsg[role]toolandlen(msg[content])self.old_max_bytes:msg[content]truncate_with_summary(msg[content])returnmessages通道 BContext Compact上下文整体压缩# 将旧消息压缩为摘要asyncdefcompact_context(self,messages,recent_n20):old_messagesmessages[:-recent_n]summaryawaitself.reme_client.summarize(old_messages)# 摘要写入向量数据库支持后续语义检索awaitself.memory_store.add(summary)return[summary_msg]messages[-recent_n:]3.3 ReMeLight 语义检索CoPaw 的独特能力是跨会话的语义检索# 在新对话开始时召回相关的历史记忆asyncdefrecall(self,query,top_k5):resultsawaitself.reme_client.search(query,top_ktop_k)# 将相关记忆注入到当前上下文中context_msgs[format_recall(r)forrinresults]returncontext_msgs3.4 设计哲学总结“记忆不应该消失只是需要被检索”—— 以长期记忆为核心通过语义检索在有限窗口中召回最相关的信息四、WeClaw 旧方案截断优先策略4.1 核心架构WeClaw 旧方案的上下文管理逻辑直接嵌入在DialogManager原文件约 1352 行中采用简单的截断策略# WeClaw 旧方案的核心逻辑classDialogManager:defget_messages(self,session_id,max_tokensNone):messagesself._load_from_db(session_id)# 策略 1消息数超限 → 截断iflen(messages)MAX_MESSAGES:messagesmessages[-MAX_MESSAGES:]# 策略 2Token 超限 → 截断total_tokensestimate_tokens(messages)iftotal_tokensmax_tokens:# 从头部开始删除直到不超限whileestimate_tokens(messages)max_tokens:messages.pop(0)returnmessages4.2 为什么在 128K 窗口下失效旧方案的阈值计算公式是threshold max(32K, context_window * 0.6)模型窗口计算阈值实际问题32K32K合理会正常触发128K76.8K偏大压缩触发较晚1M600K过大几乎不会触发2M1.2M超过绝对上限永远不触发核心问题阈值基于模型的原始窗口大小而非实际有效窗口。一个 1M 窗口的模型实际安全可用空间可能只有 600-800K但阈值已经设为 600K加上 System Prompt 和输出预留留给压缩的空间几乎为零。4.3 旧方案的另一个致命缺陷无摘要# 旧方案截断后早期消息永久丢失messagesmessages[-MAX_MESSAGES:]# 用户 20 轮前的分析请求没了。# 用户之前讨论的量化策略没了。# 之前搜索到的关键信息没了。4.4 设计哲学总结“简单就是好——直到不够用”—— 在 32K 窗口时代够用但在大窗口时代完全失效五、关键差异表 —— 七个维度的横向对比[图片: 架构对比热力图 | 生成方式: 文生图 PROMPT: “A heatmap comparison table with 7 rows (dimensions) and 3 columns (projects), cells colored from red (poor) to green (excellent), with dimension labels on the left and project names on top, clean data visualization style”]5.1 压缩时机项目触发时机优劣分析HermesAPI 调用之后在自然边界触发不干扰推理循环CoPaw消息追加之后(Hook)时机灵活但可能在工具执行中间触发WeClaw 旧获取消息之时实时但可能截断在 tool_call 中间5.2 Tool 配对保护项目策略可靠性Hermes移除孤儿 tool_call 添加 stub result高CoPaw间接保护按轮次保留中WeClaw 旧无保护低可能切断配对5.3 旧结果处理项目策略效果Hermes三阶段无损预处理去重摘要截断压缩前减少 40-60% tokenCoPaw双通道tool compact context compact工具结果专门优化WeClaw 旧直接丢弃零成本但信息全失5.4 容灾机制项目容灾级别极端情况表现Hermes三级辅助→主模型→静态最坏情况保留结构化文件摘要CoPaw单级LLM 摘要LLM 失败时降级为简单截断WeClaw 旧无直接截断无容灾5.5 反抖动项目机制说明Hermes连续 2 次节省 10% 时暂停避免反复压缩相同内容CoPaw标记压缩而非删除天然避免重复压缩WeClaw 旧无N/A5.6 System Prompt 管理项目策略说明Hermes无显式管理SP 管理不在上下文引擎职责内CoPaw无显式管理依赖框架层WeClaw三级预算控制总 40K 技能 8K 文件 3K最精细的 SP 管理5.7 跨会话记忆项目支持说明Hermes不支持专注单会话压缩CoPaw支持ReMeLight 向量检索核心差异化能力WeClaw不支持通过 SQLite 存储历史但无语义检索六、决策推导 —— WeClaw 为什么选择借鉴而非照搬6.1 选型决策树[图片: 架构选型决策树 | 生成方式: 文生图 PROMPT: “A decision tree flowchart for choosing LLM context management architecture, branching by: context window size (small/medium/large), latency requirement (low/medium/high), cost budget (tight/moderate/flexible), and multi-session support (yes/no), clean technical diagram, white background”]6.2 排除 CoPaw 的推理WeClaw 排除记忆分层方案的三个理由场景不匹配WeClaw 用户通常在单一会话中完成完整任务无需跨会话语义召回复杂度过高引入向量数据库ChromaDB增加了部署依赖和维护成本质量不可控向量检索的假阳性召回可能误导模型尤其在技术对话场景中# 向量检索的风险示意query中芯国际的投资价值resultsawaitvector_store.search(query,top_k3)# 可能召回# 1. 中芯国际的财报分析 ← 相关 ✓# 2. 芯片行业趋势报告 ← 半相关 △# 3. 国际形势对科技股的影响 ← 不相关但向量相似 ✗6.3 借鉴 Hermes 的理由WeClaw 选择 Hermes 流水线模式作为基础并做本地化适配压缩时机自然API 调用后的边界不干扰 ReAct 推理可靠性设计完备三级容灾的理念与 WeClaw 不失忆的目标一致可扩展性好Pluggable Engine 模式便于未来替换或增强6.4 WeClaw 的差异化增强在借鉴 Hermes 的基础上WeClaw 做了四项独特增强增强项HermesWeClawSP 管理无显式管理三级预算控制 膨胀监控压缩触发固定阈值分档自适应三档 封顶异步压缩同步异步后台 快照 hash 保护截断通知无自动追加到 SP 中提示模型七、总结与展望7.1 核心要点回顾三种哲学各有侧重Hermes 重可靠性、CoPaw 重长期记忆、WeClaw 旧方案重简单七个维度决定选型压缩时机、Tool 保护、旧结果处理、容灾、反抖动、SP 管理、跨会话借鉴不等于照搬WeClaw 在 Hermes 基础上增加了分档阈值、异步压缩、SP 管理等差异化能力7.2 选型速查表你的项目需要跨会话语义检索吗 ├── 是 → 考虑记忆分层方案类似 CoPaw └── 否 → 你的模型窗口 128K 吗 ├── 是 → 考虑压缩流水线类似 Hermes/WeClaw 新方案 └── 否 → 简单截断可能就够了下期预告《压缩阈值为什么 1M 窗口下 AI 从不压缩》旧公式threshold max(32K, window * 0.6)的致命缺陷三档自适应策略的设计与实现为什么阈值需要绝对上限封顶从代码到测试的完整验证过程敬请期待附录 A代码规模对比项目核心文件行数职责Hermescontext_engine.py~1415 行压缩预处理容灾CoPawmemory_manager.py~391 行记忆管理向量检索WeClawcontext_engine.py~852 行压缩截断SP 管理附录 B参考资料Hermes-Agent GitHubCoPaw GitHubAgentScope Framework上一篇《当 AI 在百万 Token 长对话中失忆》本系列第 46 篇下一篇《压缩阈值为什么 1M 窗口下 AI 从不压缩》本系列第 48 篇版权声明本文为 CSDN 博主「翁勇刚」的原创文章遵循 CC 4.0 BY-SA 版权协议转载请附上原文出处链接及本声明。