Agent Memory System 该怎么设计

如果我们把 Agent Memory System 只理解成“把记忆存进数据库”，那它的价值就会被低估很多。

这类项目真正难的地方，不在于存储本身，而在于四件事：

1. 什么内容该共享
2. 什么内容只该本地保留
3. 不同 Agent 怎么接入
4. 出问题时怎么治理

从这个仓库的设计文档来看，它最值得看的并不是某一个技术点，而是整体拆法。

第一层拆分：共享经验和本地记忆必须分开

这是整个系统里最重要的设计判断。

共享经验层

这层服务的是“跨 Agent 复用”。

更适合放：

• 已验证的方法
• 项目里稳定的规则
• 可被引用的经验总结

本地记忆层

这层服务的是“当前 Agent 的私有上下文”。

更适合放：

• 当前 Agent 的偏好
• 临时工作记忆
• 不适合公开扩散的信息

如果这两层不分开，会有两个直接后果：

• 不该共享的信息被扩散
• 真正有复用价值的经验被临时噪声淹没

第二层拆分：存储层和接入层不能混成一层

仓库文档里一个很好的点，是它不只考虑“数据放哪里”，还考虑“别人怎么来用”。

所以这里至少有两层：

存储层

负责：

• 共享经验表
• 本地记忆表
• 元数据
• 标签、编码、重要度、来源

接入层

负责：

• CLI
• Python SDK
• REST Gateway API
• 给 OpenClaw / Claude Code / Codex 的适配入口

这层拆开之后，系统才会具备真正的可扩展性。
否则每加一个 Agent，都会变成一次重写。

Gateway API 为什么是关键

很多人做多 Agent 系统时，会先写多个脚本分别接不同工具。
这样短期很快，长期很乱。

Agent Memory System 往 Gateway API 方向走，是个比较稳的思路，因为它把这些能力统一了：

• 写入共享记忆
• 搜索共享记忆
• 查询共享经验
• 管理访问权限
• 注册 Agent 身份

这层的价值不是“看起来架构更大”，而是让所有 Agent 对记忆系统说同一种语言。

经验编码规则为什么重要

这个项目不是把经验随意落成一段文本，而是给经验设计了编码格式，例如：

EXP-{DOMAIN}-{TAG}-{SEQ:4}

这意味着共享经验在系统里不是“匿名文本”，而是可编号、可引用、可追踪的对象。

它带来的好处很实在：

• 后续检索结果更容易被引用
• 团队协作时可以直接讨论某条经验
• 删除、覆盖、更新时更容易治理

ACL 和 Agent Registry 为什么不是“高级可选项”

很多初版系统会忽略权限和 Agent 注册，先把功能跑通再说。
这当然可以，但如果目标是跨 Agent 共享，ACL 和 Registry 很快就会从“可选”变成“必需”。

ACL 解决的问题

• 哪个 Agent 能看哪些共享记忆
• 哪些项目级经验不该被全局读取
• 哪些操作允许写，哪些只允许读

Agent Registry 解决的问题

• 谁在访问系统
• 它属于哪类 Agent
• 它具备什么能力
• 它最近是否还活跃

如果没有这两层，所谓“共享”很快就会滑向“混用”。

和 OpenClaw 官方记忆系统怎样分工更现实

我很认同这个项目文档里那种修正后的定位：
不是重新造一个完全替代 OpenClaw 的记忆系统，而是把它当成共享层和接入层的补充。

一个更现实的分工是：

OpenClaw 官方记忆负责

• 本地记忆主能力
• 内建索引和搜索
• Dreaming 等已有记忆机制
• 本地工作空间记忆组织

Agent Memory System 负责

• 跨 Agent 共享层
• Gateway API
• 外部 Agent 适配
• 共享经验编码、治理和访问控制

这个分工的好处是明显的：

• 不和已有能力硬碰硬
• 复用 OpenClaw 已经做好的部分
• 把精力放在“跨 Agent”这个真正新的问题上

从架构角度看，最合理的模块边界

按这个项目的文档，我会把它理解成下面几个核心模块：

1. Shared Experience Store 负责沉淀共享经验和元数据。

2. Local Memory Store 负责保存本地或作用域内记忆。

3. Gateway API 负责统一外部读写入口。

4. Agent Adapter Layer 负责让 OpenClaw、Claude Code、Codex 用各自可接受的方式接入。

5. ACL / Registry 负责谁能访问什么，以及系统里有哪些 Agent。

这几个模块一旦拆清楚，后续无论是加新 Agent，还是加新检索方式，成本都会小很多。

一个更像工程实现的伪代码

type Visibility = "private" | "shared" | "global";

type SharedMemoryRecord = {
  id: string;
  content: string;
  summary?: string;
  visibility: Visibility;
  sourceAgent: string;
  projectPath?: string;
  tags: string[];
  importance: number;
};

function storeSharedMemory(input: SharedMemoryRecord, caller: AgentIdentity) {
  assertAgentRegistered(caller);
  assertWritePermission(caller, input.visibility, input.projectPath);

  const normalized = normalizeRecord(input);
  const embedding = buildEmbedding(normalized.content);

  saveToMemoryStore(normalized, embedding);
  updateSearchIndex(normalized);
  writeAuditLog(caller, "store", normalized.id);

  return normalized.id;
}

function searchSharedMemory(query: string, caller: AgentIdentity) {
  assertAgentRegistered(caller);

  const scope = buildVisibleScope(caller);
  const vectorHits = vectorSearch(query, scope);
  const keywordHits = keywordSearch(query, scope);

  return rerankMergedHits(vectorHits, keywordHits);
}

这段逻辑里最重要的不是技术选型，而是顺序：

• 先识别调用者
• 再检查可见范围
• 再处理存储和检索
• 最后写审计

这类设计最容易做错的地方

最常见的三个偏差是：

1. 只做存储，不做接入边界
2. 只做检索，不做可见范围和治理
3. 只考虑 OpenClaw，不考虑其它 Agent 以后怎么接进来

短期看这些都不一定立刻出问题。
但只要系统真的开始承载协作，它们都会变成结构性障碍。

如果你要继续往下推进，下一步最该补什么

设计想清楚之后，最合理的下一步不是继续堆概念，而是验证：

• MySQL 初始化和环境变量配置是否顺畅
• CLI / SDK 是否足够稳定
• 第一个接入场景选得对不对
• 从 OpenClaw 到其他 Agent 的接入链是否最小可跑

这也是为什么部署实战篇会比继续谈抽象架构更重要。

延伸阅读

• 什么是 Agent Memory System：一个把跨 Agent 共享经验和本地记忆拆开的实战项目
• Agent Memory System 实战部署指南：MySQL、CLI、SDK 和跨 Agent 接入怎么落地
• 跨 Agent 记忆系统最容易做错的地方：共享污染、检索失真和治理失控
• Agent Memory System 项目页