---
tags: [AI, memory, context]
阶段: 08-Agent与工程化
难度: ★★☆
created: 2026-10-18
related: "[[Agent工作流与编排]], [[RAG原理与流程]], [[向量数据库]], [[上下文工程与Few-shot]]"
---

# Agent记忆与上下文

## 定义

**记忆**（memory）指系统在单次模型调用之外保存、并可在后续轮次重新取用的信息集合。上下文窗口内的消息是记忆，持久存储中的条目也是记忆；区别在于容量、访问方式与生命周期。按位置分为三层：

1. **工作记忆**（working memory）：当前上下文窗口中的消息序列，模型每次调用都完整读取。
2. **会话摘要**（summary）：对较早轮次的压缩表示，占用少量上下文，保留约束与结论。
3. **长期记忆**（long-term memory）：上下文之外的存储，按查询检索后注入上下文，载体为向量库或键值库。

上下文预算约束写为

$$
B\ \ge\ T_{\text{sys}}+T_{\text{tools}}+T_{\text{work}}+T_{\text{sum}}+T_{\text{ret}}+T_{\text{out}},
$$

当工作记忆占比超过阈值时触发压缩：

$$
\rho=\frac{T_{\text{work}}}{B-T_{\text{fixed}}}>\alpha
\quad\Longrightarrow\quad
\text{compress},
$$

其中 $T_{\text{fixed}}=T_{\text{sys}}+T_{\text{tools}}+T_{\text{out}}$。

检索打分写为

$$
s(m\mid q)=\lambda_1\cos(\mathbf{e}_q,\mathbf{e}_m)
+\lambda_2\,2^{-\Delta t/\tau}
+\lambda_3\,I(m),
\qquad
\lambda_1+\lambda_2+\lambda_3=1,
$$

$\Delta t$ 为条目创建至今的时间，$\tau$ 为半衰期参数，$I(m)\in[0,1]$ 为重要性。

| 符号 | 含义 |
|---|---|
| $B$ | 模型上下文窗口的 token 上限 |
| $T_{\text{sys}}$ | 系统提示占用的 token 数 |
| $T_{\text{tools}}$ | 工具描述占用的 token 数 |
| $T_{\text{work}}$ | 工作记忆占用的 token 数 |
| $T_{\text{sum}}$ | 会话摘要占用的 token 数 |
| $T_{\text{ret}}$ | 本轮检索注入占用的 token 数 |
| $T_{\text{out}}$ | 为模型输出预留的 token 数 |
| $\rho$ | 工作记忆在可用预算中的占比 |
| $\alpha$ | 压缩触发阈值，取值在 $0.6$ 至 $0.8$ 之间 |
| $\mathbf{e}_q,\mathbf{e}_m$ | 查询与记忆条目的嵌入向量 |
| $\tau$ | 时间衰减的半衰期，单位为秒 |
| $I(m)$ | 条目的重要性分数 |
| $\lambda_1,\lambda_2,\lambda_3$ | 三个打分项的权重 |

其余术语在首次出现处定义：**记忆条目**（memory item）是长期记忆的最小单位，包含实体、属性、取值与元数据；**写入策略**（write policy）决定何时写、写什么、如何避免重复；**检索策略**（retrieval policy）决定取哪些条目、如何排序、注入多少；**遗忘**（forgetting）指按时间、容量或用户请求移除条目；**压缩**（compression）指用更短的表示替代原文；**结构化记忆**（structured memory）指以实体-属性-取值三元组而非自由文本保存的记忆；**记忆污染**（memory poisoning）指错误或恶意信息被写入并在后续轮次被当作事实使用。

## 为什么重要

上下文窗口是有限资源，任务长度不受此限制。设平均每轮产生 $t$ 个 token，窗口为 $B$，则轮数达到 $B/t$ 时上下文溢出。取 $B=128000$、$t=800$，约 160 轮后溢出；若每轮包含工具结果，$t$ 上升到数千，溢出提前到数十轮。溢出只有三种处理方式：截断、压缩、外置。截断会丢失早期约束，压缩会引入信息损失，外置会引入检索误差。记忆系统的作用是把三者的损失控制在可度量范围内。

没有记忆会产生四类具体故障。第一类是重复询问，用户已说明的偏好与约束在后续轮次被再次追问。第二类是自相矛盾，前一轮确认的结论在后一轮被推翻，因为原始依据已不在上下文中。第三类是约束丢失，任务执行到中途违反早期设定的预算、格式或范围。第四类是跨会话不可用，同一用户的长期偏好每次都要重新输入。

