Claude Code 源码拆解 harness 设计 - 记忆注入

Claude Code 源码拆解 harness 设计 - 记忆注入

Tags
Date
Created
May 7, 2026 08:02 AM
Blocking
Blocked by
总结与启发
核心思想:自动化生产记忆但要保证不失控,兼顾自动化和可控性
自动化体现:用户无需主动告诉Agent记忆什么,后台子Agent对话结束后会自动分析和提取
权限锁死:一定要最小权限,确保不会出现重大问题
轮次限制:确保不会陷入无限循环
互斥机制:确保不会和主模型重复执行
游标合并:确保不会遗漏信息以及并行冲突
 
Claude Code方案
extractMemories 机制:一个后台Agent自动帮用户写记忆
  • 每次主模型回答完成后,不再调用工具时,系统会在后台启动一个独立的子 Agent ,这个子 Agent 唯一任务就是回顾完成的对话,判断有没有值得长期保存的信息,存在则写入记忆文件,用户完全无感
 

具体设计

权限锁死
除了记忆目录,其他文件完全只读,无法调用任何外部服务

  • 后台写入记忆的 Agent 权限被严格限制,只能读取文件,搜索文件,使用只读的命令行工具查看目录和文件内容,以及对记忆目录的写入和编辑权限
  • 任何涉及写入、重定向、修改状态的命令都会被拒绝
  • 无法调用其他子 Agent,无法调用任何外部服务

为什么要这么设计
  • 记忆提取看似简单,实际上是一个高价值高风险的操作,它在后台运行,用户完全无感,这既是优势也是劣势
  • 如果它有权限修改代码或者执行命令,一个错误的判断就可能在用户不知情的情况下导致一系列的问题
  • 把权限锁死在只读加记忆目录写入确保了即使 子Agent 犯错 最坏的结果也只是写了一条不太准的记忆,不会影响代码
两轮处理
  1. 并行读取所有需要的文件
      • 会读取现有的记忆文件列表,了解已经存了什么,避免写重复的内容
      • 同时读取最近的会话内容,找寻值得保存的信息
  1. 并行写入所有记忆文件
      • 把提炼出来的记忆一次性写完
硬兜底:子 Agent 被限制在最多五轮内完成任务

为什么要这样设计
  • 子Agent共享主模型的提示词缓存,它和主模型看到的系统提示词,工具定义是完全一样的
  • 因此它的轮次越少,缓存命中率越高,成本就越低,分两轮处理能兼顾成本和性能
  • 大部分输入Token从缓存中读取,产生的计算成本很低
互斥机制
如果主模型在对话过程中,已经自己写了记忆文件,后台就记忆提取则直接跳过

  • 检查最近的对话中有没有主模型写入记忆目录的操作,如果有说明主模型已经处理了记忆写入,后台子Agent无需行动,直接将游标推进的最新的位置

为什么要这样设计
  • 用户输入指令要求模型将这次的改动总结到记忆中,主模型会直接写一条记忆,不需要等后台子Agent
  • 如果后台子Agent再跑一遍,它会看到同样的对话内容,可能会写重复的记忆
  • 主模型往往比后台子Agent选用的模型能力更强
游标与合并
只看游标之后的信息提取记忆

  • 后台子Agent并不是每次都回顾整段对话历史,它会维护一个游标,记录上次处理到了哪条消息,每次运行只看游标之后的信息
  • 如果提取失败,游标不会推进,下次提取会重新进行,确保不会因为一次失败丢失需要保存的信息

不会并行多个子Agent提取不同对话的信息

  • 如果上一次提取还在运行,新的一轮对话又结束了,系统不会启动第二个子Agent并行处理
  • 它会将新的上下文暂存,等当前任务提取完成后再执行任务
  • 避免多个Agent并行运行导致记忆冲突

节流机制:不是每轮对话结束都触发提取,而是可以配置间隔,例如每两轮或者每三轮才触发一次,对于高频对话的场景可以降低后台的计算开销