w wyl123ly 的博客
MD

Agent记忆与上下文

36 KB 2026.10.18 原文件

Agent记忆与上下文

定义

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

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

上下文预算约束写为

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

其中 。

检索打分写为

为条目创建至今的时间, 为半衰期参数, 为重要性。

符号含义
模型上下文窗口的 token 上限
系统提示占用的 token 数
工具描述占用的 token 数
工作记忆占用的 token 数
会话摘要占用的 token 数
本轮检索注入占用的 token 数
为模型输出预留的 token 数
工作记忆在可用预算中的占比
压缩触发阈值,取值在 至 之间
查询与记忆条目的嵌入向量
时间衰减的半衰期,单位为秒
条目的重要性分数
三个打分项的权重

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

为什么重要

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

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

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

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

原理与推导

1 三层记忆的容量与代价

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

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

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

2 写入策略

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

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

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

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

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

3 检索策略

检索打分由三项构成。相关性项 衡量语义匹配;时间项 使近期条目占优, 的选择取决于信息的半衰期,偏好类信息可设数周,任务状态类信息应设数小时;重要性项 由写入时指定或由规则计算,例如用户显式强调的约束取 ,一般事实取 。

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

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

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

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

4 遗忘与压缩

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

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

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

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

5 结构化记忆

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

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

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

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

6 记忆污染与冲突

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

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

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

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

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

7 隐私与删除

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

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

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

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

8 上下文预算的分配

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

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

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

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

9 记忆条目的 schema

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

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

关键直觉

记忆系统的核心不是存储容量,而是写入时的取舍与读取时的排序:未写入的信息无法召回,写入的噪声会挤占预算,读取顺序错误会使关键条目排在预算之外。

与严格定义的关系:定义中的三层与打分公式正是这一判断的形式化。工作记忆决定「现在看到什么」,摘要决定「还记得什么」,长期记忆决定「能找回什么」;三者的容量与保真度不同,因此同一信息应放在与其生命周期匹配的层,而不是全部堆进上下文。

例子与代码

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

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

# 分层记忆:工作记忆 + 会话摘要 + 外部长期记忆(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 轮之后:五轮对话的工作记忆超过 token,压缩后降到 40 token,摘要保留了两条含约束的要点。第 6 轮同时召回预算条目与近轮对话;第 7 轮以明确问句检索到同一条目,得分 0.463。过期演示写入的会场条目在有效期内可召回,900 秒后因超过 valid_until 被过滤。冲突覆盖写入新预算后,旧条目保留但 valid_until 被置为当前时间,新条目记录 supersedes。删除后,摘要中的对应片段被替换,检索不再返回该条。

长期记忆: 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 —— 后续:提升记忆召回精度的重排方法。

达标检测

  • [ ] 写出上下文预算不等式,并对 给出一组具体分配。
  • [ ] 说明三种记忆层的容量、延迟与失效方式,各举一个只适合该层的例子。
  • [ ] 给定一个检索查询与五条候选记忆,按三项打分公式手算排序。
  • [ ] 运行本篇代码,把 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 节上下文预算分配与摘要触发阈值。