朴素的记忆同样产生故障。无限追加会使成本随轮数线性增长，并使关键信息被淹没；无过滤的写入会把模型的推测当作事实，形成自我强化的错误；无时效的检索会返回已被覆盖的旧值；只删除主表而不删除索引与摘要会留下隐私残留。记忆系统的设计目标不是「记住更多」，而是在给定预算下最大化可用信息的密度。

在本库中的位置：[[Agent工作流与编排]] 决定状态在节点之间如何传递，本篇决定状态在时间维度上如何保存与取回；[[RAG原理与流程]] 给出检索增强的完整流程，本篇把同一套检索机制用于对话历史与用户状态；[[向量数据库]] 给出索引实现，本篇只定义检索接口；[[上下文工程与Few-shot]] 讨论上下文如何组织，本篇讨论上下文装不下时如何取舍。

## 原理与推导

### 1 三层记忆的容量与代价

三层的差异可以用三个量刻画：容量、访问延迟、保真度。工作记忆容量等于窗口，延迟为零，保真度为原文；摘要容量约为窗口的十分之一，延迟为零，保真度取决于抽取规则；长期记忆容量受存储限制，延迟为一次检索，保真度为条目原文但依赖召回率。

| 层 | 载体 | 容量 | 访问延迟 | 生命周期 | 主要失效 |
|---|---|---|---|---|---|
| 工作记忆 | 上下文消息 | $B-T_{\text{fixed}}$ | 0 | 一次会话 | 溢出、被稀释 |
| 会话摘要 | 上下文中的压缩文本 | 约 $0.1B$ | 0 | 一次会话 | 关键约束丢失 |
| 长期记忆 | 向量库、键值库 | 存储上限 | 一次检索往返 | 跨会话 | 召回失败、过期 |

三者不是替代关系。工作记忆保存最近的原文，用于精确引用；摘要保存早期结论，用于维持一致性；长期记忆保存跨会话的事实与偏好，用于个性化。任何一层缺失都会在特定场景失效：只有工作记忆则长任务溢出；只有摘要则无法精确引用；只有长期记忆则当前对话的指代无法解析。

### 2 写入策略

写入的判据是「该信息在未来轮次是否可能改变决策」。满足判据的情形有五类：

1. 用户显式陈述的约束与偏好，例如预算上限、格式要求、禁用项。
2. 用户对前文的纠正，例如「不是 3000，是 2500」。
3. 任务完成后的结论与关键中间结果，例如最终选定的方案与理由。
4. 实体状态变化，例如订单状态从待支付变为已支付。
5. 失败教训，例如某工具在特定参数下必然超时。

不应写入的情形同样明确：模型的中间推理、工具的原始长输出、可随时重新获取的公开信息、未经确认的推测。中间推理写入后会在后续轮次被当作既定事实，形成错误累积；原始长输出应只保存摘要与指针，需要时按指针重新读取。

去重有三个层次。第一层是精确去重，对条目内容取哈希，相同哈希不重复写入。第二层是近似去重，计算与已有条目的余弦相似度，超过阈值 $\theta$ 时视为重复，$\theta$ 取 $0.9$ 至 $0.95$。第三层是键级更新，以（实体，属性，类别）为键做 upsert：同键同值只更新重要性与时间，同键不同值则将旧条目标记为失效并写入新条目。

写入的收益与成本不对称。一条错误条目会在每次检索命中时污染上下文，且难以被后续轮次发现；漏写一条条目只影响需要它的那一轮。因此写入应偏保守：来源必须可追溯，推测必须标注置信度，用户未确认的推断不进入长期记忆。

### 3 检索策略

检索打分由三项构成。相关性项 $\cos(\mathbf{e}_q,\mathbf{e}_m)$ 衡量语义匹配；时间项 $2^{-\Delta t/\tau}$ 使近期条目占优，$\tau$ 的选择取决于信息的半衰期，偏好类信息可设数周，任务状态类信息应设数小时；重要性项 $I(m)$ 由写入时指定或由规则计算，例如用户显式强调的约束取 $0.9$，一般事实取 $0.5$。

三项权重需要按场景调整。任务状态类检索应提高时间项权重，避免取到已过期的状态；偏好类检索应提高重要性项权重，避免被近期闲聊淹没；事实类检索应提高相关性项权重。权重不应在运行中随机变化，否则同一查询的结果不稳定，难以复现故障。

单一相似度检索有两个缺陷：同质结果挤占预算，以及词面不匹配导致漏召回。前者用最大边际相关性缓解：

$$
\text{MMR}=\arg\max_{m\in R\setminus S}\Big[\mu\,\text{sim}(m,q)-(1-\mu)\max_{m'\in S}\text{sim}(m,m')\Big],
$$

