随着 Agent 承担越来越复杂的长期任务，一个现实的工程瓶颈逐渐浮出水面——LLM 的上下文窗口有限，Token 成本高昂，每次对话结束后，所有的交互信息都会随 Session 消失。Agent 每次都是从零开始，无法记住之前学到的东西。
记忆系统正是为了解决以上痛点而诞生的基础设施。它让 Agent 不仅能在单次对话中保持连贯性，还能跨越多个 Session 积累用户偏好和历史经验，从“一次性工具”进化为“长期协作伙伴”。
今天这篇文章就来系统梳理 Agent 记忆系统的核心概念和工程实践，帮你搞清楚如何让 Agent 拥有真正的“记忆”。本文接近 1.3w 字，建议收藏，通过本文你将搞懂：
- 记忆系统的设计原理：短期记忆与长期记忆如何划分？各自承担什么职责？
- 记忆的存储形式：Token 级记忆和参数化记忆有什么区别？
- 记忆生命周期：记忆如何进行读取、写入、遗忘和检索？
- 主流技术架构：Mem0、MemGPT、ZEP 等方案各有什么特点？
- 生产级优化策略：如何设计高信噪比的记忆系统？
Agent 的记忆系统是如何设计的？
工业界通常将记忆系统划分为两个物理与逻辑隔离的层级：短期记忆（Session 级）与长期记忆（跨 Session 级）。
记忆的存储形式
除了按时间维度划分，记忆还可以按存储位置与表征形式分为三类：
| 存储形式 | 说明 | 典型实现 |
|---|---|---|
| Token 级记忆 | 以自然语言或离散符号形式存储在外部数据库 | 向量库中的文本块、结构化 JSON |
| 参数化记忆 | 将信息编码进模型参数中 | 预训练知识、LoRA 适配器、SFT 微调 |
| 潜在记忆 | 以隐式形式承载在模型内部表示中 | KV Cache、激活值、Hidden States |
这三种形式可以相互转换。例如 MemOS 提出的“记忆立方体”框架支持：纯文本记忆 → 激活记忆（KV Cache）→ 参数记忆（通过蒸馏固化到模型） 的动态流转，实现“热记忆”到“冷记忆”的分级管理。
记忆的功能分类
按功能目的，Agent 记忆分为三类：
| 功能类型 | 核心问题 | 存储内容 | 典型场景 |
|---|---|---|---|
| 事实记忆 | 智能体知道什么？ | 用户偏好、环境状态、显式事实 | 记住用户的技术栈偏好 |
| 经验记忆 | 智能体如何改进？ | 过往轨迹、成败教训、策略知识 | 从失败的代码审查中学习 |
| 工作记忆 | 智能体当前思考什么？ | 当前推理上下文、任务进展 | 多步推理中的中间状态 |
按内容性质进一步细分：
- 情景记忆（Episodic Memory）：记录特定时间、场景下的具体事件，回答"What happened?"。例如：“上周三用户反馈订单超时问题”。
- 语义记忆（Semantic Memory）：从多个情景中提炼的通用知识、事实或规律，回答"What does it mean?"。例如：“该用户对性能问题敏感度高于功能需求”。
- 程序记忆（Procedural Memory）：存储技能、规则和习得行为，使 Agent 能自动执行任务序列而无需每次显式推理。例如：“处理该用户的代码审查时，优先检查 OOM 风险”。
记忆操作的生命周期
记忆系统是一个动态演化的有机体。其生命周期包含以下核心操作：
编码(Encode) → 存储(Storage) → 提取(Retrieval) → 巩固(Consolidation) → 反思(Reflection) → 遗忘(Forgetting)| 操作 | 说明 | 工程实现 |
|---|---|---|
| 编码 | 将原始交互转化为可存储的结构化信息 | LLM 提取事实三元组、生成摘要 |
| 存储 | 将编码后的信息持久化 | 写入向量库 / 图数据库 / 参数 |
| 提取 | 根据上下文检索相关记忆 | 向量检索 + BM25 + 图遍历 |
| 巩固 | 将短期记忆转化为长期记忆 | 异步任务：对话摘要 → 实体库 |
| 反思 | 主动回顾评估记忆内容，优化决策 | 任务完成后提取 Meta-Knowledge |
| 遗忘 | 淘汰低价值或过时记忆 | 权重衰减 + 冲突标记废弃 |
前沿趋势：记忆控制策略（Control Policy）成为新维度
最新的记忆系统综述将控制策略列为与时间跨度、表征形式并列的三大维度之一。核心问题是：“何时写、何时读、何时更新？”传统的记忆系统采用规则触发（如每轮对话后写入），而前沿方案正尝试通过强化学习让 Agent 学习最优的控制策略——例如，判断当前信息是否值得写入、何时触发记忆更新、何时主动遗忘。这种端到端的记忆管理使 Agent 能够根据任务特点自主调整记忆行为，避免依赖硬编码规则。
短期记忆（Short-Term Memory / Working Memory）
概念：Agent 在当前单次会话（Session）中持有的暂存信息，涵盖用户的提问、模型的每轮回复，以及工具调用的中间结果（Observations）。短期记忆直接作为 Prompt 的组成部分参与 LLM 当前轮次的推理，是 Agent 感知“当前任务上下文”的唯一来源。
实现方式：依托 LLM 自身的上下文窗口（Context Window）。主流模型的窗口已显著扩展：GPT-5 支持 400K Token，Claude Sonnet 4.6 支持 1M Token，Gemini 3 Pro 支持 1M Token，Llama 4 Scout 支持 10M Token，Grok 4 支持 2M Token（截至 2026 年数据）。需注意：上下文窗口属于高频变更指标，上述数字请以各模型官方 model card 或 API 文档的最新发布为准。
然而，更大的上下文窗口并不意味着可以无限堆砌上下文——推理成本随 Token 数线性增长。《Lost in the Middle》研究表明，在多文档检索型任务中，模型对位于上下文首尾位置的信息利用率显著高于中间段。这一位置偏差在窗口越长时越明显，需要在上下文工程中主动控制输入信息的分布。
上下文工程策略（Context Engineering）：为控制短期记忆的膨胀，框架层通常在运行时采用以下三类压缩策略：
- 上下文缩减（Context Reduction）：当对话历史达到预设 Token 阈值时，框架自动丢弃最早的 N 轮消息（滑动窗口），或调用轻量模型将历史对话总结压缩，以最小的信息损耗换取上下文空间。
- 上下文卸载（Context Offloading）：工具或 Skill 调用可能返回大体量数据（如完整网页 HTML、CSV 文件内容），此时将这些“重型结果”卸载到外部临时存储，Prompt 中只保留极短的引用标识（UUID 或文件路径）。当模型需深挖细节时，通过强制关联的 Function Calling 触发内部工具执行读取动作。同时需为该动作设置防雪崩策略：若读取超时或文件超限，工具应主动返回截断或降级响应。
- 上下文隔离（Context Isolation）：在多智能体架构中，主 Agent 在向子 Agent 分配子任务时，只传递精简的任务指令和必要的上下文片段，避免将整个对话历史广播给每个子 Agent。这是控制多 Agent 系统总 Token 消耗的关键工程实践。
长期记忆（Long-Term Memory）
概念：跨越单个 Session 的持久化知识与经验库。与短期记忆不同，它不随对话结束而销毁，而是通过主动的“写入-检索”机制，使 Agent 能在全新的 Session 中调取历史沉淀的用户偏好、事实认知和过往经验。
实现原理（Record & Retrieve 双向交互）：
- 记忆写入（Record）：对话结束后，框架触发后台异步任务，调用 LLM 对本轮短期记忆进行语义“提纯”——过滤冗余的对话噪声，抽取高价值的结构化事实（例如：“用户的技术栈偏好为 Python + FastAPI”、“用户的汇报对象是 CFO，需要非技术化的表达风格”），以结构化条目的形式写入持久化存储。写入链路应视为尽力而为（Best-Effort）操作——LLM 提取可能遗漏关键事实或误将假设性陈述固化为偏好。写入操作本身也需设计幂等 Key 以防重试产生重复记忆；在 LLM 抽取场景下，幂等 Key 应基于源消息 ID + 抽取批次 ID，而非抽取结果文本（因温度采样或 prompt 微调可能导致语义相同但字面不同的表述，字符串哈希无法保证幂等）。在多端并发对话场景下，实体库合并与覆盖必须引入乐观锁或版本控制（MVCC）机制。
- 记忆检索（Retrieve）：在新 Session 开始时，用户 Query 被向量化，与长期记忆库中的条目进行语义相似性检索，将最相关的历史偏好和背景知识注入到当前 Session 的 System Prompt 中，使 Agent 在对话伊始就具备“了解这位用户”的上下文感知能力。由于检索发生在首次响应的关键路径上，VectorStore 的 P99 延迟会直接叠加到 TTFT（Time to First Token），生产中通常采用预检索缓存（用户建立连接时将基础偏好全量加载至内存数据库如 Redis 形成预热缓存）来缓解这一开销，而对于依赖具体对话意图的深度记忆，则将向量检索与首 Token 生成进行流水线化重叠（如检索完成后立即开始生成首段，后台并行精排），使两部分耗时在用户感知上并行叠加，从而降低整体 TTFT。
长期记忆与 RAG（检索增强生成）的区别：
两者底层技术高度相似（均依赖向量库和语义检索），但服务对象不同：
- RAG 挂载的是共享知识源——公司规章、产品文档、实时数据库查询结果等，与“谁在使用”无关，对所有用户返回同一知识库的内容。其核心特征是非个性化，而非一定是静态的。
- 长期记忆管理的是 Agent 与特定用户交互中动态沉淀的个性化经验——用户的偏好、习惯、历史决策、专属背景，高度个性化，因人而异。
两者并非二选一，而是协作关系：RAG 提供“世界知识”（公司规章、产品文档），长期记忆提供“用户画像”（偏好、习惯、历史决策）。检索阶段可分别召回后融合排序；长期记忆中的实体可作为 RAG 检索的 query 扩展；用户偏好可作为 RAG 结果的个性化重排信号。
⭐️ 记忆系统的主流技术架构有哪些？
由于长期记忆涉及向量化存储、语义检索和记忆管理等复杂逻辑，通常将其剥离为独立的第三方组件。
底层存储架构
其底层架构通常由以下三层组成：
- VectorStore（向量数据库）：将提取的记忆文本转化为语义向量（Embeddings）存储。以单节点 Qdrant（1.x 版本）、本地 SSD、HNSW 索引 ef=128、Recall@10 ≥ 0.95 为基准，在低并发场景（如 QPS 小于 50）下，P99 延迟可控制在数十毫秒级别。不同产品（Pinecone Serverless vs 自建 Qdrant vs Milvus）在相同 QPS 下 P99 差异可达 5-10 倍，实际选型请参考 ann-benchmarks.com 或各厂商 benchmark 报告。常见方案包括 Pinecone、Weaviate、Chroma、Qdrant 等。
- GraphStore（图数据库）：进阶方案，将记忆以“实体-关系”的形式建模为知识图谱（如 Neo4j），适用于需要多跳推理的复杂查询场景，例如“用户提到的同事 A 与项目 B 之间有什么关联”。
- Reranker（重排序器）：向量检索的初步召回结果在语义相关性上并不精确有序，Reranker 基于交叉编码器（Cross-Encoder）对召回结果进行二次精排，显著提升最终注入上下文的记忆质量。
向量库选型核心维度：
| 维度 | 关键考量 | 说明 |
|---|---|---|
| 索引类型 | HNSW / IVF / DiskANN | 影响召回率与延迟的 tradeoff |
| 元数据过滤 | pre-filter vs post-filter | 高过滤率场景下 pre-filter 易破坏图结构连通性 |
| 多租户隔离 | Namespace / Collection / 物理隔离 | 影响召回率与数据安全 |
| 持久化一致性 | 强一致 vs 最终一致 | 影响写入可靠性 |
| 成本模型 | Serverless 按量 vs 自建集群 | 影响运营成本 |
LLM 事实抽取的失败模式与防御手段：LLM 提取可能遗漏关键事实或误将假设性陈述固化为偏好。工程上建议：
- Schema 约束：强制 JSON Schema 定义 + 重试机制兜底
- 置信度过滤：LLM-as-Judge 二次校验，置信度低于阈值的结果不写入
- 假设性语句识别：Prompt 中添加“假设性语句识别”指令（如"I might..."类陈述不固化）
- 人工 Review 队列：高 importance 记忆触发人工审核流程
- 抽取审计日志：保留原始对话 + 抽取结果对照，便于回溯
主流 Memory 产品对比
2025 年被视为 Agent 市场元年，Agent Memory 领域涌现出多个代表性产品，各有其技术特色：
| 产品 | 核心思想 | 技术亮点 | 适用场景 |
|---|---|---|---|
| Mem0 | 单次 ADD-only 抽取 + 多信号融合检索 | 单次 LLM 调用完成实体抽取与跨记忆链接；语义 + BM25 + Entity Linking 并行打分；通过可选的 GraphStore 后端启用图记忆（Mem0g） | 通用对话记忆 |
| LETTA (原 MemGPT) | 操作系统虚拟内存分页 | Main Context ↔ External Context 动态交换；递归摘要压缩 | 长对话上下文管理 |
| ZEP | 时间感知知识图谱 | 自研 Graphiti 引擎；情景/语义/社区三层子图；边失效机制 | 企业级多租户场景 |
| A-MEM | Zettelkasten 知识管理 | 卡片笔记法；记忆间自动建立语义连接 | 知识密集型任务 |
| MemOS | 三种记忆类型动态转换 | 纯文本 ↔ 激活记忆(KV Cache) ↔ 参数记忆(LoRA) | 全栈记忆管理 |
| MIRIX | 六模块分工协作 | 元记忆管理器路由；不同记忆组件采用不同存储结构 | 复杂决策支持 |
代表性方案详解
LETTA 的虚拟内存模型：借鉴操作系统分页思想，将 Context 划分为 Main Context（系统指令 + 工作上下文 + FIFO 队列）和 External Context（持久化存储）。当 Main Context 空间不足时，通过递归摘要（Recursive Summary）将旧消息压缩后换出到外部存储。这本质上是一种以牺牲信息颗粒度为代价的有损压缩方案——长周期的递归会导致精准事实（如 API 密钥、具体的报错堆栈、精确数值）严重降维甚至丢失，Agent 可能患上“技术性失忆症”。
ZEP 的三层知识图谱：
- 情景子图：无损存储原始输入数据（消息、问题、JSON）
- 语义子图：提取实体和关系，构建知识网络
- 社区子图：对强连接实体聚类，生成高层次概括（参考 GraphRAG）
其核心创新是边失效机制：当新事实与旧事实存在时间重叠的矛盾时，标记旧边为“失效”并记录失效时间，既保留最新事实，也支持历史回溯。
MemOS 的记忆动态转换：
纯文本记忆 ──(高频使用)──→ 激活记忆(KV Cache) ──(长期固化)──→ 参数记忆(LoRA)
↑ │
└──────────────(知识过时/卸载)─────────────────────────────┘这种设计使“热记忆”（高频访问）可以预加载为 KV Cache 大幅降低 TTFT。而“核心记忆”则通过触发离线的 SFT（监督微调）流水线，蒸馏内化为特定用户的 LoRA 适配器——这并非实时的内存操作，而是需要收集高质量训练数据并启动离线 GPU 训练任务。
更需注意的 trade-off 是：参数化记忆一旦烧入 LoRA，遗忘和纠错变得极其昂贵——不像向量库可以软删除一条记录，LoRA 的局部知识修改是开放研究问题（Machine Unlearning），业界尚无成熟方案。因此建议仅对极稳定的、几乎不会变更的核心偏好（如用户的汇报风格、长期偏好）才烧入参数。在多租户生产环境中，还需依赖支持动态 LoRA 卸载与加载的推理基建（如 vLLM 或 TGI）才能实现特定用户上下文的永久保留。
⭐️ 记忆系统的高级演化机制有哪些？
在基础的写入与检索之上，生产级 Agent 系统还需要一套 代谢机制 ，来保证记忆的质量与检索的信噪比。
记忆反思与合成（Reflection & Synthesis）
核心问题：Agent 如何从“原始数据”向“高阶知识”转化？
Agent 不仅仅是被动地记录原始对话，还需要像人类“睡觉”一样，定期对记忆进行自我审计和二次加工。
实现方式：
1. 自我反思（Self-Reflection）：在任务完成后，Agent 启动一个异步任务，复盘本次任务的成败原因，并将“教训”提取为一条 Meta-Knowledge（元知识）。这一机制最早由 Park et al.（2023）《Generative Agents》论文系统化提出，是模拟人类“睡眠记忆巩固”过程的工程化实现。
例如：“在处理该用户的 Java 代码审查时，他更在意性能而非规范，未来应优先关注 OOM 风险。”
2. 精细化反思闭环（Reflect Loop）：2025-2026 年的前沿框架（如 MUSE）已将反思机制演化为更精细的“规划-执行-反思-记忆”闭环。反思不再仅发生在任务完成后，而是在每个子任务结束时都会触发。独立的 Reflect Agent 会对子任务输出进行三重验证：
- 真实性验证：输出是否符合客观事实
- 交付物验证：是否完成了用户指定的目标
- 数据保真性验证：关键数据是否在传递过程中丢失或变形
通过这种细粒度的反思，可以有效防止错误在多轮推理中累积放大。
3. 记忆聚类与合并（Clustering & Consolidation）：当长期记忆中出现大量碎片化、重复的记录时（例如用户 10 次提到了同一个项目背景），系统会自动触发合并任务，将这些碎片合成为一个完整的“实体百科”，减少向量库的冗余并提升检索的一致性。
记忆的清理与遗忘机制（Pruning & Forgetting）
核心问题：如何避免“记忆爆炸”和“过时记忆干扰”？
记忆并非越多越好。无用的噪声记忆和过时的错误信息会显著干扰 LLM 的判断。
工程策略：
- 权重与衰减（Importance & Decay）：为每条记忆维护综合得分
score = relevance × importance × decay(t)，其中relevance为当前 Query 与记忆条目的语义相似度（如余弦相似度），importance为记忆的固有重要性评分，衰减函数decay(t)通常取指数形式（如e^{-λt}，λ 为衰减速率）。这一设计参考了《Generative Agents》中提出的三维检索模型：将近期性（Recency）、重要性（Importance）、相关性（Relevance）合并为综合权重。为避免查询时全量计算时间衰减造成的性能雪崩，工程上通常采用“读时粗滤 + 重排精算”策略：向量库仅负责静态语义召回，在随后的 Reranker 阶段，再对召回的 Top-K 结果实时应用该公式进行动态调整。 - 主动冲突解决：当新旧记忆发生逻辑冲突时（如用户去年用 Java 8，今年升级到了 Java 21），系统需识别并标记旧记忆为“废弃状态”，防止 Agent 给出过时的建议。工程实现上，由于主流向量库（如 HNSW 索引）处理软删除（Soft Delete）会引发图索引连通性退化，需要定期执行离线 Vacuum（空间清理与图重构） 任务，避免废弃记录拉低检索性能。
⭐️ 如何优化长期记忆的检索精度？
在 VectorStore 和 GraphStore 之外，生产环境下通常还需要一层“混合检索”策略。
混合检索与元数据过滤（Hybrid Search & Metadata Filtering）
核心问题：单纯依赖向量检索为什么会产生“虚假关联”？
单纯依赖向量的语义相似度（Dense Retrieval）有时会产生“虚假关联”。
混合检索（Hybrid Search）：结合传统的关键词检索（BM25/Sparse）与语义向量检索（Dense）。融合算法可针对不同 query 类型动态调整权重（如专有名词查询加大 BM25 权重，模糊意图查询加大向量权重），常见融合方式包括：
- RRF（Reciprocal Rank Fusion）：无调参，适合冷启动，按排名倒数加权融合
- Linear weighted（α·dense + (1-α)·sparse）：可调但需要标注数据校准权重
- Cross-encoder Reranker 兜底：召回阶段取并集，精排阶段统一打分，对长尾 query 效果显著
元数据硬过滤（Hard Filters）：在进行向量检索前，先基于 UserID、组织 ID、时间范围或业务标签进行硬过滤。这是多租户场景下最关键的数据隔离手段——若缺失，“张三的偏好被推给了李四”将演变为严重的隐私合规事故。建议在数据访问层强制注入隔离条件，而非依赖调用方传参。但此处存在工程权衡：在基于 HNSW 算法的向量库中，如果在海量图谱中对少数租户标签进行强过滤，极易破坏图结构的连通路径导致召回率骤降。对于高活跃的核心租户，更稳妥的做法是分配独立的 Collection 进行物理隔离。
检索方法优于写入策略（Retrieval Trumps Writing）
在记忆系统中，检索方法的选择对性能的影响远大于写入策略。Mem0 在 LoCoMo 上达到 91.6（较旧算法 +20 分），LongMemEval 上达到 93.4（+26 分），BEAM (1M) 上 64.1，平均每次检索仅消耗约 7K Token（对比全上下文方案 25K+）。这些数字反映的是新旧算法的整体效果对比，详见 Mem0 官方 benchmark 文档。
实验普遍表明，投入资源优化检索链路（Reranker、混合检索、图遍历）的 ROI 远高于优化写入链路。
⭐️ 生产级记忆系统需要哪些架构特性？
| 架构特性 | 核心问题 | 解决方案 |
|---|---|---|
| 多维索引 | 如何提升召回精度？ | 结合 Vector（捕捉语义）、Graph（捕捉关系）、Keyword（捕捉专有名词）三种索引 |
| 隐私合规 | 如何满足 GDPR 等法规要求？ | 在写入持久化存储前，进行 PII（个人身份信息）脱敏 |
| 冷热分离 | 如何平衡性能与成本？ | 高频偏好缓存 + 低频背景 RAG |
这套完整的记忆系统架构，使 Agent 能够像人类一样：短期记忆保持连贯，长期记忆积累经验，反思机制持续优化，遗忘机制过滤噪音——这是从“工具”进化为“数字协作伙伴”的基础能力。
一个设计良好的记忆系统应能回答三个核心问题：
- 智能体知道什么？（事实记忆 → 保持一致性）
- 智能体如何改进？（经验记忆 → 持续学习）
- 智能体当前思考什么？（工作记忆 → 上下文管理）
这三种能力的协同，使 Agent 从“即时反应”进化为“经验驱动的智能体”——通过结构化的多源信息融合，实现 Prompt + 当前输入 + 历史可用信息的有机组合。
⭐️ Markdown 如何存储 Agent 记忆
说了这么多向量库、知识图谱、记忆框架，你可能会问：有没有更轻量的方案？
还真有。当你认真审视 Agent 记忆的本质需求时，会发现一个反直觉的答案——Markdown 文件可能就是最务实的长期记忆载体。
为什么 Markdown 可以作为 Agent 记忆
Markdown 本质上是一种人和 Agent 都能读写的“显式长期记忆”。它不依赖数据库、不需要向量引擎、不用配置检索管道。
核心优势在于透明、可审查、可版本化、低成本：
- 透明可审计：随时打开文件，看得到 Agent 记住了什么、写入了什么。没有任何黑盒。
- 持久化：文件存活于磁盘，不依赖进程生命周期。进程崩溃、重启、换机器，记忆都在。
- 版本控制：记忆可以提交到 Git，回滚、分支、Code Review 随心所欲。
- 零迁移成本：标准格式，无供应商锁定。换模型、换框架，只需迁移文件。
- 成本极低：如果使用托管向量数据库和完整 RAG pipeline，成本和运维复杂度很容易上来；而 Markdown 文件在本地几乎没有额外成本。
Manus 把文件系统视为结构化的外部记忆；Claude Code 则把 CLAUDE.md 和 Auto Memory 明确产品化；OpenClaw 等 Agent 项目/社区实践中，也能看到类似的文件化记忆思路。它们共同说明：在很多 Agent 场景里，文件系统 + Markdown 已经是一个足够务实的长期记忆方案。
Claude Code 的 CLAUDE.md 机制
Claude Code 的记忆系统采用双轨制：CLAUDE.md（人工编写） 和 Auto Memory（自动积累）。
CLAUDE.md：该写什么、不该写什么
CLAUDE.md 本质上是给 AI 新人写的 onboarding 文档。写得不好还不如不写——一份臃肿的 CLAUDE.md 会让真正重要的规则被噪音淹没。
该写的东西：
- 技术栈和版本信息：框架版本差异往往是 AI 犯错的源头。你不标注 Spring Boot 版本，它会倾向于生成训练数据中更常见的版本用法。
- 常用命令：构建、测试、lint、启动——全部放在代码块里。代码块里的命令 Claude 倾向于照着跑，写在自然语言里的命令它可能根据自己的理解改写。
- 架构决策和背后的理由：光写规则不够，写清楚“为什么”能让 Claude 举一反三。比如“不要直接写 SQL，使用 QueryWrapper”——加上“因为 SQL 审计系统依赖 Wrapper 解析来记录操作日志”之后，Claude 在其他需要生成查询的地方也自觉用 Wrapper。
- 团队约定和项目特有的坑：提交信息格式、分支命名规范、环境变量依赖。这些 Claude 从代码里读不出来，但一个新入职的工程师一定会问。
不该写的东西：
- 代码风格规则（交给格式化工具）
- 语言或框架的默认行为（现代 Python 用 f-string 这种事写下来是噪音）
- 大段参考文档（给链接就行，Claude 需要时会自己去读）
一句话判断标准：逐行过一遍
CLAUDE.md，每条规则问自己——“如果没有这行，Claude 最近是不是真的犯过这个错”。如果答案是“好像没犯过”，那行就可以删。
怎么写才能让 Claude 真正遵守
规则要具体可验证。“注意代码可读性”没法验证；“函数名使用动词开头、单个函数不超过 40 行”可以验证。规则写得越具体，Claude 遵守的概率越高。
禁令要搭配替代方案。只说“不要做 X”会让 Claude 在遇到相关场景时卡住。更好的方式是“不要做 X，遇到这种情况应该做 Y”。实战例子：
# 依赖注入
- 不要使用 @Autowired 字段注入
- 使用构造器注入，配合 Lombok 的 @RequiredArgsConstructor
- 参考示例：UserController.java 中的写法善用标记词但别滥用。如果某条规则 Claude 反复违反，加 IMPORTANT: 或 YOU MUST: 能引起它的注意。但这招不能经常用——到处标“重要”的文件，等于什么都不重要。
工程提示：如果 Claude 反复忽略某条规则，不要急着加感叹号。更大的可能是文件太长了，规则被其他内容稀释了。解决方案是精简文件，不是加强调。
标题用常规名字。用 Commands、Structure、Conventions、Testing 这类在 README 里常见的标题。Claude 训练数据里有大量标准结构的 README，它对“这个标题下面通常写什么”有稳定的预期。
CLAUDE.md 文件的层级结构
| 层级 | 位置 | 作用范围 | 适用场景 |
|---|---|---|---|
| 组织级 | 系统目录（如 /etc/claude-code/CLAUDE.md） | 所有用户 | 公司编码规范、安全策略，任何设置都无法排除 |
| 用户级 | ~/.claude/CLAUDE.md | 个人所有项目 | 代码风格偏好、个人工具习惯 |
| 项目级 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 团队共享 | 项目架构、编码标准、工作流，提交至 Git |
| 本地级 | ./CLAUDE.local.md | 个人当前项目 | 沙箱 URL、测试数据偏好，加入 .gitignore |
文件加载遵循目录树向上查找规则——从当前工作目录逐级向上，同一目录内 CLAUDE.local.md 追加在 CLAUDE.md 之后，越靠近工作目录的规则优先级越高。
CLAUDE.md 不适合存什么：
- 大段日志和完整对话记录
- 敏感密钥、Token、账号信息
- 高频变化的运行时数据
- 可以实时查询的动态信息
分层管理：项目大了怎么组织
一个人的项目，一份 CLAUDE.md 够用。项目一大、团队一介入，就需要分层：
# `CLAUDE.md`（项目根目录）
## Project
Spring Boot 3.2 + MyBatis-Plus + MySQL 8.0 的订单管理服务。
## Commands
- 构建：`mvn clean package`
- 测试：`mvn test`
## Rules
- API 约定：@docs/api-conventions.md
- 数据库规范：@docs/database-rules.md用 @path/to/file 引用外部文件。注意：@ 引用会把整个文件内容嵌入上下文，如果被引用文件很大，每个会话启动时都会烧掉一大块指令预算。大文件改为自然语言引用——"架构细节参见 docs/architecture.md"，Claude 需要时会自己读取。
对于更细粒度的控制，可以用 .claude/rules/ 目录组织 path-scoped 规则：
---
paths:
- "src/main/java/**/controller/**/*.java"
---
# Controller 规范
- 统一使用 Result<T> 包装返回值
- 所有接口必须添加 Swagger 注解这样编辑 Controller 时只加载 Controller 的规则，编辑 Service 时只加载 Service 的规则。
Auto Memory（自动积累）：Claude 根据对话自动写入的笔记，包括调试模式、代码习惯、工作流偏好。它存在 ~/.claude/projects/<project>/memory/ 目录下，MEMORY.md 是入口文件，细节笔记在子文件中。
注意：Auto Memory 需要 Claude Code v2.1.59+，默认开启，可以通过 /memory 或 autoMemoryEnabled 配置关闭。
Markdown 记忆的层级设计
一个完整的 Markdown 记忆体系通常包含多个层级：
- 用户级记忆：存个人偏好和长期习惯，放在
~/.claude/CLAUDE.md。比如你偏好用 2-space 缩进、习惯先写测试再写代码、不喜欢用 emoji。 - 项目级记忆：存项目规范、技术栈、目录结构，放在仓库根目录的
CLAUDE.md。团队成员共享，通过 Git 同步。 - 子目录级记忆：存局部模块的专属规则，放在子目录的
CLAUDE.md。比如backend/下的 API 设计规范、docs/下的写作风格要求。 - 团队共享记忆：需要提交到仓库的共同约定。项目级的
CLAUDE.md和.claude/rules/目录下可版本化的规则文件。 - 私有记忆：不应该提交的个人工作流。
CLAUDE.local.md这类文件加入.gitignore，只存在本地。
Markdown 记忆和传统长期记忆的区别
不是所有场景都适合 Markdown，也不是所有场景都适合向量库。关键在于理解各自的适用边界：
| 维度 | Markdown 记忆 | 向量库记忆 | RAG 知识库 | 数据库型框架（Mem0等） |
|---|---|---|---|---|
| 检索精度 | 中等（依赖人工组织） | 高（语义相似度） | 高（语义检索） | 高（混合策略） |
| 调试体验 | 极佳：直接读写文件 | 中等：需向量查询工具 | 中等：需检索日志 | 复杂：需理解框架逻辑 |
| 部署成本 | 极低：只需文件读写 | 高：需维护向量服务 | 高：需 RAG pipeline | 高：需框架运行时 |
| 版本控制 | 原生集成 Git | 需额外同步机制 | 需额外同步机制 | 需额外同步机制 |
| 迁移成本 | 零：复制文件即可 | 高：锁定专有格式 | 高：锁定 pipeline | 极高：绑定框架 |
| 适用场景 | 偏好、约定、踩坑记录 | 多样化记忆检索 | 共享知识查询 | 复杂多源记忆管理 |
Markdown 的局限性也很明确：当你需要从海量非结构化文本中检索特定片段时，人工组织的 Markdown 会成为瓶颈。此时向量库的语义检索能力不可替代。
反过来，当你的记忆需求是“记住这个项目的编码规范”、“记住用户的报告偏好”这类明确、可结构化的信息时，Markdown 的简洁和可维护性完胜复杂系统。
Markdown 记忆的维护策略
这里以 CLAUDE.md 为例。
CLAUDE.md不是写完就完事的。项目在演进，规则也会过时。
- 添加规则要慢：一条新规则只有在 Claude 确实犯了一个错误、且这条规则能防止同类错误再次发生时，才值得写进去。为还没发生过的事预设规则，往往是在浪费空间。
- 删规则要果断：如果某条规则存在很久了，但删掉后 Claude 的行为没有变化，说明这条规则从一开始就没起作用——Claude 本来就会这么做。果断移除，把空间留给真正需要的规则。
- 错误驱动的持续进化：每次纠正 Claude 的错误后，追加一句“更新
CLAUDE.md，确保下次不再犯”。累积几次同类错误后归纳为一条精炼的规则，避免文件快速膨胀。
两个预警信号：
- 信号一：Claude 为已经写在文件里的规则道歉（比如“抱歉，我刚才忽略了 XX 规则”）。这说明这条规则的措辞有问题——换个更直接的表述。
- 信号二：同一条规则在不同会话中反复被违反。这通常不是措辞问题，而是整份文件太长了，规则被稀释了。解决方案不是改措辞，而是压缩整份文件。
两个实用的维护习惯：
- 对话式审查：每隔几周，找几个
CLAUDE.md里的规则问 Claude：“如果我删掉这条规则，你会改变行为吗？”如果它说不会，那这条规则可能就可以删。 - 用
/init但别直接用：自动生成的CLAUDE.md是一个合理的起点，但里面可能包含对项目不准确的描述。按原则逐条审查，删掉冗余、补上遗漏。
Git 做版本追踪 + Code Review：每一次重要记忆更新都 commit，遇到问题可以回滚，code review 可以追溯修改原因。团队共享内容的修改应该走 PR 流程。
总结
Agent 记忆系统解决的核心问题是：让 Agent 从无状态的“一次性工具”进化为有上下文的“长期协作伙伴”。
短期记忆依托上下文窗口，通过上下文缩减、卸载、隔离三类工程策略控制膨胀。长期记忆则通过“写入-检索”的双向机制，在新的 Session 中恢复历史沉淀的个性化经验。
本文的核心要点回顾：
- 记忆的两个层级：短期记忆（Session 级，利用上下文窗口）和长期记忆（跨 Session 级，通过向量库或文件持久化）
- 记忆的生命周期：编码 → 存储 → 提取 → 巩固 → 反思 → 遗忘。记忆系统不是只写不删，而是需要主动的代谢机制
- 技术选型看场景：向量库适合海量非结构化检索，Markdown 适合偏好、约定、踩坑这类明确可结构化的信息。两者不是替代关系，而是协作关系
- Claude Code 的双轨记忆：
CLAUDE.md（人工编写）和 Auto Memory（自动积累）各司其职，前者是你主动的指令，后者是 Claude 自学的笔记 CLAUDE.md的核心原则：写什么比怎么写更重要——只记录“Claude 真的犯过这个错”的规则；怎么写比写什么更重要——具体可验证、禁令搭配替代方案、别滥用标记词- 维护是持续的过程：添加要慢、删除要果断、错误驱动进化。定期用对话式审查检验规则的有效性
一个设计良好的记忆系统，能让 Agent 回答三个核心问题：智能体知道什么（事实记忆）、智能体如何改进（经验记忆）、智能体当前思考什么（工作记忆）。这三种能力的协同，才是“记忆”的完整含义。