我把Claude Code泄露的代码改造成python程序了，其中的大模型记忆模块与上下文工程分析

文章目录项目概述一、记忆模块1.1 架构设计1.2 记忆类型4 种1.2.1 用户记忆1.2.2 反馈记忆1.2.3 项目记忆1.2.4 引用记忆1.3 记忆保存方式方式 Amemory 标签快速笔记方式 B结构化文件持久化记忆1.4 记忆不保存的内容1.5 自动梦境整合Auto Dream1.6 梦境整合流程Phase 1 - Orient定位Phase 2 - Gather收集Phase 3 - Consolidate整合Phase 4 - Prune and Index修剪和索引1.7 会话持久化二、上下文工程2.1 系统提示架构2.2 记忆系统注入2.3 上下文压缩2.4 压缩触发条件2.5 消息分割策略2.6 摘要提示词2.7 媒体剥离三、LLM 客户端抽象3.1 多提供商支持3.2 流式响应3.3 错误处理四、成本追踪4.1 Token 成本计算4.2 成本计算公式4.3 Advisor 成本五、关键设计模式5.1 追加式日志Append-Only Logs5.2 索引与内容分离5.3 锁文件模式5.4 节流机制5.5 角色交替保证六、总结记忆模块核心特性上下文工程核心特性设计亮点项目概述Claude Code开源代码是一个交互式 AI 助手系统下面我来详细解析Claude Code的记忆模块与上下文工程分析其中采用模块化架构设计本文档详细分析其记忆模块和上下文工程的实现机制。我把Claude Code泄露的代码改造成python程序了并且接入Qwen大模型来进行问答。下面我将对Claude Code大模型记忆模块与上下文工程进行详细分析。Claude Code中还有很多隐藏的功能比如电子宠物一、记忆模块1.1 架构设计记忆模块位于features/memory.py采用基于文件的持久化系统支持跨会话记忆存储和检索。核心目录结构~/.config/cc-mini/ ├── memory/ # 记忆存储目录 │ ├── MEMORY.md # 记忆索引文件200 行 │ ├── logs/ # 按日追加的日志 │ │ └── YYYY/MM/YYYY-MM-DD.md │ └── [topic].md # 主题记忆文件 └── sessions/ # 会话记录目录 └── [session_id].jsonl1.2 记忆类型4 种系统采用与 Claude Code 相同的 4 类型记忆分类1.2.1 用户记忆用途存储用户的角色、目标、职责和知识保存时机了解到用户的角色、偏好、职责或知识时示例用户是后端工程师偏好使用 PostgreSQL1.2.2 反馈记忆用途用户给出的指导或纠正确保跨会话一致性保存时机用户纠正你的行为方式时结构- 规则描述 - **Why:** 原因说明 - **How to apply:** 应用方式1.2.3 项目记忆用途正在进行的工作、目标、bug 或事件保存时机了解到谁在做什么、为什么做、何时完成要求相对日期必须转换为绝对日期1.2.4 引用记忆用途指向外部系统中信息的位置示例“bug 追踪在 Linear 项目 INGEST 中”1.3 记忆保存方式方式 Amemory标签快速笔记defextract_memory_tags(text:str)-list[str]:从文本中提取所有 memory.../memory 标签内容return[m.strip()forminre.findall(rmemory(.*?)/memory,text,re.DOTALL)]在对话中模型可以输出memory用户偏好使用 PostgreSQL 而非 MySQL/memory系统会自动提取并追加到当日日志。方式 B结构化文件持久化记忆写入.md文件到记忆目录使用 frontmatter 格式--- name: 用户数据库偏好 description: 用户对数据库的技术偏好 type: user --- 用户偏好使用 PostgreSQL 而非 MySQL因为需要复杂查询支持。然后在MEMORY.md中添加索引指针- [用户数据库偏好](user-db-preference.md) — 技术偏好说明1.4 记忆不保存的内容系统明确规定了不应保存的内容代码模式、架构、文件路径可从代码库读取Git 历史、最近变更git log/git blame是权威来源调试解决方案修复在代码中上下文在 commit messageCLAUDE.md 文件中已记录的内容临时任务详情或当前对话上下文1.5 自动梦境整合Auto Dream系统实现了自动记忆整合机制定期将日志中的临时记忆整合为持久化主题文件。触发条件defshould_auto_dream(memory_dir,min_hours,min_sessions,current_session_id): 检查是否触发自动整合 1. 时间间隔 ≥ min_hours默认由配置决定 2. 新会话数 ≥ min_sessions 3. 包含 10 分钟扫描节流避免频繁检查 锁机制锁文件.consolidate-lock锁持有者 PID 存储在文件内容中锁过期时间1 小时3600 秒支持锁回收持有者进程死亡后1.6 梦境整合流程整合过程分为 4 个阶段Phase 1 - Orient定位使用 Glob 列出记忆目录中的所有文件读取MEMORY.md了解当前索引浏览现有主题文件避免重复创建Phase 2 - Gather收集按优先级收集新信息日志文件追加式日志流漂移的记忆与当前代码库矛盾的事实转录搜索使用 grep 搜索 JSONL 转录中的关键术语Phase 3 - Consolidate整合将新信息合并到现有主题文件将相对日期转换为绝对日期删除矛盾的事实Phase 4 - Prune and Index修剪和索引更新MEMORY.md保持在 200 行以内每行 150 字符- [标题](文件.md) — 一句话钩子移除过时、错误或已被取代的记忆指针1.7 会话持久化会话记录采用JSONL 格式每行一个 JSON 对象defsave_session(messages:list[dict],session_id:str)-None:序列化消息到 JSONL 并更新 last-session 符号链接SESSIONS_DIR.mkdir(parentsTrue,exist_okTrue)pathSESSIONS_DIR/f{session_id}.jsonlwithpath.open(w,encodingutf-8)asf:formsginmessages:f.write(json.dumps(serialize_message(msg),defaultstr)\n)SessionStore 类管理单个会话append_message()追加消息到 JSONLload_messages()从 JSONL 读取所有消息list_sessions()列出可用会话按更新时间排序自动生成标题从第一条用户消息提取二、上下文工程2.1 系统提示架构系统提示采用分块组装方式位于core/context.py。静态部分按顺序Intro Section角色介绍和安全准则System Section系统行为规则Doing Tasks Section任务执行指南Actions Section操作风险评估Using Tools Section工具使用偏好Tone and Style Section沟通风格Output Efficiency Section输出效率要求动态部分Environment Section工作目录、Git 状态、平台信息Git Section当前分支、状态、最近提交CLAUDE.md Section项目特定指令如果存在Memory Section记忆系统指令和索引Companion SectionAI 伴侣介绍如果启用Plan Mode Section计划模式指令如果激活2.2 记忆系统注入记忆系统通过build_memory_system_section()函数注入到系统提示defbuild_memory_system_section(memory_dir:Path)-str:返回记忆指令 MEMORY.md 内容indexload_memory_index(memory_dir)# 读取 MEMORY.md截断到 10,000 字符section # Auto Memory You have a persistent, file-based memory system at {memory_dir}/. ... [完整的记忆类型说明和保存指南] ifindex:sectionf\n## Current Memory Index (MEMORY.md)\n{index}\nreturnsection2.3 上下文压缩当上下文接近模型限制时系统会自动压缩历史消息。核心机制classCompactService:defcompact(self,messages,system_prompt,custom_instructions):压缩消息列表返回 (new_messages, summary_text)history,recent_split_recent(messages)# 分离历史和最近消息# 对历史部分调用 LLM 生成摘要summaryself._client.create_message(modelself._model,max_tokensCOMPACT_MAX_OUTPUT_TOKENS,# 4096systemCOMPACT_SYSTEM,messagescleaned_history,)# 构建新消息列表[摘要用户消息] [确认助手消息] [最近消息]new_messages[{role:user,content:summary},{role:assistant,content:Understood...},]new_messages.extend(recent)returnnew_messages,summary2.4 压缩触发条件自动压缩阈值计算def_auto_compact_threshold(model:str)-int:context_window - max_output_reserve - buffercw_context_window_for_model(model)# 模型上下文窗口max_out_reservemin(20_000,cw//5)# 预留输出空间returncw-max_out_reserve-AUTOCOMPACT_BUFFER_TOKENS# buffer13,000模型上下文窗口模型系列上下文窗口claude-opus-4-61,000,000claude-sonnet-4-61,000,000claude-opus-4200,000claude-sonnet-4200,000claude-3-5-sonnet200,000触发判断defshould_compact(messages,modelNone,last_input_tokensNone):iflast_input_tokensandmodel:# 使用 API 返回的实际 token 数returnlast_input_tokens_auto_compact_threshold(model)# 回退到基于字符的估算returnestimate_tokens(messages)COMPACT_THRESHOLD_TOKENS# 100,0002.5 消息分割策略压缩时会保留最近的对话def_split_recent(messages):分离 (待摘要历史, 保留的最近消息)# 向后遍历直到满足两个条件# 1. 至少 MIN_RECENT_MESSAGES 6 条消息# 2. 至少 MIN_RECENT_TOKENS 10,000 个 token# 保证不分割 tool_use / tool_result 对ifkeep_start0:msgmessages[keep_start]ifmsg 是纯 tool_results 的用户消息:keep_start-1# 包含前一条助手消息2.6 摘要提示词压缩使用的提示词结构## Primary Request 用户的总体目标 ## Key Technical Concepts 建立的技术概念、模式、框架或约束 ## Files and Code 讨论或修改的关键文件及简要说明 ## Errors and Fixes 遇到的错误及解决方式 ## Current Work 最近工作内容及当前状态 ## Pending Tasks 未完成的任务或下一步2.7 媒体剥离压缩前会剥离历史消息中的图片/文档以节省 tokendef_strip_media(messages):将 images/documents 替换为文本标记forblockincontent:ifblock.typeimage:new_blocks.append({type:text,text:[image]})elifblock.typedocument:new_blocks.append({type:text,text:[document]})三、LLM 客户端抽象3.1 多提供商支持core/llm.py实现了对 Anthropic 和 OpenAI 的抽象classLLMClient:def__init__(self,provideranthropic,api_keyNone,base_urlNone):self.providervalidate_provider(provider)ifprovideropenai:self._clientOpenAI(api_key,base_url)else:self._clientanthropic.Anthropic(api_key,base_url)3.2 流式响应支持流式输出和工具调用defstream_messages(self,model,max_tokens,messages,system,tools):ifprovideropenai:return_OpenAIStream(...)return_AnthropicStream(...)3.3 错误处理重试机制_MAX_RETRIES10_BASE_DELAY0.5_MAX_DELAY32.0def_compute_retry_delay(attempt,retry_afterNone):ifretry_after:returnretry_after# 尊重 API 的 Retry-After 头# 指数退避 抖动delaymin(_BASE_DELAY*(2**attempt),_MAX_DELAY)jitterdelay*random.uniform(0,0.25)returndelayjitter错误类型分类认证错误立即返回不重试上下文溢出减少 max_tokens 后重试可重试错误限流、连接、内部错误指数退避重试其他 API 错误返回错误信息四、成本追踪4.1 Token 成本计算features/cost_tracker.py实现成本追踪dataclass(frozenTrue)class_PricingTier:input:float# $/MTokoutput:floatcache_write:floatcache_read:float定价层级示例模型输入输出缓存写缓存读claude-3-5-haiku$0.80$4.0$1.0$0.08claude-sonnet$3.0$15.0$3.75$0.30claude-opus-4-1$15.0$75.0$18.75$1.504.2 成本计算公式defcalculate_cost(model,usage):tier_tier_for_model(model)cost(input_tokens*tier.inputoutput_tokens*tier.outputcache_read*tier.cache_readcache_write*tier.cache_write)/1_000_000returncost注意Anthropic API 的input_tokens已排除缓存 token缓存部分单独计费。4.3 Advisor 成本Advisor 功能智能建议的 token 单独计费ifadvisor_inoradvisor_out:advisor_tier_tier_for_model(advisor_model)advisor_cost(advisor_in*advisor_tier.inputadvisor_out*advisor_tier.output)/1_000_000五、关键设计模式5.1 追加式日志Append-Only Logs日志采用追加式写入保证数据完整性defappend_to_daily_log(memory_dir,entry):pathdaily_log_path(memory_dir)# YYYY/MM/YYYY-MM-DD.mdtimestampdatetime.now().strftime(%H:%M)withpath.open(a,encodingutf-8)asf:f.write(f- [{timestamp}]{entry}\n)5.2 索引与内容分离MEMORY.md仅作为索引不包含实际记忆内容索引文件200 行每行150 字符主题文件完整记忆内容优势系统提示中只注入索引节省 token5.3 锁文件模式使用文件 mtime 作为时间戳文件内容为 PIDdeftry_acquire_lock(memory_dir):lp_lock_path(memory_dir)# 检查锁是否过期1 小时# 检查持有者进程是否存活# 写入自己的 PIDlp.write_text(str(os.getpid()))5.4 节流机制防止频繁扫描会话文件_SESSION_SCAN_INTERVAL_S600# 10 分钟ifnow-_last_session_scan_atSESSION_SCAN_INTERVAL_S:returnFalse# 跳过本次检查_last_session_scan_atnow5.5 角色交替保证API 要求消息严格的用户/助手交替def_fix_alternation(messages):fixed[messages[0]]formsginmessages[1:]:ifmsg[role]fixed[-1][role]:# 合并到前一条消息fixed[-1][content]prev\ncurelse:fixed.append(msg)returnfixed六、总结记忆模块核心特性4 类型分类法user/feedback/project/reference双模式保存memory标签临时和结构化文件持久自动整合基于时间和会话数的触发条件锁机制防止并发整合冲突索引分离MEMORY.md 仅作索引节省 token上下文工程核心特性分块组装静态 动态部分模块化组合自动压缩基于模型上下文窗口的智能阈值消息分割保留最近 6 条消息或 10k token媒体剥离压缩前移除图片/文档结构化摘要7 部分摘要模板设计亮点追加式日志简单可靠易于回溯节流机制避免不必要的频繁操作错误恢复多层次重试和回退策略成本感知实时追踪 token 使用和成本多提供商统一的 Anthropic/OpenAI 抽象这套系统实现了持久化记忆、智能上下文管理和成本优化的平衡为长周期 AI 助手交互提供了坚实基础。