WeClaw 记忆功能：从「AI 复述」到「精准管理」

背景

WeClaw 是一个基于 Go 的多 agent 消息网关，接入微信等平台，支持多种 LLM 后端。其中「长期记忆」功能允许用户保存跨会话的偏好和事实，每次对话自动注入到 agent 的系统提示词中。

最近在使用中发现了一个问题：微信端发送 /memory 命令查看记忆时，返回的不是原始记忆列表，而是 AI 对记忆内容的复述——比如「已读取，苑广山。你的数字操作系统架构很清晰……」。这显然不是我们想要的效果。

问题定位

排查后发现，/memory 命令虽然在 registerCommands() 中注册了处理函数，但没有加入 isBuiltinCommand() 的白名单。这导致消息处理流程把它当成了普通用户消息，直接发给了 agent，agent 就用自己的理解复述了记忆内容。

修复很简单——在 isBuiltinCommand 的命令列表中加上 /memory：

// messaging/handler.go  
for _, cmd := range []string{  
    "/help", "/info", "/new", "/clear", "/cwd", "/save", "/hub",  
    "/sh", "/$", "/q", "/podcast", "/debate", "/chat", "/roundtable",  
    "/todo", "/timer", "/workflow", "/cron", "/publish", "/zhihu",  
    "/memory",  // ← 新增  
} {  

微信端管理命令

修复后，微信端支持以下记忆管理命令：

命令	功能	示例
/memory	查看所有记忆	/memory
/memory list	同上	/memory list
/memory add <内容>	添加记忆	/memory add 我是做 Go 后端的
/memory <内容>	快捷添加	/memory 偏好简洁回复
/memory del <编号>	删除指定记忆	/memory del 3
/memory clear	清空自己的记忆	/memory clear

命令详解

查看记忆：/memory 返回当前用户的所有记忆条目，格式如：

🧠 长期记忆（3 条，对所有 agent 生效）:  
📌#1 [全局] 用户是 Go 后端开发者  
#2 偏好简洁回复  
#3 关注 Python 代码质量  
  
删除: /memory del <编号> | 清空: /memory clear  

📌 标记的是 Pin 优先的记忆，会排在前面且不会因长度限制被截断。

添加记忆：/memory add 和 /memory <内容> 效果相同，都会创建一条 source=wechat 的记忆。区别是 add 显式指定，<内容> 是快捷方式。

删除记忆：/memory del 3 删除编号为 3 的记忆。注意只能删除自己的记忆，不能删除其他用户的或全局记忆。

清空记忆：/memory clear 清空当前用户的所有记忆，但全局记忆（user_id=*）会保留。

Admin 页面优化

除了修复微信端命令，还对 admin 管理页面做了两项改进：

1. 记忆预览区

在记忆管理页面顶部增加了固定预览区，实时显示「实际注入到 agent 的提示词」。这让管理员能直观看到记忆是如何被格式化并注入到系统提示中的。

预览文本格式：

[关于用户的长期记忆（系统注入，用户看不到这段）]  
- 用户是 Go 后端开发者  
- 偏好简洁回复  
[记忆结束，以下是用户消息]  

支持按用户 ID 筛选预览，也能手动输入任意 user_id 查看。

2. 日志页面快捷复制

日志页面新增四个复制按钮：

• 📋5 — 复制最近 5 条日志
• 📋10 — 复制最近 10 条日志
• 📋轮 — 复制最近一轮（基于时间断档自动分组）
• 📋全 — 复制全部日志

「最近一轮」的定义：从末尾往前找第一个时间间隔 >30 秒的位置，该位置到末尾的所有日志为一轮。这在排查单次请求时非常有用。

自动刷新状态通过 localStorage 持久化，刷新页面后会自动恢复。

技术细节

记忆注入机制

记忆通过 MemoryStore.BuildContext(userID) 注入到 agent 请求中。核心逻辑：

1. 查询该用户的所有记忆（包括全局 * 记忆）
2. Pin 优先排列，普通记忆按列表序
3. 逐条拼接，总长度不超过 2000 字符
4. 超出部分静默丢弃，末尾提示「另有 N 条记忆因长度限制未注入」

注入文本被包裹在 [关于用户的长期记忆] 和 [记忆结束] 标记之间，agent 会将其视为系统上下文而非用户消息。

数据存储

记忆存储在 ~/.weclaw/memories.json 中，结构为：

[  
  {  
    "id": 1,  
    "user_id": "*",  
    "content": "用户是 Go 后端开发者",  
    "category": "profile",  
    "source": "wechat",  
    "pinned": true,  
    "created_at": 1724361600  
  }  
]  

• user_id=* 表示全局记忆，对所有用户生效
• pinned=true 的记忆优先注入且不被截断
• 每次修改后自动写入磁盘

总结

这次优化解决了三个问题：

1. /memory 命令失效 — 加入白名单后正确路由到处理函数
2. 记忆注入不透明 — admin 页面新增预览区，所见即所得
3. 日志排查低效 — 快捷复制按钮 + 智能分轮

记忆系统是 agent 个性化的核心能力。让用户能方便地管理「agent 记住了什么」，是建立人机信任的基础。