让AI跨会话记住你的偏好：claude-code-from-scratch语义记忆召回系统设计解析

让AI跨会话记住你的偏好claude-code-from-scratch语义记忆召回系统设计解析【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. Claude Code 开源了 50 万行代码读不动用 ~5000 行 TypeScript / Python 从零复现核心架构11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratchclaude-code-from-scratch 是一个用约 5000 行 TypeScript / Python 代码从零复现 Claude Code 核心架构的开源教程项目它的记忆系统能真正做到让 AI 跨会话记住你的偏好——关掉终端再打开AI 依然知道部署去 staging、回复别加总结。本文带你读懂这套语义记忆召回系统的设计精髓四类记忆文件、sideQuery 语义选择、异步预取三大机制几乎零等待就让 AI想起该想起的事。 痛点为什么 AI 每次都要重新认识你大多数 coding agent 的记忆只是当前会话的消息数组——会话一关全部清零。你上周纠正过的习惯这周它还会再犯一次。claude-code-from-scratch 给出的答案是把用户偏好、项目事实写成磁盘上的小文件一份记忆一个文件下次会话时按当前话题的相关度自动捞回相关记忆塞进 System Prompt而不是把整段历史都背回来。核心源码就一个文件src/memory.tsPython 版在 python/mini_claude/memory.py完整设计思路见官方教程 docs/08-memory.md。 记忆存储一份偏好 一个小 Markdown 文件四种封闭分类防止标签膨胀系统只允许四种记忆类型这是刻意设计的封闭分类法——防止标签自由膨胀导致召回时的模糊匹配类型记什么触发时机user用户角色、偏好、知识背景了解到用户偏好时feedback对 Agent 行为的纠正和肯定用户纠正或肯定某行为时project项目进展、决策、截止日期了解到项目动态时reference外部系统定位信息URL、面板等了解到外部资源位置时一个细节很值得学feedback类型不只记错误也记肯定——只记错误会让模型放弃用户已验证过的好做法。项目隔离 自动索引记忆按项目隔离路径取process.cwd()的 sha256 前 16 位同一项目目录始终映射到同一记忆空间见 getProjectHash。每个记忆文件带 YAML frontmattername / description / type文件名格式为{type}_{slugified_name}.md文件系统排序时自动按类型分组人眼扫描一目了然。每次写入后自动重建MEMORY.md索引。索引是索引不是容器每条一行链接内容按需读取并设 200 行 / 25KB 双重截断保护MAX_INDEX_LINES。 语义召回AI 如何想起该想起的事关键词匹配为什么不够早期版本用关键词重叠打分召回最小实现见 recall_memories简单、零 API 调用但用户问部署流程时标题为CI/CD 注意事项的记忆完全匹配不上——没有共同关键词。sideQuery让模型判断哪条记忆有用新方案在 selectRelevantMemories 中只把每条记忆的文件名 描述 时间戳一份轻量清单发给模型让模型判断哪些与当前查询真正相关最多返回 5 条。几个关键设计输入极小不发送记忆全文只发清单token 成本很低宁缺毋滥提示词明确要求不确定就不选避免无关记忆污染上下文静默失败召回失败只打日志返回空数组——记忆召回永远不应阻塞主循环L276-L281。数据库性能能匹配到PostgreSQL 索引优化经验——因为模型理解语义关联而不是字面重叠。异步预取用户几乎零等待语义召回需要一次 API 调用同步执行会拖慢每次提问。解法是 startMemoryPrefetch在用户提交输入的瞬间启动召回与第一次模型 API 调用并行执行主循环每轮迭代做一次非阻塞轮询就绪即注入为system-reminder消息。三个门控条件避免浪费 API 调用查询太短如单词 hi直接跳过语义匹配无意义会话记忆累积超过60KB 预算后停止召回防止挤占上下文MAX_SESSION_MEMORY_BYTES没有记忆文件时跳过省一次调用。配合alreadySurfaced集合同一会话中展示过的记忆不再重复出现——越到会话后期召回越精准。⏳ Freshness Warning提醒模型记忆会过期记忆是时间切片不是实时状态。一条项目下周截止的记忆在两周后读到时已经过时。memoryFreshnessWarning 的规则很简单1 天以内不提示超过 1 天就附带警告明确告诉模型这是过去某个时刻的观察引用前请先对照当前代码验证。这比单纯标注X 天前更有效——它给出了行动指引。 一条命令跑起来无需 API key想亲眼看看效果克隆仓库后运行第 8 章 demo 即可——它会从磁盘记忆认出部署去 staging并直接回答git clone https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch cd claude-code-from-scratch npm install npm run build node steps/run.mjs 8 # 跑记忆章节 demo本地 mock 模型不联网 node steps/run.mjs 8 --py # 换成 Python 版对应的最小实现与测试场景分别在 steps/canonical/py/memory.py 和 steps/scenarios/recall-memory.json可对照阅读。 延伸阅读与文件导航资料路径记忆系统完整教程第 8 章docs/08-memory.mdTypeScript 版记忆源码src/memory.tsPython 版记忆源码python/mini_claude/memory.pyfrontmatter 共享解析模块src/frontmatter.ts章节运行入口steps/run.mjs 加入 AI Agent 工坊对这个约 5000 行就能看懂的 coding agent 架构感兴趣扫码加入交流群一起拆解 Agent Loop、语义记忆召回、多 Agent 这些话题。【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. Claude Code 开源了 50 万行代码读不动用 ~5000 行 TypeScript / Python 从零复现核心架构11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考