Agent Memory System 实战部署指南

这类项目最容易出现一种错觉：
架构图已经很完整了，部署应该不难。

但真正落地时，常见卡点往往不是“原理不懂”，而是：

• MySQL 配置没理顺
• 环境变量没配齐
• 初始化脚本没跑对
• CLI 跑通了，SDK 却没接顺
• 还没验证单条经验能写入和搜索，就急着接多 Agent

所以这篇不讲大而全，只讲一个更现实的落地顺序。

第一阶段目标：只跑通最小闭环

先不要把目标定成：

• 多 Agent 实时共享
• 权限全量上线
• 自动记忆工作流
• 复杂的 Gateway 编排

更合理的第一阶段目标是：

1. 能成功初始化数据库
2. 能写入一条共享经验
3. 能搜索并取回这条经验
4. 能用 CLI 或 SDK 完成一次完整验证

只要这四步成立，项目就已经从“文档设计”变成“可运行原型”了。

建议的最小部署顺序

1. 克隆仓库

git clone https://github.com/kunpeng-ai-lab/agent-memory-system.git
cd agent-memory-system

这一步看起来没信息量，但建议同时确认三件事：

• 仓库结构是否完整
• 你准备跑的是哪个环境
• 文档和脚本是否和当前分支匹配

2. 安装依赖

Windows：

install.bat

Linux / macOS：

chmod +x install.sh
./install.sh

这一步的重点不是“装完就好”，而是确认安装脚本之后：

• Python 依赖是否可用
• CLI 是否可执行
• 配置样例是否在预期位置

3. 准备 MySQL

这个项目的共享经验层是围绕 MySQL 持久化展开的，所以数据库准备要先做稳。

典型初始化可以是：

CREATE DATABASE agent_memory CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'memory_user'@'%' IDENTIFIED BY 'YOUR_STRONG_PASSWORD';
GRANT ALL PRIVILEGES ON agent_memory.* TO 'memory_user'@'%';
FLUSH PRIVILEGES;

这里最该注意的不是语法，而是：

• 字符集要统一到 utf8mb4
• 用户权限尽量只限定在目标数据库
• 不要把密码硬写进仓库

4. 配环境变量

PowerShell：

$env:MEMORY_DB_HOST = "YOUR_MYSQL_HOST"
$env:MEMORY_DB_PORT = "3306"
$env:MEMORY_DB_DATABASE = "agent_memory"
$env:MEMORY_DB_USER = "memory_user"
$env:MEMORY_DB_PASSWORD = "YOUR_PASSWORD"

这一层其实是在验证“系统和环境的边界是否清晰”。
如果这里都还靠手改源码，后面接工作流会越来越脆。

5. 初始化数据库结构

mysql -h YOUR_MYSQL_HOST -P 3306 -u memory_user -p agent_memory < scripts/init_mysql.sql

跑完之后，不要立刻跳下一步。
建议先确认：

• 目标表确实创建成功
• 索引和关键字段在不在
• 数据库用户真的有写入权限

第二阶段：先用 CLI 跑通

我很建议先用 CLI，而不是直接写接入代码。

因为 CLI 的好处是：

• 它最接近“系统到底能不能用”的最短路径
• 出错时更容易判断是配置问题、数据库问题还是业务问题
• 它可以最快验证共享经验的写入和检索闭环

写入一条共享经验

python -m skills.agent-memory.scripts.client share \
  --title "FastAPI 性能优化" \
  --summary "uvicorn workers=4 更稳" \
  --content "# FastAPI 性能优化..." \
  --tags fastapi,performance \
  --domain BACKEND

搜索共享经验

python -m skills.agent-memory.scripts.client search "fastapi"

获取详情

python -m skills.agent-memory.scripts.client get EXP-BACKEND-FASTAPI-0001

这几步连起来，才是真正的“第一条价值链”。

第三阶段：再切到 Python SDK

当 CLI 跑通后，再进入 SDK 才划算。

一个最小示例可以像这样：

from skills.agent-memory.scripts import ExperienceClient, MemoryClient

exp_client = ExperienceClient()

exp_client.share_experience(
    title="FastAPI 性能优化最佳实践",
    summary="uvicorn workers=4 在当前场景更稳",
    content="# FastAPI 性能优化\n\n## workers 配置\n...",
    tags=["fastapi", "performance"],
    domain="BACKEND",
    importance=8.0,
)

results = exp_client.search_experiences("fastapi 性能")

mem_client = MemoryClient()
mem_client.store_memory(
    content="当前 Agent 偏好在下午处理复杂问题",
    memory_type="preference",
    tags=["user", "habit"],
)

这里的关键不是语法，而是你会开始看到系统边界：

• 共享经验客户端和本地记忆客户端是不同角色
• 共享层和私有层不是一回事
• 接下来的工作流接入，也应该保留这条边界

怎样把它接到 OpenClaw / Agent workflow 里

很多人会在这里直接上复杂方案。
我反而建议只接一个最小触发链：

最小接法

1. 工作流开始前，查询相关共享经验
2. 工作流结束后，把经过确认的经验写回

例如：

• 记住 xxx：写入本地记忆
• 分享经验：写入共享经验层
• 谁有 xxx 经验：查询共享经验

这样做的好处是：

• 写入边界清楚
• 调试成本低
• 不会一开始就把共享层变成噪声池

一个更现实的接入伪代码

async function runTaskWithMemory(task: TaskInput) {
  const sharedContext = await searchSharedExperiences(task.query);

  const result = await executeWorkflow({
    task,
    sharedContext,
  });

  if (result.hasVerifiedInsight) {
    await shareExperience({
      title: result.insightTitle,
      summary: result.insightSummary,
      content: result.insightMarkdown,
      tags: result.tags,
    });
  }

  return result;
}

这段逻辑刻意很保守。
因为第一阶段真正重要的是：

• 能读
• 能写
• 能回查

而不是自动化程度有多高。

部署时最容易踩的坑

1. 数据库能连，但权限不完整

现象通常是：

• 查询正常
• 写入报错
• 初始化脚本跑不全

2. 环境变量配置方式不统一

一个脚本从 .env 读，一个脚本从系统变量读，最后调试会非常痛苦。

3. 还没跑通单链路，就同时接多个 Agent

这种情况下，你根本分不清问题出在：

• 数据层
• API 层
• 适配器层
• 某个 Agent 的调用方式

4. 把所有工作流结果都当成可共享经验

这不是“更智能”，而是更快把共享层污染掉。

一个更适合验证阶段的验收标准

部署完第一版后，我建议只看这四件事：

1. 一条经验是否能稳定写入
2. 另一条查询是否能稳定取回
3. 共享经验和本地记忆是否没有混用
4. 出错时是否能快速定位是数据库、CLI 还是 SDK 问题

这四项比“看起来功能很多”更重要。

如果下一步继续做，应该优先补什么

在我看来，部署跑通之后最该补的是：

1. 第一批真实经验样本
2. 接入边界的人工确认规则
3. 简单的审计和回查能力
4. 只选一个 Agent workflow 场景做深

这样这套系统才会从“能跑”走向“值得长期保留”。

延伸阅读

• 什么是 Agent Memory System：一个把跨 Agent 共享经验和本地记忆拆开的实战项目
• Agent Memory System 该怎么设计：共享经验、本地记忆、Gateway API 和适配边界
• 跨 Agent 记忆系统最容易做错的地方：共享污染、检索失真和治理失控
• Agent Memory System 项目页