其中 $R$ 为候选集，$S$ 为已选集合，$\mu$ 控制相关性与多样性的权衡。后者用混合检索缓解：词法检索负责精确匹配标识符与数字，向量检索负责语义近似，两路结果按倒数排名融合。

检索结果注入上下文前还要过两道关。第一道是预算关，按打分从高到低累加 token，超过 $T_{\text{ret}}$ 即停止，而不是取固定 $k$ 条。第二道是时效关，过滤 $\text{valid\_until}$ 早于当前时间的条目；这条过滤必须在打分之前执行，否则过期条目会占用候选名额。

### 4 遗忘与压缩

遗忘有四种触发条件。时间触发按 TTL 删除，适用于验证码、临时令牌、一次会话的中间状态。容量触发在条目数超过上限时按重要性或最近使用时间淘汰。冲突触发在新值覆盖旧值时把旧条目标记为失效而非物理删除，以保留审计线索。请求触发按用户指令删除，需覆盖全部副本，见第 7 节。

压缩分抽取式与生成式。抽取式从原文中选择句子，保真度高，但压缩率有限；生成式重写为更短的表述，压缩率高，但可能改变含义。对约束类信息应使用抽取式，因为数字、否定词、日期与专有名词在改写中最容易被改变。设原文长度为 $L$、摘要长度为 $L'$，压缩率为 $1-L'/L$；压缩率不是越高越好，超过某个点后约束开始丢失，该点应由评测确定。

压缩必须遵守一条硬规则：数字、否定、日期、专有名词、用户的纠正必须逐字保留。原因是这些成分的语义对字面形式敏感，「不超过 3000 元」被改写为「预算较紧」后无法再用于判断是否超支。可行的实现是把约束同时写入结构化槽位，摘要只承担叙述性内容；这样即使摘要丢失细节，结构化槽位仍可精确回答。

分层摘要用于超长会话。第一层对每若干轮生成一条摘要，第二层对第一层摘要再压缩。两层都保留结构化槽位作为旁路。分层摘要的成本是每次压缩一次模型调用，收益是把上下文占用从线性增长变为分段常数。

### 5 结构化记忆

结构化记忆以三元组保存：（实体，属性，取值）。与自由文本相比，它支持精确覆盖、冲突检测与按键删除，且不依赖嵌入的稳定性。

| 类别 | 例子 | 键 | 典型 TTL |
|---|---|---|---|
| 事实 | 会议地点为国家会展中心 | 会议.地点 | 任务结束 |
| 偏好 | 座位靠窗 | 差旅.座位 | 长期 |
| 约束 | 住宿预算上限 3000 元 | 差旅.住宿预算 | 任务结束 |
| 任务状态 | 订单处于待支付 | 订单.状态 | 状态变化即失效 |
| 事件 | 10 月 18 日确认了方案 B | 方案.决策 | 长期 |

任务状态适合以状态机快照保存，字段与编排中的状态一致，见 [[Agent工作流与编排]]。这样恢复会话时可以直接从快照继续，而不必重放全部对话。

结构化记忆的写入必须经过抽取步骤，抽取的质量决定记忆质量。抽取规则可以基于模式，例如金额、日期、否定词；也可以基于模型，但模型抽取的输出必须与原文片段一同保存，以便事后核对。只保存抽取结果而不保存原文片段，会使错误无法追溯。

### 6 记忆污染与冲突

污染有四个来源：抽取错误、模型推测被当作事实、工具输出中的对抗性内容、以及用户前后不一致的陈述。四者的共同点是新条目与已有条目矛盾或本身错误，而检索阶段无法区分。

冲突检测在键级进行：对同一（实体，属性）存在两条有效条目即构成冲突。解决策略按优先级排序：

1. 用户显式陈述优先于系统推断。
2. 同一来源下，新陈述覆盖旧陈述，旧条目设置 $\text{valid\_until}$。
3. 来源不同且时间接近时，保留两条并标注冲突，在下一轮向用户确认。
4. 无法判定时不自动选择，把冲突写入任务状态，避免静默采用错误值。

双时间轴是处理冲突的基础设施：每条目记录「生效时间」与「记录时间」，前者表示事实在世界上成立的时间，后者表示系统得知的时间。二者分离后，可以回答两类不同的问题：「当时系统认为预算多少」与「预算实际是多少」。

对抗性污染需要额外防御。检索到的记忆应与工具输出同等对待：作为数据注入，不作为指令；系统提示明确声明记忆区块的边界；权限判定不读取记忆内容。写入侧应要求来源标记，来自外部文档的内容默认置信度较低，不覆盖用户陈述。

### 7 隐私与删除

