OMC - 16 让 Claude 真正“记住你”：oh-my-claudecode 的多层记忆与状态管理实践

文章目录Pre一、问题背景LLM 的“记忆错觉”二、整体架构四种记忆表面 生命周期编排2.1 四个记忆子系统2.2 生命周期驱动的记忆流水线三、项目记忆让模型真正理解你的项目3.1 核心数据模型对项目环境的结构化刻画3.2 启动时的三段式检测流水线3.3 会话缓存与去重避免上下文冗余3.4 从工具输出中学习把“踩坑”变成可复用经验3.5 热路径追踪让注意力跟着你走3.6 用户指令保留解决“指令被压缩”这个硬伤四、Wiki跨会话演化的项目知识库4.1 存储形态带 Frontmatter 的 Markdown4.2 五大操作能力摄入、查询、检查、增删、浏览4.3 生命周期集成把 Wiki 拉进对话闭环4.4 并发与安全工程化的细节打磨五、Writer Memory为小说作家准备的“角色大脑”六、Remember 技能知识的“分拣中心”七、对抗上下文压缩双层保留策略7.1 项目记忆 PreCompact带“必须保留”的系统消息7.2 Wiki PreCompact面包屑式的知识提醒八、配置与落地开箱即用但可逐步调优九、思考与启发如何在自己的系统里做记忆工程PreOMC - 01 用 19 个 Agent 打造你的 Claude Code“工程团队”oh-my-claudecode 深度解析与实战指南OMC - 02 五分钟起步走向多智能体协作深入解析 oh-my-claudecode 快速开始与架构设计OMC - 03 从 0 到高效Oh My ClaudeCode 安装与实践全指南OMC - 04 用好 Oh-My-ClaudeCode 的 30 个会话技能从“帮我写点代码”到端到端自动交付OMC - 05 从单人到多 AgentOh-my-claudecode 的插件架构解析OMC - 06 从“大模型管家”到“十九人专家团队”oh-my-claudecode 的多 Agent 工程实践OMC - 07 把「选模型」当成一门工程学oh-my-claudecode 的三层模型路由实践OMC - 08 在多 Agent 时代如何优雅地「分工协作」oh-my-claudecode 委托分类体系深度解读OMC - 09 oh-my-claudecode 的多 Agent 编排实战OMC - 10 从创意到“免看管生产力”深入解析 Oh-My-ClaudeCode 的 Autopilot 与 Ralph 模式OMC - 11 跨供应商 CCG 合成让 Claude、Codex、Gemini 一起给你“做代码评审”OMC - 12 把 Claude Code 变成「可编程开发同事」oh-my-claudecode 技能系统深度解析OMC - 13 深入理解 Oh My ClaudeCode 的 Hooks 生命周期为 AI 编排搭建“中枢神经系统”OMC - 14 MCP 工具服务端oh-my-claudecode 的中枢神经系统OMC - 15 在 Claude Code 里搞个“魔法关键词”oh-my-claudecode 是怎么做到真正无摩擦体验的大模型越来越强但有一个老大难问题迟迟没被真正解决记不住事。会话一长早期说过的话被上下文裁剪换个会话之前辛苦“调教”的习惯和约定又得重来一遍。对于要做长期开发协作、知识积累的开发者来说这几乎是致命缺陷。oh-my-claudecode 给出的答案是一套围绕 Claude 打造的多层记忆架构在会话生命周期的关键节点用多个持久化子系统协同构建起一个可以跨会话、跨上下文压缩、随时间演化的“认知地基”。这篇文章从架构设计、实现细节到使用心法系统拆解这套记忆与状态管理方案帮助你理解如果想让一个 LLM 真的像长期搭档那样理解你的项目、习惯和知识库需要做哪些工程工作。一、问题背景LLM 的“记忆错觉”在 IDE 里接入 Claude 做编程助手看起来似乎已经具备了“上下文感知”当前打开的文件、最近的对话、部分日志都能被模型看到。但只要稍微用久一点就会暴露几个典型问题会话一长早期的关键指令和约定被压缩掉模型开始“跑偏”。换个分支或子目录模型立刻忘记项目结构只能从零开始推理。同一个项目下构建命令、启动脚本、测试习惯要重复解释多次。想把项目里的领域知识沉淀下来结果散落在无数 chat log 中无法系统复用。这些问题背后本质是两件事模型上下文是易失性的而且有严格长度上限。传统“长上下文”方案只是把更多文本塞进去而不是以“记忆系统”的方式组织和持久化。oh-my-claudecode 做的是把“记忆”从模型内部抽到外部用工程手段构造出一个有结构、有层次、有生命周期管理的记忆系统让 Claude 在一个长期演化的“外脑”上工作。二、整体架构四种记忆表面 生命周期编排2.1 四个记忆子系统整个系统不是一个“大一统的记忆数据库”而是四个针对不同认知表面设计的子系统子系统存储位置保留策略主要用途生命周期集成节点项目记忆.omc/project-memory.json按项目24 小时缓存自动检测的环境上下文SessionStart, PostToolUse, PreCompactWiki.omc/wiki/*.md按项目持久化可搜索的精选知识库SessionStart, SessionEnd, PreCompactWriter Memory.writer-memory/memory.json按项目持久化小说写作中的角色/场景追踪仅通过技能调用Remember 技能无单独文件路由层路由到上面各表面将新知识分类到合适的记忆表面仅通过技能调用可以把它理解为项目记忆面向“环境智能”和开发上下文。Wiki面向“项目知识”和决策沉淀。Writer Memory面向“叙事与角色一致性”的领域记忆。Remember负责“把东西扔到哪”这件事不直接存储只负责路由。2.2 生命周期驱动的记忆流水线所有记忆的写入与注入并不是随手调用而是严格挂在 Claude 会话的生命周期上SessionStart检测并加载项目记忆。加载 Wiki 索引并注入环境与知识概览。PostToolUse从工具输出中学习构建命令、端口、错误模式等写入项目记忆。更新热路径常用文件/目录。PreCompact在上下文压缩之前注入一条“必须保留”的项目记忆摘要指令、热路径、技术栈等。注入 Wiki 的面包屑摘要让模型记得“我有一个 Wiki 可以查”。SessionEnd自动捕获本次会话的元数据写入 Wiki 作为 session-log供未来精炼为正式知识。这套流水线的核心是承认“上下文压缩是不可避免的物理现实”因此要在压缩边界刻意注入那些跨会话、跨压缩仍需存活的记忆。三、项目记忆让模型真正理解你的项目项目记忆是整个系统的基础层它负责回答一个问题当前项目到底是什么样子3.1 核心数据模型对项目环境的结构化刻画项目记忆用一个结构化对象来描述项目环境包含七大块信息techStack语言、框架、包管理器等。build构建、测试、lint、dev 命令及脚本。conventions命名、导入、测试组织方式等代码约定。structuremonorepo 检测、工作区划分、目录用途。customNotes来自工具输出或人工的观察与说明。directoryMap带用途标签的目录索引。hotPaths最近频繁访问的文件/目录。userDirectives用户给 Claude 的长期指令例如“永远用 pytest 写测试”。这些信息并不是一次性写死的而是持续演化自动检测负责打基础后续的工具交互和用户行为不断补充和修正。3.2 启动时的三段式检测流水线在 SessionStart 阶段项目记忆的注入经历三个步骤缓存检查与过期判断读取.omc/project-memory.json检查lastScanned是否超过 24 小时。超过就触发重新扫描否则直接复用。环境扫描文件系统级扫描匹配各种配置模式npm、pip、Cargo、Go、Ruby 等识别项目使用的语言、包管理器和框架。解析package.json、pyproject.toml、Cargo.toml等来识别框架类型。抽样源文件分析命名、导入约定、测试模式等。使用目录用途映射规则为各个目录打上“源码”“测试”“构建产物”等标签。摘要格式化与上下文注入使用一个带硬预算的 formatter将项目记忆压缩成不超过 650 字符的摘要。根据当前工作目录只选取与当前范围最相关的一层信息避免把整个项目一次性“灌”进模型。一个关键细节是重新扫描不会覆盖已有的 customNotes、userDirectives 和 hotPaths而是将它们与新检测到的环境信息合并。换句话说你之前积累的“经验”和“习惯”不会被一次全量扫描抹掉。3.3 会话缓存与去重避免上下文冗余如果一个长会话中反复触发 SessionStart 或多次回到同一个项目目录会导致同一段项目记忆不断被重复注入上下文既浪费窗口也增加噪音。为此系统维护了一个最多 100 条目的sessionCaches映射key会话 ID。value该会话下已注入过的projectRoot:scopeKey组合。当在同一会话、同一项目根路径和范围再次尝试注入时会直接跳过。超过 100 个会话时按 FIFO 淘汰最老的记录。这一步很“工程化”却非常必要记忆系统本身也要遵守上下文预算。3.4 从工具输出中学习把“踩坑”变成可复用经验开发过程中很多关键信息是通过工具交互暴露出来的比如运行npm run dev时打印的端口号。后端启动日志中的环境变量约定。CI 失败日志中的错误模式。项目记忆在 PostToolUse 钩子里通过learnFromToolOutput函数对这些输出做“被动学习”利用模式匹配抓取构建命令、测试命令写入 build 区域。扫描端口号、API 路径、环境变量名等作为 customNotes 持久化。从错误模式中抽取有价值的调试线索。并发写入通过 per-projectRoot 的 Promise 互斥锁来串行化避免多次工具调用同时更新记忆文件导致竞态。这意味着你每一次在项目里“踩过的坑”系统都会尽可能转化为可复用的环境知识下次再遇到相关问题时Claude 已经“知道”项目之前发生过什么。3.5 热路径追踪让注意力跟着你走单纯记录“访问次数最多的文件”很容易偏向历史而不是当前关注点。项目记忆采用了一套热路径追踪机制最多保留 50 个 hot path文件或目录。为每个路径维护访问计数并按时间做指数衰减近期访问权重大。打分时融入“距离当前工作目录”的亲近度越接近当前范围得分越高。在生成 650 字符摘要时热路径信息会显著影响选择哪些文件/目录的上下文被注入。效果是Claude 看到的“项目视图”更贴近你此刻正在处理的模块而不是项目历史上最常改动的地方。3.6 用户指令保留解决“指令被压缩”这个硬伤对很多人来说最痛苦的一点是一开始花了大量字数跟模型约定好风格、边界和禁区聊着聊着这些指令就因为上下文压缩被吃掉模型开始“遗忘原则”。项目记忆在这里做了一个非常关键的设计使用专门的 directive-detector监控用户消息中的祈使句模式例如“始终…”“绝不要…”“更偏向 X 而非 Y”。将这些句子抽取为结构化的 UserDirective 对象并带上优先级high/normal。在 PreCompact 阶段把这些指令重新注入为一条独立的系统消息并明确写出“即使在上下文压缩之后也必须遵守这些指令”。这样即使早期对话内容被裁剪指令本身仍然通过磁盘持久化 压缩前重注入的方式存活下来。从架构层面看这是在给 LLM 人为地“焊死了一条长期原则通道”。四、Wiki跨会话演化的项目知识库如果说项目记忆更多是环境事实和运行时观测那么 Wiki 就是一个 Karpathy 风格的“LLM 内置 Wiki”把零散的洞察、决策和模式沉淀为结构化、可搜索的文档体系。4.1 存储形态带 Frontmatter 的 MarkdownWiki 本质上是一组存放在.omc/wiki/下的 Markdown 文件每个文件都带有 YAML frontmatter用来描述页面元信息title标题。tags标签。created / updated创建与更新时间戳。sources贡献该页面的会话 ID 列表。links通过[[page-name]]语法建立的交叉引用。category知识类别如 architecture / decision / pattern / debugging / environment / session-log / reference / convention。confidence置信度high / medium / low。schemaVersionschema 版本用于未来迁移。此外有三个保留文件承担特殊职责index.md自动维护的 Wiki 目录索引。log.mdAppend-only 的操作日志用于审计。environment.md从项目记忆同步过来的环境事实桥接页。这套结构既贴合开发者习惯文本 Git 管理又天然支持 diff、review、重构。4.2 五大操作能力摄入、查询、检查、增删、浏览Wiki 支持一组围绕“知识生命周期”的操作摄入ingestKnowledge用 slug 做去重新内容可以合并到已有页面。内容按时间戳追加并自动提取[[page-name]]形式的 wiki-link构建 links。查询queryWiki关键词 标签搜索。支持 CJK 友好的分词策略兼容中英文混排场景。返回匹配片段和相关度评分。特别强调不使用向量嵌入只做确定性、轻量级的关键字检索。检查lintWiki找出孤立页面没有交叉引用。标记过期内容超过staleDays。检测断链、超大页面超过maxPageSize默认为 10KB、低置信度条目以及结构性矛盾。添加/删除常规的创建、删除页面操作自动更新 index 与 log。列表/读取列出所有页面或读取指定页面内容。这种能力组合基本覆盖了一个“微型知识库系统”所需要的核心功能。4.3 生命周期集成把 Wiki 拉进对话闭环Wiki 并不是一个孤立的“文档目录”而是通过 SessionStart / SessionEnd / PreCompact 三个节点和会话紧密耦合SessionStart加载或重建 Wiki 索引。如果项目记忆有更新就同步到environment.md保持环境事实和 Wiki 一致。注入一段 Wiki 概览摘要到 Claude 的上下文让模型知道有哪些页面、有哪些类别。SessionEnd如果wiki.autoCapture启用默认 true在 3 秒硬超时内生成一个session-log页面。这个页面记录本次会话的“原始元数据”不会立即进行 LLM 层面的筛选。真正的“选哪些内容升格为正式 Wiki 页面”留到后续人工或wiki_ingest技能处理。PreCompact在上下文压缩前注入一条高度压缩的 Wiki 摘要包括页面数量、类别分布、最后更新时间。目的不是让模型“记住 Wiki 全文”而是让它在压缩后仍然知道“我有一个 Wiki可以去查”。这套机制的关键点在于知识持续流入 Wiki但不会在每次对话中把全部内容灌给模型而是保持一个轻量、可导航的“知识视图”。4.4 并发与安全工程化的细节打磨作为一个基于文件的知识库Wiki 在并发和安全方面也做了不少防御性设计所有写操作通过withWikiLock实现同步文件锁防止竞争写入损坏数据。使用atomicWriteFileSync做原子写入避免部分写入导致文件半损坏。路径统一通过safeWikiPath做白名单校验防止路径遍历攻击写到仓库之外。这意味着你可以放心地在多人协作、复杂工具链里挂载这套系统而不必担心“某次工具异常就把整个 Wiki 砸坏”。五、Writer Memory为小说作家准备的“角色大脑”相比前两者偏工程向Writer Memory 更像是给小说作者设计的“角色与世界观记忆宫殿”。它的职责包括追踪角色的情感轨迹、台词语气、语言层级。维护角色之间的关系网络。记录场景镜头切分、情绪标签和世界观设定。支持“角色对话校验”检查某句台词是否符合该角色既有的声音、语调、关键词与禁忌词。Writer Memory 存储在.writer-memory/memory.json中不参与会话生命周期钩子而是完全通过专用技能调用。这保证了它不会对一般的开发者工作流造成干扰同时又能为写作场景提供一套专用且高保真度的记忆系统。六、Remember 技能知识的“分拣中心”当模型在对话中挖掘出一些“值得记”的信息时一个现实问题是到底应该存到哪乱存的结果要么是一锅粥要么是关键信息埋没在海量噪声里。Remember 技能就是这套系统的“记忆路由层”。它本身不存储数据而是负责做三件事收集聚合本轮对话中被认为有价值的发现。分类判断每条信息适合落在什么记忆表面。落盘调用对应子系统项目记忆 / Notepad / Docs完成写入同时标记重复或冲突。系统预设了几种记忆表面记忆表面最适用场景保留策略项目记忆稳定的团队/项目事实持久化自动刷新Notepad 优先级“下一轮要用”的高信号上下文会话内保留Notepad 工作区临时活跃会话笔记会话内保留Docs / CLAUDE.md持久化的指令、规范、约定持久化需要人工管理这样的设计迫使系统在“记还是不记、记到哪”上做清晰决策避免“所有东西都塞进一个大 JSON”那种常见灾难。七、对抗上下文压缩双层保留策略上下文压缩是所有长对话系统绕不过去的物理限制。oh-my-claudecode 没试图否认它而是专门设计了一套双层保留策略来“跟压缩打擂台”。7.1 项目记忆 PreCompact带“必须保留”的系统消息在 PreCompact 钩子中项目记忆会做一次“压缩前总动员”加载完整的项目记忆。用 formatter 生成一条包含用户指令尤其是 high 优先级当前热路径及其语义当前技术栈与重要构建信息最近学习到的重要自定义笔记。以系统消息形式注入模型并明确标注“这些内容必须在压缩后保留”。配合 650 字符的硬预算控制这条消息的目标不是“面面俱到”而是“保证最关键的那一撮不会死”。7.2 Wiki PreCompact面包屑式的知识提醒Wiki 在 PreCompact 阶段做的事情更轻量注入一个高度压缩的“知识地图”当前 Wiki 有多少页面、覆盖哪些类别、最近更新时间在什么范围。让模型在压缩之后仍然知道项目有一套结构化的知识库。可以通过技能调用来定位和查询具体内容。这有点像给模型脑子里放了一张“知识导航图”不要求记住全部内容但记住“哪里有路”。八、配置与落地开箱即用但可逐步调优从使用者角度看这套记忆系统的默认体验是尽量“零配置”的项目记忆默认开启自动扫描并运作无需手动设置。Wiki可以通过.omc-config.json做细粒度调优例如wiki.autoCapture是否在会话结束时自动捕获 session-log默认 true。wiki.staleDays多少天视为页面过期默认 30。wiki.maxPageSize页面内容达到多大时视为过于膨胀默认 10240 字节。实际落地时一个比较自然的演进路径是先完全接受默认设置依赖项目记忆和 Wiki 自动运作。观察几轮使用后的项目记忆与 Wiki 内容手动整理几篇关键架构/约定文档。在团队内约定部分“写给 Claude 看”的文档规范例如CLAUDE.md并通过 Remember 技能和 Wiki 把它们纳入统一记忆系统。对于有写作需求的成员再逐步启用 Writer Memory。整个系统的设计哲学是不要一上来就让你配置 N 个 YAML而是先以保守默认值跑起来再逐步根据项目成熟度增强记忆层。九、思考与启发如何在自己的系统里做记忆工程oh-my-claudecode 的这套状态与记忆管理方案不仅是一个具体实现更是一份“如何为 LLM 做记忆工程”的设计样板。如果你打算在自己的代理系统、IDE 插件或对话平台中引入长期记忆能力可以从中借鉴几个关键原则把“记忆表面”拆分清楚环境、知识库、指令、叙事不要混在一个存储里。一切围绕生命周期节点设计尤其是 SessionStart、PostToolUse、PreCompact、SessionEnd 这四个关键点。把“指令保留”作为一等公民问题来设计而不是仅依赖更大的上下文窗口。对每一条持久化信息都思考“写在哪、如何更新、何时过期、如何被查到”。接受上下文压缩不可避免把“压缩前强行插一句”当成系统能力而不是临时补丁。当你把这些工程约束考虑进去LLM 才有可能从“聪明的一次性对话机器”变成一个在项目周期内持续成长的长期合作者。