小节三：实现 read_memory、write_memory、update_memory——让 Agent 真正能读写长期记忆

把概念讲清楚以后，真正落地就要靠工具了。下面这张图把 read_memory、write_memory、update_memory 和 MemoryStore 的关系串起来了，大家可以先建立一个整体印象。

换句话说，这里不是搞一个神秘的“黑盒记忆系统”，而是通过一套很朴素、很好查的文件系统能力来完成：读的时候按结构解析，写的时候落到指定文件，更新的时候尽量做局部修改，并且把 Markdown 结构保住。这样一来，后面无论调试还是排错，心里都会更有底。

现在正式实现三个能力：

read_memory
write_memory
update_memory

这里先明确它们的职责。

read_memory

读取某类长期记忆。

例如：

read_memory("project")

返回：

project.md

内容。

write_memory

追加一条新的长期信息。

例如：

写入 decisions.md：
项目继续使用 Python 3.9

update_memory

不是简单追加。

而是，已有事实变化时，更新原有内容。

例如昨天：

入口文件：app.py

今天项目重构：

入口文件：src/main.py

如果继续 append：

入口文件 app.py
入口文件 src/main.py

Memory 就冲突了。

所以必须支持更新。

第一版采用 Section + Key

这一点非常关键。很多同学一开始会下意识地想“直接整段替换掉不就行了”，但真到工程里，这样做风险不小。下面这张图把局部更新和全局替换的差别画出来了。

你会很直观地看到，update_memory 更推荐走 Section + Key 这条路。因为它只改目标位置，不会顺手把别的字段误伤，也更不容易把原有结构打乱。对长期记忆来说，能局部改，就尽量不要整段抹掉重写，这是很实用的一条工程经验。

为了更新更稳定，我们给 Markdown 加一点结构。

例如 project.md：

# Project Memory

## Runtime

- python_version: Python 3.9
- framework: Flask

## Structure

- entrypoint: src/main.py
- test_dir: tests/

这样以后可以更精确更新。

完整 MemoryStore

这就是最基础的：

read
write
update

闭环。

为什么 update_memory 不能默认全局 replace？

和我们前面的 edit_file 一样。

如果旧文本出现 5 次：

Python 3.9

直接全部替换可能误改其他章节。

所以：

0 次 → 报错
1 次 → 更新
>1 次 → 要求更精确

这个原则很稳。

这份 Markdown 实现刻意省略了什么？

到这里，我们已经有一份容易读懂的教学实现，但先不要把它直接当成多人在线服务的存储层。它还没有记录：

scope_id
source
confidence
created_at / updated_at
expires_at
version

它也没有处理两个 Session 同时更新同一条事实的竞争。临时文件替换可以避免文件写到一半，却不能避免“后写入者覆盖先写入者”。课程项目因此另外提供了结构化 LongTermMemoryStore：按作用域和类型保存记录，用 expected_version 拒绝过期写入，并支持过期过滤和删除。规模继续上升时，再把同样的字段迁移到 SQLite 或数据库，概念不用重学。

运行项目中的完整版本：

在项目根目录使用 python3 projects/05_context_memory_session/main.py，可以看到它和 Working Memory、Session、ContextBuilder、Compaction 串在同一条链路里。阶段入口会自动找到项目的 src 目录，我们只需要确认当前解释器是 Python 3.9。

把 Memory Store 包成 Tool

上一部分我们已经有 Tool Registry。

因此可以把 Memory API 作为 Tool 暴露给 Agent：

然后：

registry.register(read_memory)
registry.register(write_memory)
registry.register(update_memory)

Agent 就拥有了长期记忆读写能力。

这里要分清“拥有 Tool”和“被授权执行 Tool”。read_memory 通常是只读能力；write_memory、update_memory、delete_memory 都会改变未来 Session 的行为，应该进入 Safety Policy 和 Trace。涉及用户偏好、敏感范围或跨项目记忆时，还要检查作用域和授权，不能只因为模型调用了 Tool 就默认放行。

但能写不等于应该自动写

这是本节非常关键的安全边界。

如果 Agent 每完成一步就：

write_memory

很快 Memory 会爆。

所以应该设计，Memory Write Policy。

例如只有满足以下条件才考虑写：

用户明确表达长期偏好
项目稳定事实被确认
形成重要架构决策
产生未来可复用经验

而：

一次性报错
临时路径
某轮 next_action
失败的猜测
未验证结论

默认不要写。