记忆系统保存的是用户数据，删除能力必须在设计时具备，而不是事后补丁。删除需要覆盖五个位置：主存储、向量索引、摘要文本、缓存、以及由记忆派生的任务状态。只删除主存储会使摘要中的片段继续被注入上下文。

可行的实现是墓碑加级联：删除时在主存储写入墓碑记录，记录被删条目的标识与键；索引按标识删除向量；摘要按取值做文本替换并标记；缓存在 TTL 后自然过期，或在删除事件中主动失效。备份中的副本按备份保留策略处理，并在恢复流程中重放删除事件。

最小化原则减少删除负担：不保存原始身份信息，用哈希标识代替；敏感字段单独加密并设置短 TTL；只保存任务所需的字段。嵌入向量同样属于敏感数据，必须与原文一并删除，否则索引中仍保留可被检索的派生表示。

访问控制与审计同样必要：记忆的读写按用户隔离；每次读取记录用途与请求方；批量导出需要额外授权。

### 8 上下文预算的分配

预算分配应按固定项、预留项、动态项的顺序进行。固定项是系统提示与工具描述，设计时应尽量压缩；预留项是输出空间，按最长回答估计；剩余部分在工作记忆、摘要与检索之间分配。

一个具体分配如下。取 $B=128000$，系统提示 2000，工具描述 6000，输出预留 8000，剩余 112000。工作记忆上限取剩余的 40%，即 44800；摘要上限取 8000；检索上限取 24000；余量 35200 用于工具结果与波动。阈值 $\alpha$ 取 $0.7$，即工作记忆超过 31360 token 时触发压缩。

触发阈值的选择是权衡。$\alpha$ 过低会频繁压缩，增加模型调用成本并加速信息损失；$\alpha$ 过高会在压缩前就发生溢出。可行做法是双阈值：软阈值触发摘要，硬阈值强制截断并记录告警。两个阈值都应写入配置，而不是散落在代码中。

检索的时机也需要设计。每轮都检索会增加延迟与噪声，只在需要时检索又可能漏掉关键信息。折中方案是规则触发：当前消息包含指代、询问历史、或涉及已知实体时检索；其余情况只使用工作记忆与摘要。

### 9 记忆条目的 schema

条目至少包含十一个字段，缺一不可。

| 字段 | 类型 | 作用 |
|---|---|---|
| `id` | 字符串 | 全局唯一标识，用于索引与删除 |
| `kind` | 枚举 | `fact`、`preference`、`constraint`、`task_state`、`episode` |
| `entity` | 字符串 | 实体名，冲突检测的第一维 |
| `attribute` | 字符串 | 属性名，冲突检测的第二维 |
| `value` | 字符串 | 取值，结构化比较的依据 |
| `text` | 字符串 | 注入上下文的自然语言表述 |
| `importance` | 浮点数 | $[0,1]$，参与打分 |
| `created_at` | 数值 | 记录时间，用于时间衰减 |
| `valid_until` | 数值或空 | 失效时间，空表示长期有效 |
| `source` | 字符串 | 来源，用于冲突裁决与审计 |
| `supersedes` | 字符串或空 | 被本条目覆盖的旧条目标识 |

```json
{
  "id": "m_1",
  "kind": "constraint",
  "entity": "差旅",
  "attribute": "住宿预算",
  "value": "3000 元",
  "text": "差旅住宿预算为 3000 元",
  "importance": 0.9,
  "created_at": 0,
  "valid_until": null,
  "source": "user",
  "supersedes": null
}
```

## 关键直觉

> [!tip] 记忆系统的核心不是存储容量，而是写入时的取舍与读取时的排序：未写入的信息无法召回，写入的噪声会挤占预算，读取顺序错误会使关键条目排在预算之外。
>
> 与严格定义的关系：定义中的三层与打分公式正是这一判断的形式化。工作记忆决定「现在看到什么」，摘要决定「还记得什么」，长期记忆决定「能找回什么」；三者的容量与保真度不同，因此同一信息应放在与其生命周期匹配的层，而不是全部堆进上下文。

## 例子与代码

下面的实现包含四个部分：一个稀疏向量索引，提供 `add`、`remove`、`search` 三个方法；一个记忆条目数据结构；一个分层记忆类，管理工作记忆、摘要与长期记忆；以及一段跨轮对话演示。

