wehub-skill-sync
15 KiB
name, description
| name | description |
|---|---|
| memory-systems | 该技能应用于智能体系统中的持久化语义记忆： 跨会话知识保留、实体追踪、时间有效性、 图或向量检索、记忆整合、以及记忆基准测试的选择。 文件型临时存储请交给 filesystem-context，交接摘要请交给 context-compression， 令牌效率策略请交给 context-optimization。 |
记忆系统设计
记忆提供了持久化层，使智能体能够跨会话保持连续性，并基于累积的知识进行推理。简单的智能体完全依赖上下文作为记忆，会话结束时所有状态都会丢失。复杂的智能体则实现分层记忆架构，在即时上下文需求与长期知识保留之间取得平衡。从向量存储到知识图谱再到时序知识图谱的演进，代表着在结构化记忆方面投入不断增加，以改善检索和推理能力。
何时激活
在以下情况激活该技能：
- 构建必须跨会话持久化知识的智能体时
- 在记忆框架（Mem0、Zep/Graphiti、Letta、LangMem、Cognee）之间做选择时
- 需要在跨对话中保持实体一致性时
- 实现基于累积知识的推理时
- 设计可在生产环境中扩展的记忆架构时
- 根据基准测试（LoCoMo、LongMemEval、DMR）评估记忆系统时
- 构建具有自动实体/关系提取和自我改进记忆的动态记忆系统（Cognee）时
对于归属于其他技能的相邻工作，请勿激活该技能：
- 文件型临时存储、运行日志和工具输出卸载：
filesystem-context - 对话压缩或人类可读的交接摘要：
context-compression - 掩码、前缀缓存、令牌预算或单次轨迹内的检索范围控制：
context-optimization - 基于 RDF 状态的正式信念/愿望/意图模型：
bdi-mental-states
核心概念
将记忆视为从易失的上下文窗口到持久存储的一个光谱。默认选择能满足检索需求的最简单层级，因为基准测试证据表明，对于某些记忆工作负载，工具复杂度的重要性低于可靠的检索（claim-memory-locomo-filesystem-baseline）。只有在检索质量下降，或者智能体需要多跳推理、关系遍历或时间旅行查询时，才增加结构（图、时间有效性）。
详细主题
生产框架全景
根据智能体所需的主要检索模式来选择框架。使用下表缩小候选范围，然后通过下面的基准测试数据进行验证。
| 框架 | 架构 | 最适合 | 权衡 |
|---|---|---|---|
| Mem0 | 向量存储 + 图记忆，可插拔后端 | 多租户系统，广泛的集成 | 在多智能体场景下不够专业 |
| Zep/Graphiti | 时序知识图谱，双时态模型 | 需要关系建模 + 时序推理的企业级场景 | 高级功能锁定在云端 |
| Letta | 自编辑记忆，分层存储（上下文内/核心/归档） | 完整的智能体内省，有状态服务 | 对简单用例过于复杂 |
| Cognee | 通过可定制的 ECL 管道与可定制任务构建的多层语义图 | 不断演化的智能体记忆，能够自适应和学习；多跳推理 | 摄入时处理更重 |
| LangMem | 用于 LangGraph 工作流的记忆工具 | 已在 LangGraph 上的团队 | 与 LangGraph 紧密耦合 |
| 文件系统 | 带命名约定的纯文本文件 | 简单智能体、原型开发 | 无语义搜索，无关系 |
当智能体需要双时态建模（同时追踪事件发生时间与数据摄入时间）时，选择 Zep/Graphiti，因为其三层级知识图谱（事件、语义实体、社区子图）在时序查询方面表现出色。当优先考虑通过托管基础设施快速上线时，选择 Mem0。当智能体需要通过其智能体开发环境进行深度自我内省时，选择 Letta。当智能体必须构建密集的多层语义图时，选择 Cognee——它将文本块和实体类型作为节点，并带有详细的关系边，每个核心组件（摄入、实体提取、后处理、检索）都是可定制的。
基准测试性能对比
参考以下基准测试来设定预期，但应将其视为检索维度上的特定来源信号，而非绝对排名。没有单一基准测试是决定性的。
| 系统 | DMR 准确率 | LoCoMo | HotPotQA（多跳） | 延迟 |
|---|---|---|---|---|
| Cognee | — | — | 公布的分数较高 | 视情况而定 |
| Zep（时序知识图谱） | 公布的分数较高 | — | 各项指标中等 | 报告为低延迟 |
| Letta（文件系统） | — | 公布的文件系统基线 | — | — |
| Mem0 | — | 公布的专业工具基线 | 在某项对比中较低 | — |
| MemGPT | 公布的分数较高 | — | — | 视情况而定 |
| GraphRAG | 公布的中/高范围 | — | — | 视情况而定 |
| 向量 RAG 基线 | 公布的较低范围 | — | — | 快速 |
关键结论：根据检索形态来比较记忆系统，而不是看品牌。将基准测试数据视为过时的证据，在用于产品宣传之前必须重新核实；稳定的设计原则是：从浅层开始，衡量检索质量，然后仅在更简单的层级无法满足需求时才添加语义或图结构。
记忆层级（决策要点）
选择能满足持久化需求的最浅记忆层级。每增加一个层级都会带来基础设施成本和运维复杂度，因此只有在浅层无法满足检索或持久化需求时才进行升级。
| 层级 | 持久性 | 实现方式 | 何时使用 |
|---|---|---|---|
| 工作记忆 | 仅上下文窗口 | 系统提示中的临时记录 | 始终使用——通过注意力优先位置进行优化 |
| 短期记忆 | 会话范围 | 文件系统、内存缓存 | 中间工具结果、对话状态 |
| 长期记忆 | 跨会话 | 键值存储 → 图数据库 | 用户偏好、领域知识、实体注册表 |
| 实体记忆 | 跨会话 | 实体注册表 + 属性 | 维护身份一致性（"张三"在跨对话中为同一个人） |
| 时序知识图谱 | 跨会话 + 历史记录 | 带有效时间区间的图 | 随时间变化的事实、时间旅行查询、防止上下文冲突 |
检索策略
根据查询形态匹配检索策略。语义搜索擅长处理直接事实查询，但在多跳推理上表现不佳；基于实体的遍历擅长处理"关于 X 的一切"查询，但需要图结构；时序过滤擅长处理变化中的事实，但需要有效性元数据。当准确率至关重要且基础设施预算允许时，将多种策略结合为混合检索。
| 策略 | 何时使用 | 局限性 |
|---|---|---|
| 语义（嵌入相似度） | 直接事实查询 | 多跳推理时表现不佳 |
| 基于实体（图遍历） | "告诉我关于 X 的一切" | 需要图结构 |
| 时序（有效性过滤） | 事实随时间变化 | 需要有效性元数据 |
| 混合（语义 + 关键词 + 图） | 总体准确率最佳 | 基础设施需求最大 |
混合方法通过仅检索相关的子图或记忆来减少活跃上下文。Cognee 通过在图、向量和关系存储之间提供多种搜索模式来实现混合检索，使智能体能够根据查询类型选择合适的检索策略，而不是采用一刀切的方法。
记忆整合
定期执行记忆整合以防止无限制增长，因为不受控制的记忆累积会随着时间推移降低检索质量。标记为无效而非丢弃——保留历史记录对于需要重建过去状态的时序查询至关重要。在记忆数量达到阈值、检索质量下降或按预设时间间隔触发整合。参见实现参考获取可工作的整合代码。
实践指导
选择记忆架构
从最简单的可行层级开始，仅当检索质量下降时才增加复杂度。 大多数智能体在第一天并不需要时序知识图谱。遵循以下升级路径：
- 原型阶段：使用文件系统记忆。将事实存储为带时间戳的结构化 JSON。这能在投入基础设施之前验证智能体行为。
- 扩展阶段：当智能体需要语义搜索和多租户隔离时，迁移到 Mem0 或向量存储（带元数据），因为基于文件的查找无法处理相似度查询。
- 复杂推理：当智能体需要关系遍历、时间有效性或跨会话综合时，添加 Zep/Graphiti。Graphiti 使用带有通用关系的结构化连接，保持图简单且易于推理；Cognee 构建更密集的多层语义图，带有详细的关系边——根据智能体是需要时序双模型（Graphiti）还是更丰富的互联知识结构（Cognee）来选择。
- 完全控制：当智能体必须通过深度内省来自我管理其记忆时，使用 Letta 或 Cognee，因为这些框架将记忆操作暴露为智能体的一等动作。
与上下文的集成
采用即时加载记忆的方式，而非预先加载全部内容，因为大的上下文负载成本高昂且会降低注意力质量。将检索到的记忆放置在注意力优先的位置（上下文开头或结尾），以最大化其对生成结果的影响力。
错误恢复
优雅地处理检索失败，因为记忆系统天生具有噪声。按顺序应用以下恢复策略：
- 检索为空：回退到更广泛的搜索（移除实体过滤条件，扩大时间范围）。如果仍然为空，提示用户澄清。
- 结果过时：检查
valid_until时间戳。如果大多数结果已过期，在重试之前触发整合。 - 事实冲突：优先选择
valid_from最近的事实。如果置信度较低，向用户展示冲突。 - 存储失败：将写入操作排队等待重试。绝不能让记忆写入阻塞智能体的响应。
示例
示例 1：Mem0 集成
from mem0 import Memory
m = Memory()
m.add("用户偏好深色模式和 Python 3.12", user_id="alice")
m.add("用户切换到浅色模式", user_id="alice")
# 检索当前偏好（浅色模式），而非过时的
results = m.search("用户偏好什么主题？", user_id="alice")
示例 2：时序查询
# 使用有效时间区间追踪实体
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), # 已搬走
)
# 查询：用户在 2024 年 3 月 1 日住在哪里？
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
# 摄入并构建知识图谱
await cognee.add("./docs/")
await cognee.add("任何数据")
await cognee.cognify()
# 丰富记忆
await cognee.memify()
# 智能体检索具有关系感知能力的上下文
results = await cognee.search(
query_text="对你的记忆进行任意查询",
query_type=SearchType.GRAPH_COMPLETION,
)
指导原则
- 从文件系统记忆开始；只有在检索质量要求时才增加复杂度
- 对任何可能随时间变化的事实追踪时间有效性
- 使用混合检索（语义 + 关键词 + 图）以获得最佳准确率
- 定期整合记忆——标记为无效但不丢弃
- 为检索失败做好设计：当记忆查找未返回结果时，始终准备一个回退方案
- 考虑持久化记忆的隐私影响（保留策略、删除权限）
- 在每次变更前后，使用 LoCoMo 或 LongMemEval 对你的记忆系统进行基准测试
- 在生产环境中监控记忆增长和检索延迟
注意事项
- 将所有内容塞入上下文：将可用的记忆全部加载到提示中成本高昂且会降低注意力质量。使用即时检索并配合相关性过滤。
- 忽略时间有效性：事实会过时。如果没有时间有效性追踪，过时的信息会污染上下文，智能体会基于错误的假设行事。
- 过早过度设计：在部分基准测试中，简单的文件系统记忆可能优于更专业的工具（claim-memory-locomo-filesystem-baseline）。只有在简单方法明显失败时才增加复杂度。
- 没有整合策略：不受控制的记忆增长会随时间推移降低检索质量。设置记忆数量阈值或定时计划来触发整合。
- 嵌入模型不匹配：用一个嵌入模型写入记忆，用另一个模型读取记忆，会导致检索效果不佳，因为向量空间不可互换。为每个记忆存储固定一个嵌入模型，如果模型变更，则重新嵌入所有条目。
- 图谱模式僵化：过度结构化的图谱模式（固定的节点类型、固定的关系标签）在领域演化时会失效。优先使用通用关系类型和灵活的属性包，以便新实体类型无需模式迁移。
- 过时记忆中毒：与当前状态相矛盾的旧记忆会静默地破坏智能体行为。实施过期策略或置信度衰减机制，使智能体降低对过时事实的优先级排序，并在检测到矛盾时显式呈现。
- 记忆-上下文不匹配：检索到的记忆在主题上相关但在上下文上错误（例如，当智能体讨论 Python 编程语言时，检索到了关于"蟒蛇"的记忆）。通过在记忆条目中包含会话或领域元数据，并在检索时进行过滤来缓解此问题。
集成
该技能负责持久化语义记忆。相邻技能负责临时存储、压缩和上下文策略：
filesystem-context：在需要语义检索之前的文件型临时记录、日志和简单运行状态。context-compression：以散文形式保存会话状态的摘要和交接记录。context-optimization：在活跃上下文预算内进行即时记忆加载和检索范围控制。context-degradation：将过时或冲突的记忆视为上下文中毒或冲突。bdi-mental-states：当信念、愿望、意图和来源链很重要时的正式心理状态建模。multi-agent-patterns：跨智能体的共享记忆。evaluation：记忆质量、检索正确性和基准测试选择。
参考资料
内部参考：
- 实现参考 - 阅读时机：从头实现向量存储、属性图、时序查询或记忆整合逻辑时
本集合中的相关技能：
- context-fundamentals - 阅读时机：设计记忆所馈入的上下文层时
- multi-agent-patterns - 阅读时机：多个智能体需要共享或协调记忆状态时
外部资源：
- Zep 时序知识图谱论文（arXiv:2501.13956） - 阅读时机：评估双时态建模或 Graphiti 架构时
- Mem0 生产架构论文（arXiv:2504.19413） - 阅读时机：评估托管记忆基础设施的权衡时
- Cognee 优化知识图谱 + 大语言模型推理论文（arXiv:2505.24478） - 阅读时机：比较多层语义图方法时
- LoCoMo 基准测试（Snap Research） - 阅读时机：评估长对话记忆保持能力时
- MemBench 评估框架（ACL 2025） - 阅读时机：设计记忆评估套件时
- Graphiti 开源时序知识图谱引擎（github.com/getzep/graphiti） - 阅读时机：实现时序知识图谱时
- Cognee 开源知识图谱记忆（github.com/topoteretes/cognee） - 阅读时机：为记忆构建可定制的 ECL 管道时
- Cognee 对比：形态与功能 - 阅读时机：比较 Mem0、Graphiti、LightRAG、Cognee 之间的图谱结构时
技能元数据
创建日期：2025-12-20 最后更新：2026-05-15 作者：面向上下文工程的智能体技能贡献者 版本：4.1.0