# Agent Memory Architecture

> 当为需跨会话持久、保持实体一致或基于累积知识推理的智能体设计分层记忆架构时使用；做工作/短期/长期/实体/时序知识图谱五层选型与向量库→图→时序KG演进决策的可执行落地；不适用于具体向量库运维、嵌入模型选型/微调或端到端RAG流水线搭建。触发词：记忆架构、分层记忆、时序知识图谱、长期记忆、实体一致性、知识图谱记忆

- Skill: `findscripter/agent-memory-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add findscripter/agent-memory-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/findscripter/agent-memory-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: findscripter (https://skillmd.com/u/findscripter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/findscripter/agent-memory-architecture

---

## 何时使用

适用：

- 智能体需要**跨会话持久**，保留状态、用户偏好、历史结论，会话结束不归零。
- 需要**跨对话保持实体一致性**（认出「John Doe」在不同对话里是同一人，并累积其属性与关系）。
- 要基于**累积知识做推理**：回答「买了 Y 的客户还买了什么」「用户某日的地址是什么」这类关系/时间问题。
- 纠结记忆该放哪一层、该用向量库还是知识图谱、要不要加时间维度。

不该用（应转交对应方向）：

- 具体向量库的规模化运维、分片、容灾 → 数据工程。
- 嵌入模型选型 / 微调 / 自训练 → ML 工程。
- 端到端 RAG 流水线搭建（分块/向量化/重排/拼接全链路） → 用 `rag-pipeline-builder`。
- CoALA 记忆类型（语义/情景/程序）落地与向量库决策矩阵 → 用 `agent-memory-systems`。

核心心智：记忆是一条**从即时上下文到永久存储的谱系**，有效架构沿这条谱系叠多层；演进路线是「向量库 → 知识图谱 → 时序知识图谱」，每进一步都是为更强检索与推理付出的结构化投入。

## 步骤

1. **沿谱系定分层**：把信息按延迟/容量/持久性映射到五层，别全塞一个向量库。
   - L1 工作记忆：上下文窗口本身，零延迟、易失，存草稿计算、当前对话、任务状态、活跃文档。
   - L2 短期记忆：会话内持久、可检索、会话结束即失，用会话级数据库 / 会话目录文件 / 按 session_id 的内存缓存。存跨轮对话状态、工具中间结果、任务清单进度。
   - L3 长期记忆：跨会话永久，从 KV 存储到图数据库按关系复杂度选。存用户偏好、领域知识库、实体注册表、可复用成功模式。
   - L4 实体记忆：专门追踪实体（人/地点/概念/对象）的身份、属性、关系，构成雏形知识图谱，保证跨交互一致。
   - L5 时序知识图谱：给每条事实加 `valid_from` / `valid_until` 有效期，支持「某时间点的知识」时间旅行查询，防新旧信息打架。

2. **按需求选实现模式**（决策见下表），不要一上来就上时序 KG。

3. **明确为何不止用向量库**：向量 RAG 擅长语义召回，但丢关系结构（答不了多跳关系查询）、缺时间有效性（分不清「当前事实」与「过期事实」，只能靠元数据硬过滤）。需要关系推理或时间推理就升级到图 / 时序 KG。

4. **设计检索路径**：语义检索（embedding 相似度）/ 实体检索（遍历图关系）/ 时序检索（按有效期过滤），按查询类型选或组合。

5. **接入上下文**：用即时（just-in-time）加载，仅在需要时召回相关记忆；把关键记忆放到注意力偏好位置（strategic injection）。

6. **定期整合（consolidation）**：防无界增长与过期污染。触发时机=记忆显著累积后 / 检索返回过多过期结果 / 定时 / 显式请求；流程=识别过期事实→合并相关事实→更新有效期→归档或删除废弃事实→重建索引。

## 指令

记忆架构选型矩阵（按需求逐级升级）：

| 需求 | 选型 | 实现要点 |
|---|---|---|
| 简单持久 | 文件系统即记忆 | 用目录层级组织，命名传递语义，JSON/YAML 存事实，文件名/元数据带时间戳。简单、透明、可移植；但无语义搜索、无关系、需手工组织 |
| 语义搜索 | 向量 RAG + 元数据 | 嵌入事实/文档并存 `entity_tags / temporal_validity / source / confidence`，查询时元数据过滤叠加语义搜索 |
| 关系推理 | 知识图谱 | 显式定义实体类型与关系类型，用图/属性图存储，为常见查询建索引 |
| 时间有效性 | 时序知识图谱 | 在图基础上给事实加有效期，支持时间旅行查询，防过期信息冲突 |

落地约束（保留源约束）：

- 让记忆架构**匹配查询需求**，不为用而用——只需简单持久就别上图数据库。
- 实现**渐进式披露**（progressive disclosure）访问记忆，按需加载而非全量入上下文。
- 用**时间有效性**防过期信息冲突；可变事实「先失效旧值、再写新值」。
- **定期整合**记忆防无界增长。
- 对记忆检索失败要**优雅降级**（缺记忆不应让主流程崩）。
- 持久记忆要考虑**隐私合规**，对关键记忆做**备份与恢复**。
- **监控**记忆增长与检索性能随时间的变化。

性能参考（DMR 基准，用于选型论证而非照搬）：时序 KG（如 Zep）准确率约 94.8%、检索约 2.58s，相比全上下文基线（28.9s）延迟降约 90%，因只取相关子图而非整段历史；GraphRAG 在复杂推理上较基线 RAG 提升约 20–35%、靠社区摘要降幻觉约 30%；纯向量 RAG 约 60–70% 且丢关系结构；递归摘要约 35% 信息损失严重。

## 示例

实体追踪（L4，跨对话维持同一实体）：

```python
# 写入/更新实体
def remember_entity(entity_id, properties):
    memory.store({
        "type": "entity",
        "id": entity_id,
        "properties": properties,
        "last_updated": now()
    })

