memory-systems

记忆系统设计

使用此技能选择并实现满足检索、持久性和推理要求的最简持久化记忆层。

何时启用

• 构建必须跨会话持久保存知识的 Agent
• 在记忆框架（Mem0、Zep/Graphiti、Letta、LangMem、Cognee）之间进行选择
• 需要在不同对话中保持实体一致性
• 实现基于累积知识的推理
• 设计可在生产环境中扩展的记忆架构
• 根据基准（LoCoMo、LongMemEval、DMR）评估记忆系统
• 构建具备自动实体／关系提取和自我改进记忆能力的动态记忆（Cognee）

对于由其他技能负责的相邻工作，请勿启用此技能：

• 单次轨迹中的令牌预算、检索范围或前缀缓存：context-optimization。
• 作为上下文污染问题处理过时或冲突的记忆：context-optimization（诊断模式，references/degradation.md）。

核心概念

将记忆需求从易失性上下文到持久化存储进行分类。 默认选择满足检索需求的最简单层，因为基准证据表明，对于某些记忆工作负载而言，工具复杂度不如可靠检索重要（claim-memory-locomo-filesystem-baseline）。仅当检索质量下降，或 Agent 需要多跳推理、关系遍历或时间回溯查询时，才添加结构（图、时间有效性）。

详细主题

生产级框架概览

根据 Agent 所需的主要检索模式选择框架。使用下表缩小候选范围，然后结合下文的基准数据进行验证。

框架	架构	最适合	权衡
Mem0	向量存储 + 图记忆，可插拔后端	多租户系统、广泛集成	对多 Agent 的专门支持较少
Zep/Graphiti	时态知识图谱、双时态模型	需要关系建模 + 时态推理的企业	高级功能仅限云端
Letta	自我编辑式记忆，采用分层存储（上下文内/核心/归档）	需要全面 Agent 自省的场景、有状态服务	对简单用例而言过于复杂
Cognee	通过可定制的 ECL 流水线和可定制任务构建多层语义图	不断演进、能够适应和学习的 Agent 记忆；多跳推理	摄取阶段的处理开销较大
LangMem	用于 LangGraph 工作流的记忆工具	已采用 LangGraph 的团队	与 LangGraph 紧密耦合
文件系统	使用命名约定的普通文件	简单 Agent、原型开发	无语义搜索、无关系

当 Agent 需要双时态建模（同时追踪事件发生时间和摄取时间）时，选择 Zep/Graphiti，因为其三层知识图谱（事件、语义实体、社区子图）擅长处理时态查询。当优先考虑快速投入生产并使用托管基础设施时，选择 Mem0。当 Agent 需要通过其 Agent 开发环境进行深入自省时，选择 Letta。当 Agent 必须构建密集的多层语义图时，选择 Cognee——它将文本块和实体类型作为节点，并以详细的关系边连接；其每个核心环节（摄取、实体提取、后处理、检索）均可定制。

基准性能对比

参考这些基准来设定预期，但应将其视为特定来源针对检索维度提供的参考信号，而非绝对排名。没有任何单一基准具有决定性。

系统	DMR 准确率	LoCoMo	HotPotQA（多跳）	延迟
Cognee	—	—	已公布高分	不定
Zep（时态 KG）	已公布高分	—	各项指标处于中等水平	据报告延迟较低
Letta（文件系统）	—	已公布文件系统基线	—	—
Mem0	—	已公布专用工具基线	在一项对比中较低	—
MemGPT	已公布高分	—	—	不定
GraphRAG	已公布中高区间成绩	—	—	不定
向量 RAG 基线	已公布较低区间成绩	—	—	快

关键要点：应根据检索模式而非品牌比较记忆系统。将基准数据视为有时效性的证据；在据此提出产品声明之前，必须重新核验。稳定的设计原则是从浅层方案开始，衡量检索质量，只有在较简单的层无法满足需求时，才添加语义或图结构。

记忆层（决策点）

选择满足持久化要求的最浅记忆层。每深入一层，基础设施成本和运维复杂度都会增加，因此只有在较浅层无法满足检索或持久性需求时，才升级到更深层。

层级	持久性	实现方式	适用场景
工作记忆	仅限上下文窗口	系统提示词中的草稿区	始终适用 — 优先使用有利于注意力的位置进行优化
短期记忆	会话范围内	文件系统、内存缓存	中间工具结果、对话状态
长期记忆	跨会话	键值存储 → 图数据库	用户偏好、领域知识、实体注册表
实体记忆	跨会话	实体注册表 + 属性	维持身份一致性（“John Doe”在不同对话中指同一个人）
时态知识图谱	跨会话 + 历史记录	带有效时间区间的图	随时间变化的事实、时光回溯查询、防止上下文冲突

