前言¶
很多 Agent 把「记忆」等同于当前会话里的上下文：对话一结束，用户偏好、实体关系、历史事实全部丢失。下一轮只能从零追问，或靠人工重复交代。向量 RAG、知识图谱、时序知识图谱等方案越来越多，但选型往往变成「先上 Mem0 / Zep / Cognee」，而不是先对齐检索形态与持久化层级。
下面介绍 memory-systems 这一 Agent Skill。它来自 Agent Skills for Context Engineering 集合，用结构化指南覆盖跨会话语义记忆、实体追踪、图/向量检索与记忆整合，并说明与同集合里 filesystem-context、context-compression 等技能的边界，避免把文件草稿、会话压缩和 token 优化误当成「长期记忆」设计。
这是什么¶
memory-systems 是一份面向生产 Agent 的 Memory System Design 说明（SKILL.md），不是可执行框架本身。维护方为 Agent Skills for Context Engineering Contributors；官方路径：
https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/memory-systems
Skill 元数据中的定位是：在 Agent 系统中处理 持久语义记忆——跨会话知识保留、实体追踪、时间有效性（temporal validity）、图或向量检索、记忆整合（consolidation），以及记忆基准（benchmark）选型。文件型 scratchpad 应交给 filesystem-context，可读交接摘要交给 context-compression，单次轨迹内的 token 策略交给 context-optimization。
核心功能¶
何时启用¶
在以下情况让 Agent 加载本 Skill：
- 需要跨会话持久化知识
- 在 Mem0、Zep/Graphiti、Letta、LangMem、Cognee 等框架间选型
- 要在多轮对话中保持实体身份一致
- 要对累积知识做推理，或设计可扩展的生产记忆架构
- 要用 LoCoMo、LongMemEval、DMR 等基准评估记忆系统
- 需要自动实体/关系抽取、可自我改进的动态记忆（如 Cognee）
不要用本 Skill 处理：文件草稿与工具输出卸载（filesystem-context）、会话压缩与人工可读交接（context-compression）、掩码、前缀缓存与检索范围（context-optimization）、基于 RDF 的 BDI 心智状态（bdi-mental-states）。
核心观念：从上下文到持久层的谱系¶
记忆是从易失的 context window 到持久存储的一条谱系。默认选 能满足检索需求的最浅层；资料指出，对部分记忆负载，工具复杂度不如可靠检索重要（claim-memory-locomo-filesystem-baseline）。仅在检索质量下降，或需要多跳推理、关系遍历、「时间旅行」查询时，再增加图结构或时间有效性。
生产框架对照¶
按主导检索模式缩小候选，再用基准数据验证预期（无单一基准可定论）：
| Framework | Architecture | Best For | Trade-off |
|---|---|---|---|
| Mem0 | Vector store + graph memory, pluggable backends | Multi-tenant systems, broad integrations | Less specialized for multi-agent |
| Zep/Graphiti | Temporal knowledge graph, bi-temporal model | Enterprise requiring relationship modeling + temporal reasoning | Advanced features cloud-locked |
| Letta | Self-editing memory with tiered storage (in-context/core/archival) | Full agent introspection, stateful services | Complexity for simple use cases |
| Cognee | Multi-layer semantic graph via customizable ECL pipeline | Evolving agent memory; multi-hop reasoning | Heavier ingest-time processing |
| LangMem | Memory tools for LangGraph workflows | Teams already on LangGraph | Tightly coupled to LangGraph |
| File-system | Plain files with naming conventions | Simple agents, prototyping | No semantic search, no relationships |
选型要点（摘自官方说明）：需要双时态（事件发生时间与写入时间）时倾向 Zep/Graphiti；要快上线、托管基础设施时倾向 Mem0；需要 Agent 深度自省与分层存储时倾向 Letta；需要可定制 ECL 管道与稠密多层语义图时倾向 Cognee。
记忆层级¶
选满足持久化需求的 最浅层，再按需加深：
| Layer | Persistence | Implementation | When to Use |
|---|---|---|---|
| Working | Context window only | Scratchpad in system prompt | 始终存在；注意注意力友好位置 |
| Short-term | Session-scoped | File-system, in-memory cache | 中间工具结果、会话状态 |
| Long-term | Cross-session | Key-value store → graph DB | 用户偏好、领域知识、实体注册表 |
| Entity | Cross-session | Entity registry + properties | 跨会话同一实体身份 |
| Temporal KG | Cross-session + history | Graph with validity intervals | 会变的事实、时点查询、避免上下文冲突 |
检索策略¶
按查询形态匹配策略；准确度优先且预算允许时采用混合检索：
| Strategy | Use When | Limitation |
|---|---|---|
| Semantic (embedding similarity) | 直接事实查询 | 多跳推理易退化 |
| Entity-based (graph traversal) | 「关于 X 的一切」 | 需要图结构 |
| Temporal (validity filter) | 事实随时间变化 | 需要有效性元数据 |
| Hybrid | 综合准确度 | 基础设施最重 |
记忆整合与实操路径¶
定期做 consolidation，避免记忆无限增长导致检索变差；原则是 Invalidate but do not discard——失效要标记，历史仍保留以供时序重建。可在记忆条数阈值、检索质量下降或定时任务时触发。
架构升级路径（官方 Practical Guidance）：
- 原型：文件系统 + 带时间戳的结构化 JSON，验证行为后再上基础设施。
- 扩展：需要语义检索与多租户隔离时，迁到 Mem0 或带元数据的向量库。
- 复杂推理：需要关系遍历、时间有效性或跨会话综合时，引入 Zep/Graphiti 或 Cognee。
- 完全自控：需要把记忆操作作为一等 Agent 动作时，考虑 Letta 或 Cognee。
与上下文集成时：即时加载（just-in-time），勿预灌全部记忆；检索结果放在上下文开头或结尾等注意力友好位置。检索失败时按顺序降级：放宽过滤 → 检查 valid_until → 冲突时优先较新 valid_from → 写入失败则排队重试且不阻塞回复。
安装与启用¶
本 Skill 为通用 SKILL.md 文本指令，仓库内无单独安装脚本。常见加载方式（与社区索引 awesome-agent-skills 一致，按所用 Agent 择一）：
Claude Code——将 Skill 目录或集合仓库加入技能列表：
/skills add https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering
若平台支持子路径，可指向 skills/memory-systems 目录；具体以 Claude Code 文档为准。
Vercel skills CLI——搜索、安装与管理：
npx skills find memory-systems
npx skills add muratcankoylan/Agent-Skills-for-Context-Engineering
npx skills list
Claude.ai / 其他客户端：可将 raw SKILL.md 地址粘贴到新对话，或由 Agent 在需要时读取该 URL（社区说明为「描述任务即可触发」，无额外配置项）。
Cursor：将 Skill 内容放入项目或用户级 Skills 配置后，在构建跨会话记忆、选型框架或设计整合策略时，在对话中明确要求遵循 memory-systems 指南。
启用后无需改代码；Agent 在匹配「When to Activate」场景时应加载全文，并可在需要实现细节时参考同目录 references/implementation.md（向量库、属性图、时序查询与整合逻辑）。
典型用法¶
官方在 SKILL.md 中给出三类可对照实现的示例（以下为原文结构，需自备对应 SDK 与环境）。
示例 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
await cognee.add("./docs/")
await cognee.add("any data")
await cognee.cognify()
await cognee.memify()
results = await cognee.search(
query_text="Any query for your memory",
query_type=SearchType.GRAPH_COMPLETION,
)
设计会话时，可先让 Agent 按 Skill 中的 Guidelines checklist 自检：从文件系统起步、为可变事实记录时间有效性、混合检索、定期整合、检索失败有回退、关注隐私与保留策略、用 LoCoMo 或 LongMemEval 做变更前后对比、监控体量与延迟。
适用场景与注意¶
适合谁
- 正在设计或重构 Agent 持久化层的后端与平台工程师
- 需要在 Mem0 / Graphiti / Cognee 等之间做技术选型的团队
- 要解决跨会话实体一致、事实随时间变化、多跳推理检索的产品场景
限制与常见坑（摘自官方 Gotchas）
- 把所有记忆塞进 prompt：成本高且损害注意力；应 JIT 检索并过滤。
- 忽略时间有效性：过期事实会污染上下文。
- 过早过度工程：部分基准上简单文件记忆仍可能表现不差；应在实测失败后再加深结构。
- 无整合策略：记忆无限增长会拖垮检索。
- 读写使用不同 embedding 模型：向量空间不兼容，需固定模型或在变更时全量重嵌。
- 图 schema 过 rigid：领域演化时易碎；倾向通用关系类型与灵活属性。
- 相关但语境错误的记忆（如 Python 语言 vs 蟒蛇）：应在条目中带会话/领域元数据并在检索时过滤。
与同集合技能的衔接：filesystem-context 管草稿与日志；context-compression 管摘要交接；context-optimization 管单次轨迹内的加载与预算；multi-agent-patterns 管多 Agent 共享记忆；evaluation 管记忆质量与基准选择。
结尾¶
跨会话记忆往往是 Agent 产品与「单次聊天机器人」的分水岭之一。memory-systems 不提供替代框架的代码，而是把层级、检索形态、框架对照、整合与评测约束写成可复用的设计清单，并明确与其他 Context Engineering Skill 的分工。落地时建议从最浅层验证检索质量，再按官方 escalation 路径加深；基准数字仅作 dated evidence，产品宣称前需重新核对。
官方 Skill 目录：
https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/memory-systems
完整指令原文（raw）：
https://raw.githubusercontent.com/muratcankoylan/Agent-Skills-for-Context-Engineering/main/skills/memory-systems/SKILL.md