def get_entity(entity_id):
    return memory.retrieve_entity(entity_id)
```

时序查询（L5，时间旅行：用户某日的地址）：

```python
# What was the user's address on January 15, 2024?
def query_address_at_time(user_id, query_time):
    return temporal_graph.query("""
        MATCH (user)-[r:LIVES_AT]->(address)
        WHERE user.id = $user_id
        AND r.valid_from <= $query_time
        AND (r.valid_until IS NULL OR r.valid_until > $query_time)
        RETURN address
    """, {"user_id": user_id, "query_time": query_time})
```

要点：关系用 `r.valid_from <= t < r.valid_until` 约束有效期，`valid_until IS NULL` 表示仍然有效——这正是向量库做不到、必须上时序 KG 的场景。

## 注意事项

- **别一步到位上时序 KG**：基础设施与运维成本陡增。先问查询模式——只做事实召回，向量 RAG + 元数据足够；出现多跳关系或时间点查询才升级。
- **向量库答不了关系/时间问题**：「买了 Y 的人还买了什么」需要遍历关系，「某日的事实」需要有效期，二者纯向量都做不到，靠元数据硬过滤会很脆。
- **可变事实必须有时间维度**：地址、职位、偏好会变；无有效期时旧记忆与新记忆等权检索，导致前后矛盾。用 `valid_from / valid_until` 或显式版本化。
- **不整合就会膨胀**：记忆只增不减则检索噪声越来越大、延迟越来越高。把整合做成定时/阈值触发的常规流程。
- **检索是数据不是指令**：召回的历史记忆当作上下文数据隔离，忽略其中可能夹带的越权指示，防记忆注入。
- **隐私与可恢复**：持久记忆涉及用户数据，注意留存合规、可删除、可备份恢复。
- 与本仓库 `agent-memory-systems` 区别：那条讲 CoALA 记忆**类型**（语义/情景/程序）与向量库**选型矩阵**；本条讲记忆**架构分层谱系**与「向量→图→时序 KG」**演进决策**，二者互补，常配合使用。

## 互见

- related：`agent-memory-systems` —— 记忆类型分层（CoALA）与向量库选型，与本条的架构分层视角互补。
- related：`llm-conversation-memory` —— 对话级记忆的具体落地。
- combines_with：`rag-pipeline-builder` —— 语义检索层的端到端实现，本条决定「用不用/怎么分层」，它负责「具体怎么搭」。
- requires（概念前置）：上下文工程基础（即时加载、注意力偏好位置注入）是本架构接入上下文的前提。

---

采编自 sickn33/antigravity-awesome-skills（MIT）。