代码分四块。第一块是向量接口：`tokenize` 把英文按词、中文按单字与二元组切分，避免引入分词依赖；`embed` 做词频归一化；`VectorIndex` 用暴力余弦检索实现接口，生产环境可替换为 HNSW 索引。第二块是 `MemoryItem`：字段与第 9 节的 schema 对应，`key` 属性给出冲突检测使用的三元组。第三块是 `LayeredMemory`：`add_turn` 追加工作记忆并在超阈值时压缩；`compress` 只从用户轮抽取含约束的句子，并对摘要长度设限；`write` 按同键覆盖、同值去重；`retrieve` 用三项打分并过滤过期条目；`build_context` 在预算内组装摘要、检索结果与近轮；`forget` 同时清除条目、向量与摘要片段。第四块是演示：写入两条长期记忆，进行五轮对话触发压缩，然后分别演示召回、过期过滤、冲突覆盖与删除。

```python
# 分层记忆：工作记忆 + 会话摘要 + 外部长期记忆（Python 3.10+，仅用标准库）
from __future__ import annotations

import math
import re
from collections import Counter
from dataclasses import dataclass
from typing import Any, Callable


# ---------- 1. 向量检索接口 ----------
def tokenize(text: str) -> list[str]:
    """英文按词，中文按单字与二元组切分，避免引入分词依赖。"""
    text = text.lower()
    words = re.findall(r"[a-z0-9_]+", text)
    chars = re.findall(r"[\u4e00-\u9fff]", text)
    bigrams = ["".join(chars[i:i + 2]) for i in range(len(chars) - 1)]
    return words + chars + bigrams


def embed(text: str) -> dict[str, float]:
    counts = Counter(tokenize(text))
    norm = math.sqrt(sum(v * v for v in counts.values())) or 1.0
    return {k: v / norm for k, v in counts.items()}


def cosine(a: dict[str, float], b: dict[str, float]) -> float:
    if len(a) > len(b):
        a, b = b, a
    return sum(w * b.get(k, 0.0) for k, w in a.items())


class VectorIndex:
    """外部向量库的最小接口：add / remove / search。生产实现替换为 HNSW 或 IVF 索引。"""

    def __init__(self) -> None:
        self._vectors: dict[str, dict[str, float]] = {}

    def add(self, item_id: str, text: str) -> None:
        self._vectors[item_id] = embed(text)

    def remove(self, item_id: str) -> None:
        self._vectors.pop(item_id, None)

    def search(self, query: str, k: int = 3) -> list[tuple[str, float]]:
        q = embed(query)
        scored = [(item_id, cosine(q, vec)) for item_id, vec in self._vectors.items()]
        scored.sort(key=lambda pair: -pair[1])
        return [pair for pair in scored[:k] if pair[1] > 0.0]


# ---------- 2. 记忆条目 schema ----------
@dataclass
class MemoryItem:
    item_id: str
    kind: str                 # constraint | preference | fact | task_state
    entity: str
    attribute: str
    value: str
    text: str
    importance: float = 0.5
    created_at: float = 0.0
    valid_until: float | None = None
    source: str = "user"
    supersedes: str | None = None

    @property
    def key(self) -> tuple[str, str, str]:
        return (self.kind, self.entity, self.attribute)


KEEP_PATTERN = re.compile(r"\d|预算|上限|必须|不要|偏好|截止|日期|地点|会场")


# ---------- 3. 分层记忆 ----------
class LayeredMemory:
    def __init__(
        self,
        token_budget: int = 200,
        trigger: float = 0.6,
        keep_recent: int = 2,
        reserve: int = 40,
        summary_char_limit: int = 180,
        clock: Callable[[], float] | None = None,
    ) -> None:
        self.token_budget = token_budget
        self.trigger = trigger
        self.keep_recent = keep_recent
        self.reserve = reserve
        self.summary_char_limit = summary_char_limit
        self._clock = clock or (lambda: 0.0)
        self.working: list[dict[str, Any]] = []
        self.summary_facts: list[str] = []
        self.items: dict[str, MemoryItem] = {}
        self.index = VectorIndex()
        self.tombstones: set[str] = set()
        self.events: list[str] = []

    # --- 预算核算 ---
    def _tokens(self, text: str) -> int:
        """粗估 token 数：中文约每 1.5 字符 1 token。"""
        return max(1, math.ceil(len(text) / 1.5))

    @property
    def summary(self) -> str:
        return "；".join(self.summary_facts)

    def working_tokens(self) -> int:
        return sum(self._tokens(t["text"]) for t in self.working)

    # --- 写入工作记忆 ---
    def add_turn(self, role: str, text: str) -> None:
        self.working.append({"role": role, "text": text, "ts": self._clock()})
        self.events.append(f"add_turn {role} {self._tokens(text)} tok")
        if self.working_tokens() > self.token_budget * self.trigger:
            self.compress()

    # --- 压缩：从用户轮抽取含约束的句子，丢弃其余 ---
    def compress(self) -> None:
        if len(self.working) <= self.keep_recent:
            return
        old = self.working[:-self.keep_recent]
        self.working = self.working[-self.keep_recent:]
        added = 0
        for turn in old:
            if turn["role"] != "user":   # 助手输出默认不进摘要，只保留确认性结论
                continue
            for sentence in re.split(r"[。；!?]", turn["text"]):
                sentence = sentence.strip()
                if sentence and KEEP_PATTERN.search(sentence) and sentence not in self.summary_facts:
                    self.summary_facts.append(sentence)
                    added += 1
        while len(self.summary) > self.summary_char_limit and len(self.summary_facts) > 1:
            self.summary_facts.pop(0)
        self.events.append(f"compress 丢弃 {len(old)} 轮，新增 {added} 条要点")
        print(f"   [压缩] 丢弃 {len(old)} 轮，新增 {added} 条要点，工作记忆 {self.working_tokens()} tok")

    # --- 写入长期记忆：同键覆盖、同值去重 ---
    def write(
        self,
        kind: str,
        entity: str,
        attribute: str,
        value: str,
        text: str | None = None,
        importance: float = 0.5,
        ttl: float | None = None,
    ) -> MemoryItem:
        now = self._clock()
        key = (kind, entity, attribute)
        superseded: str | None = None
        for old in self.items.values():
            if old.key != key or old.valid_until is not None:
                continue
            if old.value == value:
                old.importance = max(old.importance, importance)
                self.events.append(f"dedupe {old.item_id}")
                return old
            old.valid_until = now
            self.index.remove(old.item_id)
            superseded = old.item_id
            self.events.append(f"supersede {old.item_id} -> {value}")

        item_id = f"m_{len(self.items) + 1}"
        item = MemoryItem(
            item_id=item_id,
            kind=kind,
            entity=entity,
            attribute=attribute,
            value=value,
            text=text or f"{entity}{attribute}为{value}",
            importance=importance,
            created_at=now,
            valid_until=now + ttl if ttl is not None else None,
            supersedes=superseded,
        )
        self.items[item_id] = item
        self.index.add(item_id, item.text)
        self.events.append(f"write {item_id}")
        return item

    # --- 检索打分：相关性 + 时间衰减 + 重要性 ---
    def retrieve(self, query: str, k: int = 3, half_life: float = 1800.0) -> list[tuple[MemoryItem, float]]:
        now = self._clock()
        hits = dict(self.index.search(query, k=max(k * 3, 6)))
        results: list[tuple[MemoryItem, float]] = []
        for item_id, sim in hits.items():
            item = self.items[item_id]
            if item.valid_until is not None and item.valid_until < now:
                self.events.append(f"skip_expired {item_id}")
                continue
            if item_id in self.tombstones:
                continue
            age = max(0.0, now - item.created_at)
            recency = 0.5 ** (age / half_life)
            score = 0.6 * sim + 0.25 * recency + 0.15 * item.importance
            results.append((item, score))
        results.sort(key=lambda pair: -pair[1])
        return results[:k]

    # --- 组装上下文：摘要 + 检索 + 近轮，受预算约束 ---
    def build_context(self, query: str, k: int = 3) -> dict[str, Any]:
        budget = self.token_budget - self.reserve
        used = self._tokens(self.summary) if self.summary else 0
        picked: list[MemoryItem] = []
        for item, _score in self.retrieve(query, k=k):
            cost = self._tokens(item.text)
            if used + cost > budget:
                break
            picked.append(item)
            used += cost
        recent: list[dict[str, Any]] = []
        for turn in reversed(self.working):
            cost = self._tokens(turn["text"])
            if used + cost > budget:
                break
            recent.append(turn)
            used += cost
        recent.reverse()
        return {"summary": self.summary, "retrieved": picked, "recent": recent, "tokens": used}

    # --- 删除：条目、向量与摘要派生文本一并清除 ---
    def forget(self, entity: str, attribute: str) -> None:
        for item in self.items.values():
            if item.entity == entity and item.attribute == attribute and item.item_id not in self.tombstones:
                self.tombstones.add(item.item_id)
                self.index.remove(item.item_id)
                self.summary_facts = [
                    "[已删除]" if item.value in fact else fact for fact in self.summary_facts
                ]
                self.events.append(f"forget {item.item_id}")
                print(f"   [删除] {item.item_id} {entity}.{attribute} 及其摘要片段")


# ---------- 4. 演示：跨轮召回 ----------
ticks = iter(range(0, 100000, 300))
clock = lambda: next(ticks)
mem = LayeredMemory(token_budget=150, trigger=0.6, clock=clock)

budget_item = mem.write("constraint", "差旅", "住宿预算", "3000 元", importance=0.9)
seat_item = mem.write("preference", "差旅", "座位", "靠窗", importance=0.6)
print("长期记忆:", budget_item.item_id, seat_item.item_id)

mem.add_turn("user", "我下周三去上海出差，住宿预算上限 3000 元，偏好靠窗座位。")
mem.add_turn("assistant", "已记录。需要一并查询 10 月 21 日至 23 日的酒店吗？")
mem.add_turn("user", "会议第一天在会场做产品演示，第二天分组讨论，晚上安排客户拜访，行程比较满。")
mem.add_turn("assistant", "收到，我会把会场与酒店的距离纳入筛选条件，并避开演示时段。")
mem.add_turn("user", "另外请把报销材料清单发我一份，包括发票、行程单和审批截图。")

print("压缩后工作记忆 token:", mem.working_tokens())
print("摘要:", mem.summary)

print("\n--- 第 6 轮：请求订酒店 ---")
ctx = mem.build_context("把酒店订在会场附近，预算别超")
print("上下文 token:", ctx["tokens"])
for item in ctx["retrieved"]:
    print("  召回:", item.item_id, item.kind, item.entity, item.attribute, "=", item.value)
print("  近轮角色:", [t["role"] for t in ctx["recent"]])

print("\n--- 第 7 轮：询问预算上限 ---")
for item, score in mem.retrieve("我的住宿预算上限是多少"):
    print(f"  {item.item_id} {item.attribute}={item.value} score={score:.3f}")

print("\n--- 过期过滤 ---")
site = mem.write("task_state", "会议", "会场", "国家会展中心", ttl=600, importance=0.8)
print(f"  写入 {site.item_id}，valid_until={site.valid_until}")
print("  当前召回:", [item.value for item, _ in mem.retrieve("会场在哪里")])
for _ in range(3):            # 时钟推进 900 秒，越过 valid_until
    next(ticks)
print("  900 秒后召回:", [item.value for item, _ in mem.retrieve("会场在哪里")])

print("\n--- 冲突覆盖 ---")
new_item = mem.write("constraint", "差旅", "住宿预算", "2500 元", importance=0.9)
print(f"  新条目 {new_item.item_id}={new_item.value}，覆盖 {new_item.supersedes}")
for item in mem.items.values():
    if item.attribute == "住宿预算":
        print(f"  {item.item_id}: value={item.value} valid_until={item.valid_until}")

print("\n--- 删除 ---")
mem.forget("差旅", "座位")
print("  摘要:", mem.summary)
print("  召回靠窗:", [item.value for item, _ in mem.retrieve("靠窗座位")])
print("\n事件流:", mem.events)
```

