Memory 长期记忆 写入 · 整合 · 检索 · 安全
本文把「Harness 管记忆、模型不裸奔」这条线讲清楚：用 Markdown + 索引 + 元数据做可检索的长期记忆，再配合分阶段写入、定期整合、独立模型筛上下文、沙箱写路径。内容根据公开讨论与架构类示意图整理，与 Anthropic 某一版实现的细节可能不完全一致，以官方文档与当前 CLI 行为为准。
仓库完整稿（与专题同源 Markdown）：wemedia/zhihu/articles/13-… ↗
1. 如何写入记忆？（阶段一：逐轮提取）
后台 Agent 在对话流中周期性回看最近 N 条消息，并拿到已有记忆摘要，避免重复造轮子。核心判定只有一个：「值得记住吗？」——否就跳过；是则新建或更新独立 .md 文件，并维护总索引 MEMORY.md（目录 + 单行摘要，方便人读、也方便后续检索）。
四种记忆类型（type）
用固定枚举帮助后续「按类检索」与提示词约束，而不是让模型随意发明标签。
- user：你是谁——角色、领域、偏好。
- project：代码与 Git 看不到的——截止日、拍板结论。
- feedback：你希望 Agent 怎么做——纠错方式、风格与红线。
- ref：仓库外的指引——外部系统、工单、合规要求。
MEMORY.md 与单文件示例
# 索引：每条一行链到独立文件
- [用户档案](user_profile.md) — 后端背景，近期在学 React
- [测试规范](feedback_testing.md) — 集成测试禁止 mock 数据库
- [认证重构](project_auth_rewrite.md) — 合规驱动，截止 2026-04-15---
name: 测试规范
description: 集成测试必须连真实库，禁止仅用 mock
type: feedback
---
正文：可写细则、历史讨论摘要、链接等。要点：description 要写得可被「未见正文」的模型读懂——后面检索阶段几乎只看这一行做相关性判断。
2. 阶段二：定期整合
当满足距上次整合 ≥ 24 小时且累积会话数 ≥ 5（阈值仅为示意图）一类条件时，触发分叉子 Agent（示意图中常称 autoDream 一类名字）专做「整理活」，避免与主会话抢上下文。
它做什么：读 MEMORY.md 与各主题文件 → 从日志/会话记录用关键词精确捞信号（而非全文吞日志）→ 合并进旧文件：相对时间改绝对时间、删掉已与当前代码矛盾的事实 → 修剪：去掉失效索引、缩短冗长段落、消解文件间矛盾。并发上可用锁文件，避免多会话同时整合写乱。
3. 记忆如何「删除」？
设计上没有按时间的自动过期；删除只发生在整合阶段由 Agent 主动判断：与当前代码不一致、或被更可靠的新记忆覆盖。换句话说：记忆只会被写精，不会在用户不知情的情况下悄悄消失——但若长期不整合，陈旧段落可能仍以「带警告」形式存在（见下一节）。
4. 如何检索 Memory？
MEMORY.md 作为轻量总目录默认进入系统提示，容量上限制在约200 行或 25KB量级（示意）；其中链接指向的各文件不会默认全量载入。
接下来用独立、相对便宜的模型（示意图常用 Sonnet）当「路由器」：扫描各记忆文件的 YAML frontmatter（可按时间排序，文件数有上限），拼成 [type] 文件名 (时间): description 的列表，连同当前用户问题一并请求模型，让其至多选出 5 个最相关文件——不确定就不选。最终只把这 5 个正文读入上下文；本会话里已经展示过的条目可跳过，优先「新鲜相关」。
对较早写入的记忆，可在载入时附带提示：「该记忆已过去 X 天，可能过时，先验证再行动」——Agent 应用 grep 或读文件核对现状。
金句：记忆是观察快照，不是实时真相；引用到具体 file:line 前务必回仓库确认。
5. Memory 安全怎么保证？
三层防护（概念顺序）：
- 全局锁定：存储根路径只在全局配置改，防止恶意仓库改路径把记忆写到奇怪地方。
- 路径校验：拦截
..、越权到系统根目录等。 - 沙箱白名单：每次写操作落在允许集合内，否则直接拒绝。
目标一句话：堵死「借记忆之名偷偷写到不该写的地方」。
6. 总结：Harness 的四条纪律
模型很强，但 Harness 默认不信任它在无监督下自管记忆——每一步都带约束：
- 写入：强制 YAML + 固定
type，格式不由模型随口定。 - 检索：独立模型筛文件，主模型不插手筛选逻辑。
- 删除：无静默定时删；只在整合时显式判定，整体偏「越写越准」。
- 过时：用日期与警告倒逼「先验证再用」，而不是假装记忆永远新鲜。
7. 外部参考：社区文件化规划方案
上述机制是 Claude Code 内部Harness 层的设计。社区中也有纯 Skill 层的实现，用类似思路在 Agent 外部解决同一类问题：
- OthmanAdi / planning-with-files — 通过
task_plan.md（阶段与状态）、findings.md（研究发现与关键决策）、progress.md（会话日志与操作记录）三文件 + hooks（PreToolUse / PostToolUse / Stop）实现文件化工作记忆。核心规则：2-Action Rule（每两次查看/搜索后必须写入 findings），对抗"看过就忘"。对照阅读可帮助理解"Harness 内部记忆"与"Skill 层外部记忆"的互补边界。
8. 延伸阅读：Agent Memory 的理论框架
当记忆系统从"附加功能"变成 Agent 架构的核心子系统，需要更系统的理论框架来指导工程实现。以下是社区中关于 Memory 的深度分析文章：
- lencx：Agent Memory — 记忆不是蒸馏 — 系统论述 Memory 的四个建模对象（用户模型、任务模型、世界模型、自我模型）、六维基本记忆单元（内容/类型/置信度/来源/作用域/时间衰减）、以及 write–manage–read 三条链路。核心判断：Memory 的难点从来不在容量，在治理。与 Harness 内部的分阶段写入、独立模型筛选、沙箱安全等机制形成互补视角。
- 相关文章链： 浅谈 Agent Memory、 深度解析：Claude Code 源码、 Harness Engineering（lencx 系列，与本站多个专题同源）
理论价值：lencx 的框架把 Memory 从"存什么"推进到"谁被允许持续影响未来"的治理层面，这与 Harness 的"模型不裸奔"原则方向一致，只是前者从系统架构视角出发，后者从 CLI 工程约束出发。