---
title: Memory
description: 结构化长期记忆与会话历史：摘要标签检索、会话历史隔离与自动抽取机制。
---

import { LinkCard, Aside } from '@astrojs/starlight/components';

大语言模型本身是无状态的——每次请求都从零开始。ESP-Claw 通过 `claw_memory` 将两类持久化上下文在请求前注入，使 Agent 表现出「记住」对话与用户的能力。

两类记忆面向不同的时间尺度，解决不同的问题：

## 记忆运行模式

ESP-Claw 的记忆模块提供两种记忆模式：

| 模式 | 行为 | 适用场景 |
|---|---|---|
| `Structured memory management`（完整模式） | 使用结构化记录 + 摘要标签目录；需要时通过 `memory_recall` 召回详情 | 默认模式，适合持续使用与自动抽取 |
| `Lightweight memory`（轻量模式） | 维持 profile 与会话历史，长期记忆以 `MEMORY.md` 文本注入为主 | 资源受限或希望更简化链路 |

`edge_agent` 默认使用完整模式，可在 menuconfig <kbd>(Top)</kbd> → <kbd>App Claw Config</kbd> → <kbd>App Claw memory management mode</kbd> 切换。

## 会话历史：对话内的连贯性

会话历史解决的是**单次对话的上下文连贯**问题。没有它，每一轮消息对模型来说都是全新的开始，无法引用之前说过的内容。

ESP-Claw 以 **Session ID** 为边界管理历史。同一 Session ID 下的轮次串联成一条对话线，**切换 Session ID 即切换到另一条独立对话线**，历史互不可见。这让系统可以并行处理来自不同来源（如不同 IM 用户、不同渠道）的对话，彼此隔离。

会话历史有容量上限（最大消息条数与单条字符数），超出后自动截断最旧的轮次。这是有意为之的设计：防止历史无限膨胀导致 token 消耗失控，同时引导系统将真正需要长期保留的信息提炼进长期记忆。

## 长期记忆：跨 session 的持久知识

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

### 记忆能力组成

结构化长期记忆支持以下基础操作：

| 操作 | 作用 |
|------|------|
| `memory_store` | 写入长期记忆 |
| `memory_recall` | 按摘要标签召回相关记忆 |
| `memory_list` | 查看当前已存储的记忆 |
| `memory_update` | 更新已有记忆 |
| `memory_forget` | 删除指定记忆 |

### 可编辑画像与灵魂记忆

除了结构化长期记忆，`claw_memory` 还会维护三份可编辑的 profile 文件，它们会作为系统上下文注入：

| 文件 | 作用 | 建议写入内容 |
|---|---|---|
| `user.md` | 当前用户画像 | 称呼、偏好语言、常用术语、长期约定 |
| `soul.md` | Agent 的“灵魂”与价值观 | 助手的核心风格、做事原则、优先级 |
| `identity.md` | Agent 身份卡 | 名称、角色、能力边界、擅长方向 |

可以把它们理解为“稳定行为设定”，而 `memory_records.jsonl` 中的结构化条目更偏向“可检索的事实记忆”。

### 结构化记忆条目

当前实现中，长期记忆不是固定的 type 枚举，而是结构化条目模型。每条条目主要包含：

| 字段 | 用途 | 示例 |
|------|------|------|
| `content` | 记忆正文（归一化后的长期事实） | “用户偏好中文回复” |
| `tags` | 用于生成摘要标签目录（最多取前 1–3 个） | `中文,回复风格` |
| `keywords` | 用于关键词索引，辅助定位相关条目 | `中文,简洁` |
| `source` | 记录来源（如 `manual`、`auto_llm`） | `auto_llm` |

### 轻量级检索：摘要标签机制

ESP-Claw 不依赖向量数据库，而采用 **摘要标签** 机制实现轻量级检索。每条记忆通常带有 1–3 个 `tags`，系统从中生成摘要标签目录。完整模式下，请求时系统自动注入该目录，供 LLM 先定位标签，再按需调用 `memory_recall` 召回正文。

### 自动抽取与去重

完整模式下，请求开始时会尝试对最新用户消息做自动抽取：将可长期保留的信息写入结构化记忆，并在写入前后做去重/替换处理，避免重复积累同一事实。

需要注意，当前自动抽取主要基于用户消息本身；设备事件是否入库取决于业务侧是否主动调用 `memory_store` 写入。

<Aside type="caution" title="注意数据来源">
  在完整模式中，`MEMORY.md` 不是记忆检索的唯一事实来源；检索与更新以结构化文件（`memory_records.jsonl`、`memory_index.json`）为准。
</Aside>

## 使用建议

| 内容类型 | 建议放在 |
|---|---|
| 助手人格、风格、价值观 | `soul.md` |
| 助手名称、角色、能力边界 | `identity.md` |
| 用户长期偏好与沟通约定 | `user.md` + 长期记忆（`memory_ops`） |
| 用户姓名、偏好、语言习惯 | 长期记忆（完整模式优先通过 `memory_ops` 管理） |
| 设备当前状态、已完成任务的摘要 | 长期记忆（结构化记录 + 摘要标签） |
| 本次对话的临时指令、中间步骤 | 自然留在会话历史中，无需干预 |
| 一次性但跨 session 的状态 | 写入长期记忆，任务完成后主动清除 |

<LinkCard href="@lang/reference-core/claw-memory" title="claw_memory" description="初始化配置字段、完整/轻量模式差异与 memory 目录文件布局" />