输出如下。压缩发生在第 5 轮之后：五轮对话的工作记忆超过 $150\times0.6=90$ token，压缩后降到 40 token，摘要保留了两条含约束的要点。第 6 轮同时召回预算条目与近轮对话；第 7 轮以明确问句检索到同一条目，得分 0.463。过期演示写入的会场条目在有效期内可召回，900 秒后因超过 `valid_until` 被过滤。冲突覆盖写入新预算后，旧条目保留但 `valid_until` 被置为当前时间，新条目记录 `supersedes`。删除后，摘要中的对应片段被替换，检索不再返回该条。

```text
长期记忆: m_1 m_2
   [压缩] 丢弃 3 轮，新增 2 条要点，工作记忆 40 tok
压缩后工作记忆 token: 40
摘要: 我下周三去上海出差，住宿预算上限 3000 元，偏好靠窗座位；会议第一天在会场做产品演示，第二天分组讨论，晚上安排客户拜访，行程比较满

--- 第 6 轮：请求订酒店 ---
上下文 token: 94
  召回: m_1 constraint 差旅 住宿预算 = 3000 元
  近轮角色: ['assistant', 'user']

--- 第 7 轮：询问预算上限 ---
  m_1 住宿预算=3000 元 score=0.463

--- 过期过滤 ---
  写入 m_3，valid_until=3300
  当前召回: ['国家会展中心']
  900 秒后召回: []

--- 冲突覆盖 ---
  新条目 m_4=2500 元，覆盖 m_1
  m_1: value=3000 元 valid_until=4500
  m_4: value=2500 元 valid_until=None

--- 删除 ---
   [删除] m_2 差旅.座位 及其摘要片段
  摘要: [已删除]；会议第一天在会场做产品演示，第二天分组讨论，晚上安排客户拜访，行程比较满
  召回靠窗: []

事件流: ['write m_1', 'write m_2', 'add_turn user 21 tok', 'add_turn assistant 21 tok', 'add_turn user 25 tok', 'add_turn assistant 20 tok', 'add_turn user 20 tok', 'compress 丢弃 3 轮，新增 2 条要点', 'write m_3', 'skip_expired m_3', 'supersede m_1 -> 2500 元', 'write m_4', 'forget m_2']
```

