# Memory System

为 Agent 设计、实现或评估用户记忆系统时使用, , 涵盖记忆能力三层次评估框架、轨迹与长期记忆分层、Simple Notes 到 Advanced JSON Cards...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill memory-system -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill memory-system -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill memory-system -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill memory-system -g -a gemini-cli -y`

## Description

为 Agent 设计、实现或评估用户记忆系统时使用, , 涵盖记忆能力三层次评估框架、轨迹与长期记忆分层、Simple Notes 到 Advanced JSON Cards 及可执行代码的存储格式选型、Mem0/Memobase 框架取舍、记忆压缩整理与隐私脱敏，以及何时该用记忆而非 RAG 的判断。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 用户记忆系统

## 何时使用
- 为 Agent 设计跨会话的用户记忆（记住偏好、身份、历史交互）
- 选型记忆存储格式（Simple Notes / Enhanced Notes / JSON Cards / Advanced JSON Cards / 可执行代码）
- 评估记忆系统好坏（对照三层次框架或 LoCoMo 基准）
- 集成、改造或对比 Mem0、Memobase 等记忆框架
- 处理记忆冲突、过期、膨胀、压缩与隐私脱敏
- 判断某类信息该进用户记忆还是共享知识库
- 设计记忆的压缩与定期整理策略

## 核心原则
- 记忆与 RAG 的边界：**单个用户的个性化信息**（偏好、身份、关系、历史）走用户记忆；**面向所有用户共享的集体知识**（行业法规、公司流程、专业文档）走 RAG 知识库。两者尺度不同但底层技术相通（向量检索、知识压缩），也面临同样的麻烦：信息冲突、知识过期、检索不准。用户记忆同样可以反过来用 RAG 技术增强召回。
- 记忆不是逐句存档：会话结束后用一次专门的 LLM 调用提取，提取结果须同时满足三条规则, , **选择性**（丢弃"搜索返回 3 个选项"这类短期细节）、**抽象化**（把本次"靠窗座位"归纳为长期偏好）、**结构化**（用可检索字段保存事实）。
- 先立评估标尺再设计。记忆能力可归纳为八项：个人信息保留、偏好追踪、上下文切换、记忆更新、多会话连续性、复杂思考、时间感知、冲突解决。工程上按三层次验收：
  - **L1 基础回忆**：精确存取用户直接给出的结构化事实（"我的会员号是 12345"）。
  - **L2 多会话检索**：跨对象、跨时期找全相关信息并主动澄清（用户有两辆车时问"为哪辆预约"，而不是猜一辆）。
  - **L3 主动服务**：综合很久以前的记忆给出预见性帮助（订国际航班时关联数月前存储的护照信息并预警临期）。
  - 公开基准可参考 **LoCoMo**（平均约 300 轮、最多 35 个会话的超长多轮对话）。
- 三个正交维度分开决策，勿混淆：**放哪里**（轨迹 / 用户长期记忆 / 业务状态）、**怎么存**（四种格式）、**存什么**（情景 / 语义 / 程序记忆）。三者可自由组合。
- 轨迹（Trajectory）是单次运行的 append-only 原始流水，供追溯调试审计；运行时上下文可对它压缩重组。用户长期记忆是跨会话持久化、与用户 ID 绑定的档案，会被反复改写、合并、淘汰。前者是流水账，后者是档案。
- 认知类型指导"存什么"：情景记忆记具体事件（订了哪班航班），语义记忆存提炼出的稳定特征（用户是素食者），程序记忆学行为流程（先搜直飞→确认座位→用常旅客号）。
- 选格式看工程需求（简单性与表达力的取舍），选类型看业务场景（需要记住事实、事件还是流程）, , 两套体系正交，分别决策。
- 格式选型按关键性与数量：
  - **Simple Notes**：最小不可分事实，开销最低、O(1) 操作，但关联性丢失，综合查询需重新拼凑碎片。
  - **Enhanced Notes**：完整上下文段落，语义丰富，但存储冗余、更新需重写多个段落。
  - **JSON Cards**：类别→子类别→键值对三层嵌套，支持部分更新、可预测可扩展，但强制单一归类会丢失多维性（"周末用 Python 开发个人项目"同时是时间/技术/活动偏好）。
  - **Advanced JSON Cards**：事实之外加 backstory（为何存储）、person、relationship（为谁存储）和时间戳，解决同名实体消歧（用户自己的牙科张医生 vs 父亲的心脏科张医生）。
  - 经验法则：**关键且少量**（偏好、关键人物关系）用 Advanced JSON Cards；**大量且非关键**的对话事实用 Simple Notes；生产系统多为混合模式，不同类别走不同路径。

  四种格式速查：

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/memory-system/SKILL.md