7.3 分层记忆：会话内、跨会话与知识库

7.3 分层记忆：会话内、跨会话与知识库

本节摘要：压缩管"这个会话装得下"，记忆管"会话之外还记得什么"。把记忆按生命周期分三层：会话内记忆就是 messages 本身加工作区——引用化（3.3 节）把文件系统当作窗口的外存，是这一层的核心技巧；跨会话记忆是落盘的结构化条目——项目约定文件（CLAUDE.md 式，随仓库走、团队共享）、会话存档（任务结束时的摘要简报，下次同仓库开工时注入）、用户偏好（风格与惯例）；知识库是检索式外存——当"要记的东西"大到无法整块注入（全部历史工单、全部内部文档），就从"注入"退到"按需检索"。每层各有介质、写入时机、读取时机与失效方式，本节给出对照表与 memory.py 最小实现，最后讲记忆的三个坑：陈旧误导、膨胀、跨用户泄漏。记忆与上下文的系统展开，另见 《Hello-Agents：智能体实战教程》第 8~9 章。

学习目标

阅读完本节，你应当能够：

1. 画出三层记忆的介质 / 写入 / 读取 / 失效对照表。
2. 设计跨会话记忆的条目 schema 与遗忘策略。
3. 说明"注入 vs 检索"的切换判据。
4. 识别记忆的三个坑及对策。

一、三层对照表

读表的要点：越靠下的层，读写与任务的耦合越松。会话内记忆每步都动；跨会话记忆一个会话动两次（开始注入、结束落盘）；知识库与任务完全解耦，只是工具表里多了一个 search_docs（第 4.1 节：检索类工具，低危可 allow）。

二、会话内：messages + 引用化

这层基本就是第 3.3 节 + 本章前两节的内容，只补一个总括：harness 的两级存储结构——窗口是高速小存储，工作区文件系统是大慢存储，引用化是两者之间的指针。读过大文件后上下文里只留 app.py（约 800 行，含 auth 模块），要用再 read_file 取段。这个结构决定了很多设计：驱逐敢丢旧输出（盘上还有）、压缩敢简化历史（简报里保留了路径）、工具表里 read 类工具永远值得有分页参数。

三、跨会话：约定、存档与偏好

三类内容、三种治理：

memory.py 最小实现（会话存档半边）：

# memory.py —— 跨会话记忆存取（写法示意，以实际工程为准）
import json, time
from pathlib import Path

STORE = Path(".mini_harness") / "memory.json"

def load() -> dict:
    if STORE.exists():
        return json.loads(STORE.read_text(encoding="utf-8"))
    return {"sessions": []}

def save_session_summary(task: str, summary: str, limit: int = 50) -> None:
    """任务结束时写入一条会话存档；上限防膨胀（示意）。"""
    mem = load()
    mem["sessions"].append({"workspace": str(Path.cwd().resolve()),
                            "task": task, "summary": summary,
                            "ts": time.strftime("%Y-%m-%d %H:%M")})
    mem["sessions"] = mem["sessions"][-limit:]
    STORE.parent.mkdir(exist_ok=True)
    STORE.write_text(json.dumps(mem, ensure_ascii=False, indent=1),
                     encoding="utf-8")

def context_inject(limit: int = 3) -> str:
    """新会话供料时注入：同工作区最近 limit 条存档。"""
    ws, mem = str(Path.cwd().resolve()), load()
    rows = [s for s in mem["sessions"] if s["workspace"] == ws][-limit:]
    if not rows:
        return ""
    return "近期会话回顾（仅供参考，项目可能已变化）：\n" + "\n".join(
        f"- {s['ts']} {s['task']}：{s['summary'][:120]}" for s in rows)
​

注意 context_inject 里那句免责声明不是装饰——它是防"陈旧记忆误导"的第一道闸（见第五节）。

四、知识库：从注入退到检索

跨会话记忆解决"几十条经验"，知识库解决"几千份文档"。切换判据很简单：当要记的内容大到无法整块注入预算（7.1 节），且任务只用到其中小部分时，从"注入"退到"检索"——把 search_docs(query) 做成工具（第 4.1 节分类学：检索类，低危），模型按需调用。实现方案（全文索引 / 向量检索 / 混合）不影响 harness 侧的设计：对 harness 而言它只是一个只读工具 + 一个异步构建流水线。不要过早上知识库——大部分团队前两年的"记忆需求"，一个约定文件加会话存档就覆盖了。

五、记忆的三个坑

本节要点回顾

1. 三层记忆：会话内（messages + 引用化两级存储）、跨会话（约定 / 存档 / 偏好，读写各两次）、知识库（检索式外存，与任务解耦）。
2. 跨会话治理：约定由人维护并版本化；存档自动落盘加上限；偏好转透明可删。
3. 切换判据：内容大到注不进预算且只用小部分 → 从注入退到检索；不要过早上知识库。
4. 三个坑：陈旧（时间戳 + 现场优先）、膨胀（上限 + 合并）、泄漏（双键隔离）。

至此供料的三件套——预算、压缩、记忆——齐了。但上下文工程管的是"进"，还有一条"出"的暗线：每一步执行之后，谁来把检查、测试、修复自动串起来？下一章：Hook 与反馈回路。

延伸阅读：同站教程库《opencode》。