检索策略

根据查询类型选择检索策略。语义搜索适合直接事实查询，但处理多跳推理时效果会下降；基于实体的遍历适合“关于 X 的所有信息”这类查询，但需要图结构；时态过滤适合处理变化的事实，但需要有效性元数据。当准确性至关重要且基础设施预算充足时，可组合多种策略进行混合检索。

策略	适用场景	局限性
语义（嵌入相似度）	直接事实查询	处理多跳推理时效果会下降
基于实体（图遍历）	“告诉我关于 X 的所有信息”	需要图结构
时态（有效性筛选）	事实随时间变化	需要有效性元数据
混合（语义 + 关键词 + 图）	整体准确性最佳	基础设施需求最高

混合方法通过仅检索相关子图或记忆，减少活跃上下文。Cognee 通过图、向量和关系存储中的多种搜索模式实现混合检索，让 Agent 根据查询类型选择合适的检索策略，而不是对所有查询都采用同一种方法。

记忆整合

定期运行整合以避免记忆无限增长，因为不加控制地累积记忆会随着时间推移降低检索质量。使记忆失效，但不要丢弃 — 保留历史记录对于需要重建过去状态的时态查询至关重要。可在记忆数量达到阈值、检索质量下降或到达计划时间间隔时触发整合。可参阅实现参考中的可运行整合代码。

实用指南

选择记忆架构

从最简单的可行层开始，仅在检索质量下降时增加复杂度。 大多数 Agent 在第一天都不需要时态知识图谱。请按以下路径逐步升级：

1. 原型阶段：使用文件系统记忆。将事实保存为带时间戳的结构化 JSON。这样可以在投入基础设施之前验证 Agent 的行为。
2. 扩展阶段：当 Agent 需要语义搜索和多租户隔离时，改用 Mem0 或带元数据的向量存储，因为基于文件的查找无法处理相似度查询。
3. 复杂推理：当 Agent 需要关系遍历、时态有效性或跨会话综合时，添加 Zep/Graphiti。Graphiti 使用通用关系构建结构化关联，让图保持简单且易于推理；Cognee 则构建更稠密的多层语义图，并包含细致的关系边 — 根据 Agent 的需求选择：需要时态双模型（Graphiti），还是更丰富、相互关联的知识结构（Cognee）。
4. 完全掌控：当 Agent 必须通过深入自省来自主管理记忆时，使用 Letta 或 Cognee，因为这些框架将记忆操作作为 Agent 的一等操作公开。

与上下文集成

按需检索记忆，而不是预先加载所有内容，因为大型上下文负载成本高昂，还会降低注意力质量。将检索到的记忆放在更易获得关注的位置（上下文开头或结尾），以最大限度地影响生成结果。

错误恢复

妥善处理检索失败，因为记忆系统天然存在噪声。按以下顺序应用这些恢复策略：

• 检索结果为空：改用范围更广的搜索（移除实体筛选条件、扩大时间范围）。如果仍然没有结果，请用户澄清。
• 结果已过时：检查 valid_until 时间戳。如果大多数结果都已过期，则在重试前触发整合。
• 事实冲突：优先选择 valid_from 最新的事实。如果置信度较低，请向用户说明冲突。
• 存储失败：将写入操作排队以便重试。绝不要让记忆写入阻塞 Agent 的响应。

示例

示例 1：Mem0 集成

from mem0 import Memory

m = Memory()
m.add("User prefers dark mode and Python 3.12", user_id="alice")
m.add("User switched to light mode", user_id="alice")

# Retrieves current preference (light mode), not outdated one
results = m.search("What theme does the user prefer?", user_id="alice")

示例 2：时间查询

# Track entity with validity periods
graph.create_temporal_relationship(
    source_id=user_node,
    rel_type="LIVES_AT",
    target_id=address_node,
    valid_from=datetime(2024, 1, 15),
    valid_until=datetime(2024, 9, 1),  # moved out
)

# Query: Where did user live on March 1, 2024?
results = graph.query_at_time(
    {"type": "LIVES_AT", "source_label": "User"},
    query_time=datetime(2024, 3, 1)
)

示例 3：Cognee 记忆摄取与搜索

