记忆系统

本章讲 Ameba-Claw 如何记住东西。「记忆系统」从用户视角说明设备有哪些记忆、如何查看、编辑与清除；「记忆内部机制」深入开发者视角——会话历史与结构化长期记忆两种时间尺度、按 token 预算的历史压缩、摘要标签检索，以及每轮对话结束后的自动抽取。

记忆与个性化

Ameba-Claw 将 Agent 的身份、记忆和会话历史全部存储在本地 Flash（VFS）中，无需云端账号，数据始终留在设备上。本文介绍记忆系统的三个层次，以及如何通过 Web 后台或 AT 命令对其进行查看、编辑和清除。

备注

所有记忆文件均保存在芯片本地 Flash 中，不会上传到任何云端服务器。即使切换 LLM 服务商，记忆数据也不受影响。

记忆系统概述

Ameba-Claw 的记忆系统分为三个层次，各自承担不同的职责：

第一层：身份与个性（Identity & Personality）

由四个 Markdown 文件定义 Agent "是谁"：

• vfs:/AGENTS.md — Agent 的职责范围和工具调用策略（系统提示词的核心）

• vfs:/SOUL.md — 人格与沟通风格，例如语气是否简洁、遇到问题是否主动建议

• vfs:/IDENTITY.md — 自我认知：Agent 的名字和自我描述

• vfs:/USER.md — 用户档案：用户的名字、语言偏好、职业背景等

第二层：长期记忆（Long-term Memory）

vfs:/MEMORY.md 以及结构化记忆数据库存储 Agent 跨会话记住的事实，例如用户偏好、过去发生的重要事件等。每次对话结束后，Agent 会自动将值得记忆的内容提取并写入这一层。

第三层：会话历史（Session History）

vfs:/session/ 目录下每个会话对应一个 s_<会话 id>_<哈希>.json 文件，记录该会话中的完整对话轮次。Agent 在后续对话中可以引用历史会话内容，实现连续上下文。

三层记忆对比

层次	内容	变更方式	影响范围
身份与个性	Agent 是谁、怎么说话	手动编辑文件	所有后续对话
长期记忆	记住的用户事实	自动提取 / 手动管理	所有后续对话
会话历史	当次及历史对话轮次	自动写入 / 手动清除	当次及引用的历史会话

个性定制文件

以下四个文件决定 Agent 的个性与行为方式。你可以随时编辑它们，保存后无需重启，下一次对话即刻生效。

个性定制文件一览

文件	作用	示例内容
vfs:/AGENTS.md	Agent 基础身份：职责范围、工具调用策略	"你是一个嵌入式硬件助手，专注于 Ameba SoC。遇到硬件问题时优先调用 board_hardware_info skill 获取引脚信息……"
vfs:/SOUL.md	人格与沟通风格：语气、价值观、行为倾向	"说话简洁有力，避免冗余客套。遇到硬件问题要主动建议查询引脚复用关系。在不确定时坦诚告知而不是猜测……"
vfs:/IDENTITY.md	自我认知：名字、描述	"你叫小爪，是一个运行在 RTL8721F 上的嵌入式 AI 助手，由 Realtek Ameba-Claw 框架驱动……"
vfs:/USER.md	用户档案：姓名、偏好、语言	"用户叫小明，偏好中文回复，是 IoT 开发工程师，主要使用 RTL8721F 开发板……"

如何编辑

1. 打开 Web 后台（在浏览器中访问设备的 WebIM 地址）。

2. 进入 记忆管理 页面。

3. 找到对应文件，点击进入编辑视图，直接修改文本内容。

4. 点击 保存。

保存后立即生效，下一次发送消息时 Agent 将使用更新后的设定。

小技巧

AGENTS.md 和 SOUL.md 的修改效果最为显著，建议先从这两个文件入手调整 Agent 的行为风格。

示例：给 Agent 改个名字

下面以将 Agent 名字从"Ameba-Claw"改为"小爪"为例，演示完整操作流程。

步骤 1：打开记忆管理

在浏览器中打开 Web 后台，点击左侧导航或顶部菜单中的 记忆管理。

步骤 2：编辑 IDENTITY.md

在文件列表中找到 IDENTITY.md，点击打开编辑器。你会看到类似如下内容：

你叫 Ameba-Claw，是一个运行在 Ameba SoC 上的嵌入式 AI 助手。

步骤 3：修改名字

将 Ameba-Claw 改为 小爪：

你叫小爪，是一个运行在 Ameba SoC 上的嵌入式 AI 助手。

