Memory
大语言模型本身是无状态的——每次请求都从零开始。ESP-Claw 通过 claw_memory 将两类持久化上下文在请求前注入，使 Agent 表现出「记住」对话与用户的能力。
两类记忆面向不同的时间尺度，解决不同的问题：
记忆运行模式
Section titled “记忆运行模式”ESP-Claw 的记忆模块提供两种记忆模式：
| 模式 | 行为 | 适用场景 |
|---|---|---|
Structured memory management（完整模式） | 使用结构化记录 + 摘要标签目录；需要时通过 memory_recall 召回详情 | 默认模式，适合持续使用与自动抽取 |
Lightweight memory（轻量模式） | 维持 profile 与会话历史，长期记忆以 MEMORY.md 文本注入为主 | 资源受限或希望更简化链路 |
basic_demo 默认使用完整模式，可在 menuconfig (Top) → Basic Demo Config → Memory management mode 切换。
会话历史：对话内的连贯性
Section titled “会话历史：对话内的连贯性”会话历史解决的是单次对话的上下文连贯问题。没有它，每一轮消息对模型来说都是全新的开始，无法引用之前说过的内容。
ESP-Claw 以 Session ID 为边界管理历史。同一 Session ID 下的轮次串联成一条对话线，切换 Session ID 即切换到另一条独立对话线，历史互不可见。这让系统可以并行处理来自不同来源（如不同 IM 用户、不同渠道）的对话，彼此隔离。
会话历史有容量上限（最大消息条数与单条字符数），超出后自动截断最旧的轮次。这是有意为之的设计：防止历史无限膨胀导致 token 消耗失控，同时引导系统将真正需要长期保留的信息提炼进长期记忆。
长期记忆：跨 session 的持久知识
Section titled “长期记忆：跨 session 的持久知识”长期记忆跨所有 Session 共享，解决的是超出单次对话生命周期的信息持久化问题：用户偏好、设备状态摘要、跨任务的重要约定等。
记忆能力组成
Section titled “记忆能力组成”结构化长期记忆支持以下基础操作：
| 操作 | 作用 |
|---|---|
memory_store | 写入长期记忆 |
memory_recall | 按摘要标签召回相关记忆 |
memory_list | 查看当前已存储的记忆 |
memory_update | 更新已有记忆 |
memory_forget | 删除指定记忆 |
可编辑画像与灵魂记忆
Section titled “可编辑画像与灵魂记忆”除了结构化长期记忆，claw_memory 还会维护三份可编辑的 profile 文件，它们会作为系统上下文注入：
| 文件 | 作用 | 建议写入内容 |
|---|---|---|
user.md | 当前用户画像 | 称呼、偏好语言、常用术语、长期约定 |
soul.md | Agent 的“灵魂”与价值观 | 助手的核心风格、做事原则、优先级 |
identity.md | Agent 身份卡 | 名称、角色、能力边界、擅长方向 |
可以把它们理解为“稳定行为设定”，而 memory_records.jsonl 中的结构化条目更偏向“可检索的事实记忆”。
结构化记忆条目
Section titled “结构化记忆条目”当前实现中，长期记忆不是固定的 type 枚举，而是结构化条目模型。每条条目主要包含：
| 字段 | 用途 | 示例 |
|---|---|---|
content | 记忆正文（归一化后的长期事实） | “用户偏好中文回复” |
tags | 用于生成摘要标签目录（最多取前 1–3 个） | 中文,回复风格 |
keywords | 用于关键词索引，辅助定位相关条目 | 中文,简洁 |
source | 记录来源（如 manual、auto_llm） | auto_llm |
轻量级检索：摘要标签机制
Section titled “轻量级检索：摘要标签机制”ESP-Claw 不依赖向量数据库，而采用 摘要标签 机制实现轻量级检索。每条记忆通常带有 1–3 个 tags，系统从中生成摘要标签目录。完整模式下，请求时系统自动注入该目录，供 LLM 先定位标签，再按需调用 memory_recall 召回正文。
自动抽取与去重
Section titled “自动抽取与去重”完整模式下，请求开始时会尝试对最新用户消息做自动抽取：将可长期保留的信息写入结构化记忆，并在写入前后做去重/替换处理，避免重复积累同一事实。
需要注意，当前自动抽取主要基于用户消息本身；设备事件是否入库取决于业务侧是否主动调用 memory_store 写入。
| 内容类型 | 建议放在 |
|---|---|
| 助手人格、风格、价值观 | soul.md |
| 助手名称、角色、能力边界 | identity.md |
| 用户长期偏好与沟通约定 | user.md + 长期记忆（memory_ops） |
| 用户姓名、偏好、语言习惯 | 长期记忆（完整模式优先通过 memory_ops 管理） |
| 设备当前状态、已完成任务的摘要 | 长期记忆（结构化记录 + 摘要标签） |
| 本次对话的临时指令、中间步骤 | 自然留在会话历史中，无需干预 |
| 一次性但跨 session 的状态 | 写入长期记忆，任务完成后主动清除 |