三处设计值得单独说明。第一，摘要只从用户轮抽取，助手输出默认不进入摘要；这样做的代价是助手的确认性结论会丢失，若结论重要，应在生成时同步写入结构化条目。第二，压缩按句子而不是按字符截断，保证保留下来的约束是完整句；代价是压缩率受句子长度限制。第三，`write` 在覆盖时不删除旧条目，只设置 `valid_until`，使审计与回放可以还原历史状态；代价是存储增长，需要定期归档。

代码的简化在于向量表示。词频向量无法处理同义改写，「住宿预算」与「房价上限」的相似度接近零；生产系统应替换为稠密嵌入，接口不变。此外，时间衰减的权重与半衰期是固定常数，没有按记忆类别区分，类别相关的参数需要用评测集确定。三处删除实验可直接验证各部件的作用：去掉 `compress`，五轮对话后工作记忆超过 107 token，继续追加会超出 `token_budget`；去掉 `retrieve` 中的 `valid_until` 过滤，已失效的会场条目仍会被注入；去掉 `forget` 中对摘要的替换，删除后摘要仍包含「靠窗座位」，检索虽然不再返回条目，上下文却仍泄露原文。

## 易错点

> [!warning]
> 1. 摘要丢失关键约束。生成式摘要把「住宿预算上限 3000 元」改写为「预算较紧」，后续无法判断是否超支。对策：数字、否定、日期逐字保留；约束同时写入结构化槽位，摘要只承担叙述内容。
> 2. 检索到过期信息。条目没有 `valid_until`，用户已把预算从 3000 改为 2500，系统仍按 3000 规划。对策：覆盖时写失效时间，检索前按时效过滤。
> 3. 无限增长。工作记忆只追加不压缩，或长期记忆没有容量上限与 TTL，数月后检索延迟与成本同时上升。对策：三层各自设配额，淘汰策略显式化。
> 4. 写入噪声。把模型的推测写入长期记忆，例如把「用户可能喜欢靠窗」当作偏好；此后每次检索都会命中，形成自我强化。对策：只写有来源的陈述，推断标注置信度且不覆盖用户陈述。
> 5. 删除不彻底。只删除主表条目，向量索引与摘要中的片段仍在，检索仍可命中。对策：删除时级联索引、摘要与缓存，并保留墓碑用于审计。
> 6. 摘要与结构化记忆不一致。摘要说预算 3000，结构化槽位是 2500，两处同时注入上下文，模型无法判断以哪个为准。对策：摘要由结构化条目生成，或在注入时显式标注优先级。