步骤 4：保存

点击页面上的 保存 按钮。稍等片刻，提示保存成功。

步骤 5：验证

在对话框中发送一条消息，例如：

你叫什么名字？

Agent 应回复类似"我叫小爪"的内容。如果没有立即生效，尝试刷新页面后重新发送。

备注

名字修改只影响 Agent 对自己的称呼，不会改变 IM 平台（如 Telegram）中显示的 Bot 用户名。IM 平台的用户名需要在对应平台的 Bot 设置中单独修改。

长期记忆

在对话过程中，Agent 会自动从对话内容中提取值得记住的事实，保存到 vfs:/MEMORY.md 和结构化记忆数据库中。这样，即使开始一个全新的会话，Agent 也能记住你的偏好和过去交流过的重要事项。

长期记忆的内容示例：

• 用户的名字和语言偏好

• 用户正在使用的开发板型号

• 用户反复提到的需求或偏好

• 重要的历史事件（例如"上次成功烧录的固件版本"）

通过 Web 后台管理

1. 打开 Web 后台，进入 记忆管理 页面。

2. 切换到 长期记忆 标签页，查看以表格形式展示的所有记忆条目。

3. 点击某条记忆右侧的 编辑 按钮，可以修改内容。

4. 点击 删除 可以移除单条记忆。

5. 操作完成后点击 刷新 确认变更已生效。

通过 AT 命令管理

如果你通过串口连接设备，可以使用以下 AT 命令：

AT+CLAW=memory,list

列出所有长期记忆条目，输出格式为纯文本列表。

AT+CLAW=memory,clear

清除所有长期记忆。此操作不可撤销，请谨慎使用。

警告

AT+CLAW=memory,clear 会永久删除所有长期记忆，包括 MEMORY.md 中的内容以及结构化数据库中的所有条目。如果你只想删除某一条，建议通过 Web 后台单条删除。

会话历史

每一次与 Agent 的对话会话都以 .json 文件的形式保存在 vfs:/session/ 目录下。文件名由会话 ID 生成，形如 vfs:/session/s_<会话 id>_<哈希>.json``（例如 ``s_serial_atcmd_1a2b3c4d.json）。

Agent 在处理新消息时，会将当前及历史会话内容作为上下文的一部分，从而支持跨消息的连续对话。

通过 AT 命令管理

AT+CLAW=session,list

列出 vfs:/session/ 下所有会话文件及其基本信息（文件名、大小等）。

AT+CLAW=session,clear

清除当前活跃会话的历史记录。后续对话将在新的上下文中开始，但不影响其他已保存的会话文件。

AT+CLAW=session,clear,all

清除所有会话历史文件，彻底重置对话记录，相当于让 Agent 从零开始记忆新的对话。

小技巧

如果你想让 Agent "忘掉"之前说的一切，执行 AT+CLAW=session,clear,all 清除所有会话历史即可。长期记忆（MEMORY.md）不受此命令影响，需要单独清除。

备注

会话历史文件占用 Flash 存储空间。如果设备存储空间紧张，建议定期清理旧会话。

通过对话更新记忆

除了手动编辑文件，你也可以直接在对话中告诉 Agent 需要记住或忘记的内容。Agent 会自动将这些指令转化为对记忆文件的更新操作。

让 Agent 记住新内容

在对话中直接说：

请记住我叫小明，我喜欢简短的回复

Agent 收到后会将这条信息更新到 vfs:/USER.md 和长期记忆中，并回复确认。后续所有对话都会应用这项设定。

让 Agent 忘记某些内容

请忘掉你知道的关于我工作的所有信息

Agent 会从 USER.md、MEMORY.md 以及结构化记忆数据库中删除与你工作相关的记忆条目，并告知你已执行。

更新 Agent 的沟通风格

以后回复我时请用英文

Agent 会将语言偏好更新到 USER.md 中，下一条回复起即切换为英文。

小技巧

通过对话更新记忆是最自然的方式，适合随时调整偏好。如果你需要对 Agent 的核心身份或系统提示做较大改动，建议直接在 Web 后台编辑 AGENTS.md 或 SOUL.md，这样修改更加精确可控。

记忆系统内部机制

本文面向开发者，介绍 claw_memory 的内部工作方式：两种时间尺度的记忆、与 Agent 核心的对接、结构化长期记忆与按 token 预算的历史压缩。面向用户的"如何查看/编辑/清除记忆"见 记忆系统。

