给 AI Agent 加记忆之前，先决定它到底允许记住什么
Agent memory 是一个很容易被讲空的能力。
最简单的说法是：把对话存起来，下次检索相似内容，再塞回上下文。
但真正接到 AI 宿主里时，问题会立刻变具体：
- 哪些内容只是当前会话上下文？
- 哪些内容算长期事实、偏好或关系？
- 哪些内容是 reasoning trace，而不是用户知识？
- 记忆归属于用户、项目、工作区，还是全局？
- 错误记忆如何纠正？
- 删除路径在哪里？
- Agent 下次使用某条记忆时，如何证明来源？
这也是我阅读 Doramagic 的 agent-memory manual 时认为最重要的点：它不应该被理解成“给 Agent 接一个向量库”，而应该被理解成“给 Agent 建立可审计的记忆边界”。
项目地址：
- Doramagic 项目页：https://doramagic.ai/en/projects/agent-memory/
- Doramagic manual：https://doramagic.ai/en/projects/agent-memory/manual/
- 上游仓库：https://github.com/neo4j-labs/agent-memory
第一层理解：三类记忆不是一回事
Doramagic manual 把 agent-memory 的核心拆成三层：
| 层级 | 存什么 | 为什么重要 |
|---|---|---|
| short-term memory | 当前 session / conversation 的消息历史 | 帮 Agent 保持当前对话上下文，但不把一切都变成永久知识 |
| long-term memory | entity、preference、relationship | 用于长期事实、用户偏好、领域关系，但也带来隐私、纠错和租户隔离问题 |
| reasoning memory | step、tool call、trace、similar trace | 让 Agent 行为可复盘，而不是把“它为什么这么做”藏在黑箱里 |
这个拆分很关键。
“记住所有东西”不是工程方案，而是一个数据治理风险。
用户的一句话可能只适合留在 short-term memory。
一个明确确认过的偏好，才可能进入 long-term memory。
一次失败的工具调用和恢复过程，更适合进入 reasoning memory，而不是混进用户事实库里。
如果 AI 宿主不知道自己正在读写哪一层记忆，就不应该直接上生产。
Neo4j 图结构不是装饰
agent-memory 使用 Neo4j 作为图存储后端。这个选择并不是为了“看起来更高级”，而是因为 Agent memory 经常不是一堆文本块。
真实记忆往往有关系：
- 某个人属于某个组织
- 某个任务来自某次 session
- 某次 tool call 影响了某个 entity
- 某个 preference 只属于一个用户
- 某条 reasoning trace 创建或更新了某个记录
manual 中提到 POLE+O 类型：PERSON、ORGANIZATION、LOCATION、EVENT、OBJECT，并支持扩展实体类型。
这意味着长期记忆不是随便扔进一个 note，而是进入一个可描述、可检查、可演进的结构。
当然，图结构不会自动让系统正确。
它只是让错误更容易被看见。
这已经很重要。
后端选择就是边界选择
manual 提到两条后端路径：
- 通过 Bolt 直连 Neo4j
- 通过 hosted NAMS REST backend
这不是一个小小的部署选项，而是运行边界。
如果你走自托管 Neo4j，就要负责数据库配置、隔离、备份、权限和运维。
如果你走 NAMS，就要检查远程服务边界、workspace 所属、API 配置、本体版本等问题。
所以第一次评估时，不要先问“哪个更先进”。
应该先问：
这份记忆允许存在哪里？以后谁能读到它？
这个问题回答不清楚，就不要让 Agent 写入长期记忆。
Ontology 是容易被低估的部分
manual 中还提到 NAMS 的 typed、versioned ontology layer。
这部分很容易被忽略，但它决定了记忆能否长期维护。
没有 ontology 边界时，Agent memory 会悄悄漂移：
- 同一个实体被记成多个名字
- preference 和 fact 混在一起
- tool result 被误当成用户意图
- 过期知识继续被检索
- 私有记忆和共享记忆混在同一个池子
ontology 不能自动解决这些问题，但它提供了一个地方来定义“什么是有效记忆”。
第一次试用时，我不建议直接设计复杂领域模型。
更合理的首跑是：
- 一个测试用户
- 一个测试 session
- 两种 entity type
- 一种 relationship
- 一条 reasoning trace
- 一个纠错案例
如果这样的小闭环都无法检查和纠正，扩大规模只会让问题更难发现。
一个安全的第一次运行
给 AI 宿主接入 agent-memory 之前，可以先做一个 sandbox dry run。
不要用生产凭据，不要用真实用户数据。
推荐的最小验证路径：
- 创建临时测试用户和 session。
- 写入一条 short-term conversation message。
- 写入一个明确的 long-term entity，例如一个假的用户偏好。
- 记录一次 reasoning step 或 tool call。
- 在下一轮检索上下文。
- 检查返回内容分别来自哪一层 memory。
- 修改或删除一条错误记忆。
- 再次检索，确认纠正生效。
这里最重要的产物不是“demo 跑起来了”。
真正重要的产物是审计链：
- 写入了什么
- 为什么写入
- 存在哪里
- 如何被检索
- 如何被纠正
- 哪些东西 Agent 不允许记住
最大的坑：把 memory 当成开关
“给 Agent 加 memory”听起来像一个功能增强。
实际上，它改变的是 Agent 的状态模型。
无状态 Agent 可能在一次运行里犯错。
有状态 Agent 可能犯错、记住错误，然后在下一次运行里更自信地复用这个错误。
所以 memory 不是不能加。
而是必须从更小的首跑、更清楚的权限、更可见的复核路径开始。
接入前检查表
在让 AI 宿主使用记忆层之前，至少回答这些问题：
- 启用了哪些 memory tier？
- 哪些写入是自动的，哪些写入需要确认？
- 后端存储在哪里？
- 记忆按用户、workspace、tenant 还是项目隔离？
- 用户能否查看和纠正被记住的事实？
- reasoning trace 是否和长期用户知识分开？
- 检索结果是否显示 provenance？
- 删除路径是否明确？
- 是否有一个 sandbox test 能证明这些边界？
如果答案不清楚，下一步不是生产接入。
下一步应该是更小的验证闭环。
参考：Doramagic agent-memory manual：https://doramagic.ai/en/projects/agent-memory/manual/
说明：本文基于 Doramagic 对 neo4j-labs/agent-memory 的独立项目整理，不是 Neo4j 官方文档，也不代表上游项目背书。