## 关联笔记

- [[Agent工作流与编排]] —— 前置：状态在节点间的传递方式，决定哪些信息需要进入记忆层。
- [[上下文工程与Few-shot]] —— 前置：上下文如何组织与排布，本篇讨论装不下时的取舍。
- [[RAG原理与流程]] —— 对照：同一套检索机制用于外部文档与对话记忆的差异。
- [[向量数据库]] —— 后续：`VectorIndex` 接口的生产实现与索引参数。
- [[检索优化与重排Rerank]] —— 后续：提升记忆召回精度的重排方法。

## 达标检测

- [ ] 写出上下文预算不等式，并对 $B=128000$ 给出一组具体分配。
- [ ] 说明三种记忆层的容量、延迟与失效方式，各举一个只适合该层的例子。
- [ ] 给定一个检索查询与五条候选记忆，按三项打分公式手算排序。
- [ ] 运行本篇代码，把 `token_budget` 改为 60，说明压缩触发点与摘要内容如何变化。
- [ ] 为一个已被覆盖的条目设计删除流程，列出需要清理的四个位置。
- [ ] 指出一种记忆污染路径，并给出写入侧与读取侧各一条防御措施。

## 参考来源

- Packer et al., "MemGPT: Towards LLMs as Operating Systems", arXiv:2310.08560 —— 对应本篇第 1 节的分层上下文管理与第 4 节的压缩触发。
- Lewis et al., "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks", arXiv:2005.11401 —— 对应第 3 节的检索与注入流程。
- LangChain, Memory 文档, python.langchain.com —— 对应第 2 节会话记忆的写入与第 3 节的检索接口设计。
- Anthropic, "Effective context engineering for AI agents", 2025 —— 对应第 8 节上下文预算分配与摘要触发阈值。