大语言模型本身是无状态的——每次请求都从零开始。claw_memory 在请求前把两类持久化上下文注入，使 Agent 表现出"记住"的能力。

初始化

claw_memory_init() 配置各目录与容量（ameba_claw_main.c 里的默认值）：

字段	说明 / 默认
session_root_dir	会话历史目录，vfs:/session
memory_root_dir	长期记忆目录，vfs:/memory （存 long_term_store.json）
profile_root_dir	人设/画像文件根目录，vfs:
max_session_turns	单会话保留的最大轮数
compaction_token_threshold	按 token 预算触发压缩的阈值（默认 110000）
context_window_tokens	上下文硬上限（默认 128000），同步裁剪据此兜底

与 Agent 核心的对接

claw_memory 通过一组 context provider 和一个写回回调接入 Agent（挂接顺序见 启动与运行时装配）：

• claw_memory_profile_provider —— 注入可编辑的人设与画像文件（AGENTS.md / SOUL.md / IDENTITY.md / USER.md，位于 vfs:/）。

• claw_memory_compaction_summary_provider —— 注入历史压缩摘要。

• claw_memory_session_history_provider —— 每次请求前注入当前会话的近期轮次。

• claw_memory_long_term_label_provider —— 注入长期记忆的**摘要标签目录**，而非全部记忆正文。

写回：claw_memory_append_session_turn() 作为 Agent 的 append_session_turn 回调，把每轮的用户消息、助手回复、以及本轮工具调用的原样序列化（tool_msgs_json）追加写回会话文件。工具轮的原样保存，使下次请求能字节级重放工具历史，既恢复跨轮工具可见性，又保持提示词前缀连续（利于缓存命中）。

会话历史：单次对话的连贯

会话历史以 session_id 为边界：同一 session_id 下的轮次串成一条对话线，切换 session_id 即切到另一条独立对话线，历史互不可见。这让系统能并行处理来自不同来源的对话。

每个会话对应一个文件，路径由 session_id 经 djb2 哈希 + 净化生成，形如 vfs:/session/s_<会话 id>_<哈希>.json。其它模块要拿会话文件路径，必须调 claw_memory_session_file_path()，不能自己重算哈希，否则路径会不一致。

按 token 预算的历史压缩

会话不是简单的定长环形缓冲。系统让对话自然增长，直到上一次请求的真实 prompt_tokens 达到 compaction_token_threshold，才把较旧的轮次总结压缩；context_window_tokens 是硬上限，同步裁剪据此兜底，保证不超模型窗口。压缩时会保护最近若干轮不动（compaction_protect_last）。真实 token 数由 Agent 的 LLM 响应回填（见 Agent 核心）。

长期记忆：跨会话的持久知识

长期记忆跨所有会话共享，解决超出单次对话生命周期的信息持久化：用户偏好、设备状态摘要、跨任务约定等。

结构化记忆条目

长期记忆不是固定的类型枚举，而是结构化条目 claw_memory_item_t：

字段	说明
id	自动分配的唯一编号
content	记忆正文
source	来源：user / llm / system
tags	逗号分隔的标签串
summary	≤40 字的短标签，用于注入摘要标签目录
access_count / created_at	访问次数 / 创建时间戳

C 层 CRUD API：claw_memory_store / claw_memory_recall / claw_memory_update / claw_memory_forget / claw_memory_list。这五个操作同时以同名的 LLM 工具（memory_store 等，属 memory 组）暴露给模型（见 Capability 系统）。

轻量级检索：摘要标签

系统不依赖向量数据库，而用**摘要标签**机制做轻量检索。每条记忆带一个短 summary 标签，系统据此生成摘要标签目录；请求时只注入这个目录（而非全部正文），供 LLM 先定位标签、再按需调 memory_recall 召回正文。这样在有限的上下文预算里也能"记得住、找得到"。

自动抽取

Agent 每轮结束后，记忆自动抽取观察器（claw_memory_extract_observer，通过完成观察器机制挂接，见 Agent 核心）会尝试从对话里提取值得长期保留的信息并写入结构化记忆，写入前后做去重/替换，避免重复积累同一事实。

人设与画像文件

除结构化长期记忆外，claw_memory 还维护几份可编辑的 Markdown 文件（位于 vfs:/），作为系统上下文注入，代表"稳定的行为设定"：AGENTS.md （职责与工具策略）、SOUL.md （人格与风格）、IDENTITY.md （身份）、USER.md （用户画像）。它们与"可检索的事实记忆"（结构化条目）互补。用户侧的编辑方式见 记忆系统。