尧图网站建设 
ESP-Claw 记忆管理器深潜上下文持久化与会话压缩的实现原理【免费下载链接】esp-clawESP-Claw, a Chat Coding AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-claw在资源受限的 ESP32 芯片上运行 AI 智能体最大的挑战之一是如何让设备记住对话。开源项目ESP-Claw一款面向 IoT 设备的Chat Coding AI 智能体框架内置了完整的记忆管理器Memory Manager它解决了两个核心问题上下文持久化——把每一轮对话安全地写入 Flash 存储以及会话压缩——在存储空间耗尽前自动瘦身历史让智能体能无限对话而不撑爆内存。这篇文章将带你逐层拆解 ESP-Claw 记忆管理器的四层架构、会话压缩算法和异步记忆提取机制即使你只熟悉 C 语言基础也能看懂这套精巧的嵌入式记忆设计。为什么嵌入式 AI 代理需要专门的记忆管理器云端大模型服务通常把对话历史放在内存里但 ESP32 只有几十 KB 到几 MB 的 RAM 和有限的 Flash 写入寿命。ESP-Claw 的记忆管理器代码位于 components/claw_modules/claw_memory/因此设计了四套互补的记忆分别应对不同尺度的记忆需求记忆层级存储介质生命周期典型内容会话历史数据文件 二进制索引单次会话完整的用户/助手消息流长期记忆JSONL 记录 索引跨会话永久用户偏好、持久事实画像记忆Markdown 文件永久Agent 人设与用户画像摘要标签JSON 索引随长期记忆可检索的记忆标签目录上下文持久化数据文件 二进制索引的双文件设计会话历史是整个系统的地基。每当核心引擎完成一轮对话就会通过 claw_core_context_persist.c 中的三个入口把消息交给记忆层用户消息claw_core_persist_context_user_messages_if_configured工具调用轮claw_core_persist_context_tool_round_if_configured助手工具调用 工具结果各一条记录最终回答claw_core_persist_context_final_if_configured此调用会标记轮次完成可能触发压缩真正的落盘逻辑在 claw_memory_session.c 中它采用了类似 SQLite 的数据文件 索引文件双文件结构session_id ← 数据文件每行一条 JSON 记录 session_id.idx ← 索引文件8 字节文件头 10 字节/条的定长索引索引文件头携带魔数0x58444843CHDX和版本号每条索引只包含 4 个字段——偏移量、长度、记录类型、后端格式全部打包packed成 10 字节。这种设计让系统无需解析整份历史就能通过偏移量随机定位任意一条记录读取成本极低。每条记录有四种类型USER用户消息、ASSISTANT_FINAL最终回答、ASSISTANT_TOOL工具调用、TOOL_RESULT工具结果。写入时系统会把消息截断到max_message_chars默认 4096 字符并做 UTF-8 边界保护确保不会在存储中留下半截汉字。更值得注意的是容错设计如果数据文件和索引文件不成对只有一个存在或索引损坏系统不会崩溃而是记录警告后自动重建文件对session_history_recreate_file保证会话历史永远可读。会话压缩150KB 阈值下的轮次瘦身算法对话越久历史文件越大。ESP-Claw 设定了150KBCLAW_MEMORY_SESSION_SIZE_LIMIT的会话上限一旦某轮对话结束后文件超限就会触发压缩流程session_history_compact_if_needed算法分为三步第一步轮次切分。系统扫描索引以每条USER记录作为分界点把历史切成若干轮次turn并标记每轮是否完成是否含ASSISTANT_FINAL以及是否含工具记录。第二步保留策略。压缩规则非常克制——只保留三类内容所有USER消息和ASSISTANT_FINAL最终回答对话主干最近1 个已完成的工具轮次的全部工具记录CLAW_MEMORY_SESSION_COMPACT_TOOL_TURNS 1保留少量工具细节供模型参考尚未完成的最后一轮的全部记录避免删掉进行中的上下文。其余旧的工具调用和工具结果记录全部丢弃——它们通常占历史体积的大头但对后续对话价值最低。第三步原地重写。系统按保留清单把记录重新打包写入文件头部用ftruncate截断两个文件索引偏移量全部重建。整个过程是原子的——先验证新大小不超限再落盘最后刷新文件。如果压缩后仍超过 150KB比如用户消息本身就极长系统会写入一个.blocked标记文件并主动向用户推送提示请发送/session new开启新会话用/session delete删除旧会话。这种优雅降级避免了在存储边缘反复写入造成的 Flash 磨损。长期记忆异步 LLM 自动提取 语义去重会话历史是短期记忆而跨会话的长期记忆由 claw_memory.c 和 claw_memory_extract.c 共同维护。最亮眼的设计是异步自动提取请求开始 ──→ 创建提取任务入队 ──→ 独立工作线程调用 LLM ↓ 阶段笔记回调等待任务完成把提取结果合并进上下文系统初始化一个名为claw_mem_extract的独立 FreeRTOS 任务6KB 栈、优先级 5、队列长度 4它持有独立的 LLM 运行时。每当一次请求开始就复制一份用户文本生成任务放入队列工作线程用一套精心设计的系统提示词位于claw_memory_auto_extract_prepare_with_runtime让 LLM 从用户消息中只提取持久性的用户事实返回{intent: none|forget|replace, memories: [...]}的 JSON。这套提示词里有很多防呆规则比如用户说忘了我刚才说的→intentforget不存任何记忆用户在纠正一个旧事实 →intentreplace只存修正后的事实涉及 Agent 人设、语气、角色扮演的指令 → 一律不存那属于画像记忆归soul.md管提问、请求、闲聊 → 不提取每次最多提取 3 条记忆且关键词必须能在原文中找到出处grounding防止 LLM 编造。提取出的记忆进入存储前还要过语义去重关系统把记忆内容规范化后取前 36 字符作为指纹claw_memory_build_item_key完全相同直接跳过若两条记忆互为子串且都超过 12 字符也判定为重复。这样我不吃辣和我讨厌吃辣的不会在 Flash 里各占一条。每条记忆在 Flash 上的落地包含四个文件定义于 claw_memory_internal.h文件作用MEMORY.md人类可读的记忆清单按访问热度排序memory_records.jsonl追加式记录日志每次变更一行memory_index.json摘要标签目录 关键词倒排索引memory_digest.log变更摘要日志store/recall/forget 审计长期记忆注入上下文时只注入摘要标签目录claw_memory_long_term_provider而不是记忆全文——提示词会明确要求模型需要细节时再调用memory_recall工具按标签精确检索。这种目录 按需检索模式把系统提示词的 token 消耗压到了最低非常适合小模型。会话与长期记忆如何协同工作一次完整请求的记忆流转如下示意请求开始会话历史提供者claw_memory_session_history_provider带REQUEST_START_ONLY标志把磁盘上的历史重新载入为消息数组画像提供者注入user.md/soul.md/identity.md长期记忆提供者注入标签目录。请求处理模型基于完整上下文回答可能触发工具调用。轮次结束核心引擎持久化本条最终回答持久化回调检查文件是否超 150KB超限则执行会话压缩。后台并行异步提取线程在后台分析用户消息提取到的长期记忆在下一次阶段笔记回调时合并注入。画像记忆claw_memory_profile.c则是最简单的三份 Markdown设计soul.mdAgent 灵魂/价值观、identity.md身份卡片、user.md用户画像每次请求原样拼接进系统提示词。关键参数速查这些宏定义集中在 claw_memory_internal.h 顶部决定了记忆管理器的行为边界调优时值得关注参数默认值含义CLAW_MEMORY_SESSION_SIZE_LIMIT150 KB会话历史上限超过触发压缩CLAW_MEMORY_SESSION_COMPACT_TOOL_TURNS1压缩时保留的最近工具轮次数CLAW_MEMORY_MAX_ACTIVE_ITEMS128长期记忆最大活跃条目数超出按热度淘汰CLAW_MEMORY_MAX_SUMMARIES3每条记忆最多挂 3 个摘要标签CLAW_MEMORY_AUTO_EXTRACT_MAX_ITEMS3单次自动提取最多落盘 3 条记忆CLAW_MEMORY_RECALL_DEFAULT_LIMIT8memory_recall默认返回条数当活跃记忆超过 128 条时claw_memory_trim_to_capacity会按容量分访问次数 × 3 更新时间的每小时增量淘汰得分最低的记忆——常用且新的记忆得以存活这正是嵌入式版的记忆遗忘曲线。源码导读路径如果你想动手阅读或修改建议按以下顺序接口总览claw_memory.h —— 全部公开 API 与四个上下文提供者的声明会话持久化与压缩claw_memory_session.c —— 重点看session_history_analyze_turns和session_history_rewrite_compacted长期记忆读写claw_memory.c 与 claw_memory_storage.c异步提取claw_memory_extract.c系统提示词与 claw_memory_session.c 开头的任务/队列代码核心侧持久化入口claw_core_context_persist.c小结ESP-Claw 的记忆管理器用不到几 KB 的常驻内存在 ESP32 上实现了完整的对话不失忆能力双文件索引让历史读写高效150KB 轮次压缩让会话可以无限延长异步 LLM 提取 语义去重让长期记忆自动积累又不膨胀目录式注入 按需检索让 token 预算花在刀刃上。这套设计对任何想在资源受限设备甚至边缘服务器上构建有记忆 AI 智能体的开发者都是一份值得借鉴的完整方案。【免费下载链接】esp-clawESP-Claw, a Chat Coding AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-claw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP-Claw 记忆管理器深潜：上下文持久化与会话压缩的实现原理
ESP-Claw 记忆管理器深潜上下文持久化与会话压缩的实现原理【免费下载链接】esp-clawESP-Claw, a Chat Coding AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-claw在资源受限的 ESP32 芯片上运行 AI 智能体最大的挑战之一是如何让设备记住对话。开源项目ESP-Claw一款面向 IoT 设备的Chat Coding AI 智能体框架内置了完整的记忆管理器Memory Manager它解决了两个核心问题上下文持久化——把每一轮对话安全地写入 Flash 存储以及会话压缩——在存储空间耗尽前自动瘦身历史让智能体能无限对话而不撑爆内存。这篇文章将带你逐层拆解 ESP-Claw 记忆管理器的四层架构、会话压缩算法和异步记忆提取机制即使你只熟悉 C 语言基础也能看懂这套精巧的嵌入式记忆设计。为什么嵌入式 AI 代理需要专门的记忆管理器云端大模型服务通常把对话历史放在内存里但 ESP32 只有几十 KB 到几 MB 的 RAM 和有限的 Flash 写入寿命。ESP-Claw 的记忆管理器代码位于 components/claw_modules/claw_memory/因此设计了四套互补的记忆分别应对不同尺度的记忆需求记忆层级存储介质生命周期典型内容会话历史数据文件 二进制索引单次会话完整的用户/助手消息流长期记忆JSONL 记录 索引跨会话永久用户偏好、持久事实画像记忆Markdown 文件永久Agent 人设与用户画像摘要标签JSON 索引随长期记忆可检索的记忆标签目录上下文持久化数据文件 二进制索引的双文件设计会话历史是整个系统的地基。每当核心引擎完成一轮对话就会通过 claw_core_context_persist.c 中的三个入口把消息交给记忆层用户消息claw_core_persist_context_user_messages_if_configured工具调用轮claw_core_persist_context_tool_round_if_configured助手工具调用 工具结果各一条记录最终回答claw_core_persist_context_final_if_configured此调用会标记轮次完成可能触发压缩真正的落盘逻辑在 claw_memory_session.c 中它采用了类似 SQLite 的数据文件 索引文件双文件结构session_id ← 数据文件每行一条 JSON 记录 session_id.idx ← 索引文件8 字节文件头 10 字节/条的定长索引索引文件头携带魔数0x58444843CHDX和版本号每条索引只包含 4 个字段——偏移量、长度、记录类型、后端格式全部打包packed成 10 字节。这种设计让系统无需解析整份历史就能通过偏移量随机定位任意一条记录读取成本极低。每条记录有四种类型USER用户消息、ASSISTANT_FINAL最终回答、ASSISTANT_TOOL工具调用、TOOL_RESULT工具结果。写入时系统会把消息截断到max_message_chars默认 4096 字符并做 UTF-8 边界保护确保不会在存储中留下半截汉字。更值得注意的是容错设计如果数据文件和索引文件不成对只有一个存在或索引损坏系统不会崩溃而是记录警告后自动重建文件对session_history_recreate_file保证会话历史永远可读。会话压缩150KB 阈值下的轮次瘦身算法对话越久历史文件越大。ESP-Claw 设定了150KBCLAW_MEMORY_SESSION_SIZE_LIMIT的会话上限一旦某轮对话结束后文件超限就会触发压缩流程session_history_compact_if_needed算法分为三步第一步轮次切分。系统扫描索引以每条USER记录作为分界点把历史切成若干轮次turn并标记每轮是否完成是否含ASSISTANT_FINAL以及是否含工具记录。第二步保留策略。压缩规则非常克制——只保留三类内容所有USER消息和ASSISTANT_FINAL最终回答对话主干最近1 个已完成的工具轮次的全部工具记录CLAW_MEMORY_SESSION_COMPACT_TOOL_TURNS 1保留少量工具细节供模型参考尚未完成的最后一轮的全部记录避免删掉进行中的上下文。其余旧的工具调用和工具结果记录全部丢弃——它们通常占历史体积的大头但对后续对话价值最低。第三步原地重写。系统按保留清单把记录重新打包写入文件头部用ftruncate截断两个文件索引偏移量全部重建。整个过程是原子的——先验证新大小不超限再落盘最后刷新文件。如果压缩后仍超过 150KB比如用户消息本身就极长系统会写入一个.blocked标记文件并主动向用户推送提示请发送/session new开启新会话用/session delete删除旧会话。这种优雅降级避免了在存储边缘反复写入造成的 Flash 磨损。长期记忆异步 LLM 自动提取 语义去重会话历史是短期记忆而跨会话的长期记忆由 claw_memory.c 和 claw_memory_extract.c 共同维护。最亮眼的设计是异步自动提取请求开始 ──→ 创建提取任务入队 ──→ 独立工作线程调用 LLM ↓ 阶段笔记回调等待任务完成把提取结果合并进上下文系统初始化一个名为claw_mem_extract的独立 FreeRTOS 任务6KB 栈、优先级 5、队列长度 4它持有独立的 LLM 运行时。每当一次请求开始就复制一份用户文本生成任务放入队列工作线程用一套精心设计的系统提示词位于claw_memory_auto_extract_prepare_with_runtime让 LLM 从用户消息中只提取持久性的用户事实返回{intent: none|forget|replace, memories: [...]}的 JSON。这套提示词里有很多防呆规则比如用户说忘了我刚才说的→intentforget不存任何记忆用户在纠正一个旧事实 →intentreplace只存修正后的事实涉及 Agent 人设、语气、角色扮演的指令 → 一律不存那属于画像记忆归soul.md管提问、请求、闲聊 → 不提取每次最多提取 3 条记忆且关键词必须能在原文中找到出处grounding防止 LLM 编造。提取出的记忆进入存储前还要过语义去重关系统把记忆内容规范化后取前 36 字符作为指纹claw_memory_build_item_key完全相同直接跳过若两条记忆互为子串且都超过 12 字符也判定为重复。这样我不吃辣和我讨厌吃辣的不会在 Flash 里各占一条。每条记忆在 Flash 上的落地包含四个文件定义于 claw_memory_internal.h文件作用MEMORY.md人类可读的记忆清单按访问热度排序memory_records.jsonl追加式记录日志每次变更一行memory_index.json摘要标签目录 关键词倒排索引memory_digest.log变更摘要日志store/recall/forget 审计长期记忆注入上下文时只注入摘要标签目录claw_memory_long_term_provider而不是记忆全文——提示词会明确要求模型需要细节时再调用memory_recall工具按标签精确检索。这种目录 按需检索模式把系统提示词的 token 消耗压到了最低非常适合小模型。会话与长期记忆如何协同工作一次完整请求的记忆流转如下示意请求开始会话历史提供者claw_memory_session_history_provider带REQUEST_START_ONLY标志把磁盘上的历史重新载入为消息数组画像提供者注入user.md/soul.md/identity.md长期记忆提供者注入标签目录。请求处理模型基于完整上下文回答可能触发工具调用。轮次结束核心引擎持久化本条最终回答持久化回调检查文件是否超 150KB超限则执行会话压缩。后台并行异步提取线程在后台分析用户消息提取到的长期记忆在下一次阶段笔记回调时合并注入。画像记忆claw_memory_profile.c则是最简单的三份 Markdown设计soul.mdAgent 灵魂/价值观、identity.md身份卡片、user.md用户画像每次请求原样拼接进系统提示词。关键参数速查这些宏定义集中在 claw_memory_internal.h 顶部决定了记忆管理器的行为边界调优时值得关注参数默认值含义CLAW_MEMORY_SESSION_SIZE_LIMIT150 KB会话历史上限超过触发压缩CLAW_MEMORY_SESSION_COMPACT_TOOL_TURNS1压缩时保留的最近工具轮次数CLAW_MEMORY_MAX_ACTIVE_ITEMS128长期记忆最大活跃条目数超出按热度淘汰CLAW_MEMORY_MAX_SUMMARIES3每条记忆最多挂 3 个摘要标签CLAW_MEMORY_AUTO_EXTRACT_MAX_ITEMS3单次自动提取最多落盘 3 条记忆CLAW_MEMORY_RECALL_DEFAULT_LIMIT8memory_recall默认返回条数当活跃记忆超过 128 条时claw_memory_trim_to_capacity会按容量分访问次数 × 3 更新时间的每小时增量淘汰得分最低的记忆——常用且新的记忆得以存活这正是嵌入式版的记忆遗忘曲线。源码导读路径如果你想动手阅读或修改建议按以下顺序接口总览claw_memory.h —— 全部公开 API 与四个上下文提供者的声明会话持久化与压缩claw_memory_session.c —— 重点看session_history_analyze_turns和session_history_rewrite_compacted长期记忆读写claw_memory.c 与 claw_memory_storage.c异步提取claw_memory_extract.c系统提示词与 claw_memory_session.c 开头的任务/队列代码核心侧持久化入口claw_core_context_persist.c小结ESP-Claw 的记忆管理器用不到几 KB 的常驻内存在 ESP32 上实现了完整的对话不失忆能力双文件索引让历史读写高效150KB 轮次压缩让会话可以无限延长异步 LLM 提取 语义去重让长期记忆自动积累又不膨胀目录式注入 按需检索让 token 预算花在刀刃上。这套设计对任何想在资源受限设备甚至边缘服务器上构建有记忆 AI 智能体的开发者都是一份值得借鉴的完整方案。【免费下载链接】esp-clawESP-Claw, a Chat Coding AI agent framework for IoT devices项目地址: https://gitcode.com/gh_mirrors/es/esp-claw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考