import cognee
from cognee.modules.search.types import SearchType

# Ingest and build knowledge graph
await cognee.add("./docs/")
await cognee.add("any data")
await cognee.cognify()

# Enrich memory
await cognee.memify()

# Agent retrieves relationship-aware context
results = await cognee.search(
    query_text="Any query for your memory",
    query_type=SearchType.GRAPH_COMPLETION,
)

指南

1. 从文件系统记忆开始；只有在检索质量有需要时才增加复杂性
2. 对任何可能随时间变化的事实跟踪其时间有效性
3. 使用混合检索（语义 + 关键词 + 图谱）以获得最佳准确性
4. 在达到数量阈值、检索质量下降或按计划执行时整合记忆——将其标记为失效，而不是丢弃
5. 针对检索失败进行设计：记忆查询无结果时，始终提供回退方案
6. 考虑持久化记忆的隐私影响（保留政策、删除权）
7. 在变更前后，使用 LoCoMo 或 LongMemEval 对记忆系统进行基准测试
8. 在生产环境中监控记忆增长和检索延迟

注意事项

1. 将所有内容塞进上下文：将所有可用记忆加载到提示词中成本高昂，还会降低注意力质量。应使用按需检索并筛选相关内容。
2. 忽略时间有效性：事实会过时。若不跟踪有效性，过时信息就会污染上下文，导致 Agent 基于错误假设采取行动。
3. 过早过度设计：在某些基准测试中，简单的文件系统记忆可能胜过更专业的工具（claim-memory-locomo-filesystem-baseline）。只有在简单方案明确失效时才增加复杂性。
4. 没有整合策略：记忆无限增长会导致检索质量随时间下降。设置记忆数量阈值或定期间隔，以触发整合。
5. 嵌入模型不匹配：使用一种嵌入模型写入记忆、另一种模型读取记忆，会导致检索效果不佳，因为向量空间不可互换。为每个记忆存储固定使用单一嵌入模型；如果模型发生变化，则重新嵌入所有条目。
6. 图谱架构僵化：结构过度严格的图谱架构（僵化的节点类型、固定的关系标签）会在领域演变时失效。优先使用通用关系类型和灵活的属性集合，这样新增实体类型时就不需要迁移架构。
7. 过时记忆污染：与当前状态矛盾的旧记忆会悄无声息地破坏 Agent 的行为。实施过期策略或置信度衰减，使 Agent 降低对旧事实的优先级；检测到矛盾时，应明确指出。
8. 记忆与上下文不匹配：检索到的记忆虽然主题相关，语境却不正确（例如，Agent 正在讨论 Python 语言时，检索到关于蟒蛇的“Python”记忆）。可在记忆条目中加入会话或领域元数据，并在检索时据此筛选。

集成

此技能负责持久化语义记忆。相邻技能负责临时存储、压缩和上下文策略：

• context-optimization：在活动上下文预算内进行即时记忆加载和检索范围限定；其诊断模式（references/degradation.md）会将过时或冲突的记忆作为上下文污染或冲突进行处理。
• multi-agent-patterns：跨 Agent 共享记忆。
• evaluation：记忆质量、检索正确性和基准选择。

参考资料

内部参考资料：

• 实现参考 - 适用场景：从头实现向量存储、属性图、时间查询或记忆整合逻辑

此合集中的相关技能：

• context-optimization（基础参考）- 适用场景：设计记忆所依赖的上下文层
• multi-agent-patterns - 适用场景：多个 Agent 需要共享或协调记忆状态

外部资源：

• Zep 时间知识图谱论文（arXiv:2501.13956）- 适用场景：评估双时间建模或 Graphiti 的架构
• Mem0 生产架构论文（arXiv:2504.19413）- 适用场景：评估托管记忆基础设施的权衡
• Cognee 优化知识图谱 + 大模型推理论文（arXiv:2505.24478）- 适用场景：比较多层语义图方法
• LoCoMo 基准（Snap Research）- 适用场景：评估长对话记忆保留能力
• MemBench 评估框架（ACL 2025）- 适用场景：设计记忆评估套件
• Graphiti 开源时间 KG 引擎（github.com/getzep/graphiti）- 适用场景：实现时间知识图谱
• Cognee 开源知识图谱记忆（github.com/topoteretes/cognee）- 适用场景：构建可定制的记忆 ECL 流水线
• Cognee 比较：形式与功能 - 适用场景：比较 Mem0、Graphiti、LightRAG 和 Cognee 的图结构