MimiClaw：文件系统重构嵌入式Agentic RAG

核心设计概述

MiniClaw是一款运行在5美元级主控芯片上的轻量化AI助手，全程基于纯C语言开发，无需Linux或Node.js运行环境。用户通过Telegram发送的消息会被ESP32-S3通过WiFi接收，送入智能代理循环：大模型完成思考、调用工具、读取本地记忆，最终将结果回复给用户。这套系统同时兼容Claude和GPT系列模型，可在运行时自由切换，所有数据均存储在本地Flash存储中，无需依赖云端服务。这一设计让完整的AI代理系统得以塞进低成本硬件中，而自主文件读取替代传统RAG检索的思路，正是其核心技术亮点之一。

所谓“LLM自主调用read_file工具替代传统RAG检索”，本质是将检索的决策权从外部基础设施交还给大模型本身：将原本依赖向量数据库的检索基础设施简化为本地文件系统，把“准备上下文”的环节从prompt预处理阶段后移到大型语言模型的推理过程中。这一思路抛弃了传统的embedding、索引构建、重排序等组件，转而依托前沿大模型的语义理解能力完成检索决策，这也是只有在大模型时代才能实现的创新设计。如果没有这一思路，MiniClaw就必须在云端部署全套检索服务，其“纯本地、低功耗、低成本”的产品定位也就无从谈起。

自主文件读取与RAG范式的变革

MiniClaw的核心思路是用大模型自主调用read_file工具替代传统的RAG检索流程。这一设计包含一个鲜明的对照：传统RAG是“系统替大模型决定要读取的内容”，而MiniClaw则反过来，让大模型自己决定需要读取哪些文件。

/* Register read_file */
mimi_tool_t rf = {
    .name = "read_file",
    .description = "Read a file from SPIFFS storage. Path must start with "MIMI_SPIFFS_BASE"/.",
    .input_schema_json = "{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"description\":\"Absolute path starting with \"MIMI_SPIFFS_BASE\"/\"}},\"required\":[\"path\"]}",
    .execute = tool_read_file_execute,
};
register_tool(&rf);

接下来我们将详细分析这一思路的细节、优势与局限。

传统RAG的工作流程

传统的云端RAG流程通常由外部管线主导：用户发起提问后，先通过Embedding模型将问题编码为向量，再在向量数据库中检索Top-K最相似的文本段落，部分流程还会通过重排序模型对结果进行过滤优化，随后将筛选出的段落拼接进入系统提示词或用户消息中，最后大模型基于准备好的上下文生成最终回答。

这种模式下，大模型仅仅是被动的内容消费者：在收到prompt之前，所有需要的上下文都已经被提前准备完毕，检索过程对大模型完全不可见，模型也无法主动对检索结果进行反馈和调整，除非采用更复杂的Agentic-RAG架构。

MiniClaw的自主检索流程

MiniClaw则完全抛弃了这套外部检索管线，取而代之的是一套完全由大模型主导的流程：

用户提问
	↓
LLM看到的system prompt只包含：
	- 静态指令+工具列表
	- 几份“目录页”（MEMORY摘要、Skills标题、文件路径约定）
LLM判断：“要回答这个问题，我需要看x文件“
	↓
LLM主动发起tool_use:read_file（path="/spiffs/skills/weather.md")
	↓
agent_loop 执行 tool，把文件内容作为 tool_result 塞回 messages
	↓
LLM拿到内容，再决定下一步（继续检索/回答/调其他工具）

这一设计的关键反转在于：大模型不再是“被投喂的消费者”，而是“主动伸手获取信息的读者”，检索环节从大模型推理之前的预处理步骤，变成了推理过程中的工具调用环节。

采用这一设计的三大动机

动机一：低成本主控无法运行传统RAG基础设施

传统RAG的依赖项在ESP32-S3这类低成本主控上几乎都无法运行：

因此MiniClaw只能选择放弃传统RAG，要么将服务迁移到云端，要么换一种更轻量化的方案，显然后者更符合其产品定位。

动机二：更好的可解释性与调试性

传统RAG的一大痛点是调试困难：当检索结果不符合预期时，很难定位问题所在——是文本分块过大？Embedding模型不匹配？Top-K参数截断了有效内容？还是重排序模型出现错误？整个调试链路长且复杂。

而在MiniClaw的架构中，每一次“检索”都对应一个清晰可见的tool_use日志，可以通过串口日志直接查看：

[agent] tool_use:read_file(path="/spiffs/memory/MEMORY.md")
[agent] tool_result: 1842 bytes
[agent] tool_use: read_file(path="/spiffs/skills/weather.md")
[agent] tool_result: 612 bytes
[agent] final answer generated

我们可以直接从日志中看到哪个文件被读取、读取到了什么内容、为什么发起读取请求，整个调试过程被简化为对话流程的调试，每一步的检索动作和结果都一目了然。

动机三：大模型已具备“读懂目录页并自主路由”的能力

当前的前沿大模型具备极强的指令遵循能力，可以替代许多原本需要专门管线完成的工作：当给大模型提供一个目录列表，比如“这里有5个技能模块，分别是X、Y、Z...”，大模型可以根据用户的提问自动判断：“用户询问天气相关的问题，我应该读取weather.md文件”，随后发起对应的read_file工具调用。

这本质上是将“检索路由”的职责从传统的Embedding相似度匹配，转交给大模型的语义理解能力。在大模型时代之前，小模型无法理解“目录”这样的隐喻，但如今的前沿大模型已经可以将目录页作为天然的索引。MiniClaw的设计正是信任了这一能力，并将其写入了prompt协议中。

这一思路基于两个核心判断：

判断一：检索与思考的边界正在消融

传统RAG的预设是“检索是廉价的预处理，推理是昂贵的核心计算”，因此需要将检索环节做厚做精，提前准备好正确的上下文喂给大模型。而MiniClaw则反过来预设：大模型的推理能力已经强大到可以将“决定读取什么内容”也纳入推理过程中，因此将检索作为推理的一部分，而非前置的独立步骤。这一趋势在云端也同样存在，比如Claude的Agentic Browsing、GPT的File Search工具，而MiniClaw则因为硬件资源的约束，将这一思路推向了极致。

判断二：自主读取带来体验升级

传统RAG中，大模型被动接收N段文本，无法主动判断“是否还需要更多的信息”，而MiniClaw的模式则允许大模型在读取一份文件后，如果发现信息不足，可以继续发起read_file调用读取第二份文件，这是一个真正的迭代式探索过程。

通过ReAct循环（最多支持10次工具调用），大模型可以完成深度的信息检索：比如当用户问“我上周三跟你说了什么？”，大模型会先调用list_dir工具查看会话目录，发现tg_12345.jsonl文件，读取后发现里面只有20条最近的消息，没有上周三的内容，于是再读取对应日期的记忆文件，最终找到当天的日记并生成回答。这种“查找→查看→决定继续查找→最终回答”的流程，更接近人类查阅资料的习惯，而非“系统直接提供5个段落让我挑选”，在文件数量较少（几十到几百份）的场景下，主动检索的效果优于被动的Top-K检索。

这套设计能够生效的三大支撑机制

仅靠“让大模型自主读取文件”的思路还不足以落地，MiniClaw至少有三个协同机制支撑这一范式：

机制一：上下文始终包含“知识地图”

系统的上下文构建模块会将以下内容始终包含在系统提示词中：可用工具列表（包括read_file、list_dir等探索性工具）、MEMORY.md的内容（让大模型知道已经存储的记忆）、技能模块的目录页（让大模型知道有哪些可用的文件资源），以及统一的文件路径约定（比如/spiffs/memory/、/spiffs/skills/、/spiffs/sessions/）。这些内容共同构成了一份“知识地图”，大模型不需要依赖Embedding模型，就可以通过这份地图知道应该去哪里查找所需的信息。

机制二：纪律性的prompt协议

系统提示词中包含了一系列用自然语言编写的检索时机规则，比如“在写入内容前务必先读取MEMORY.md”、“在编写每日笔记前先获取当前时间”、“当任务匹配某个技能模块时，先读取完整的技能文件获取详细指令”、“在回答用户偏好相关的问题前先读取MEMORY.md”。这些规则替代了传统RAG中的检索触发逻辑，仅通过几行Markdown格式的文本就实现了复杂的检索规则控制，实现成本极低。

机制三：文件系统作为“扁平知识库”

SPIFFS存储中的所有文件均为Markdown或JSONL格式，既可以被人类阅读，也可以被大模型理解和枚举。大模型可以通过list_dir工具发现可用的资源，通过read_file加载特定文件，还可以通过write_file或edit_file工具修改资源。整个文件系统就是一个“模型可寻址的知识库”，不需要额外构建索引：因为文件名、文件标题和第一段内容本身就构成了天然的语义索引，大模型可以通过这些信息判断文件的大致内容。

与Agentic-RAG的对比

熟悉智能代理架构的开发者可能会发现，这其实就是Agentic RAG的一种极简形态，但MiniClaw将其推向了更极致的位置：

因此更准确的描述是，MiniClaw是“将Agentic RAG简化到仅保留文件系统”的极致版本。

这套设计的代价与适用边界

这套设计也存在明显的代价，主要包括以下几点：

因此这套设计的适用边界非常清晰：适合知识库规模较小（小于1000份文件）、文件命名清晰有语义、运行前沿大模型的场景。MiniClaw恰好完美契合这个区间：个人设备上的几十份Markdown文件，搭配顶级的Claude或GPT模型，是非常合适的组合。如果有人尝试将这套架构用于管理十万份企业文档，那么就必须回归传统的RAG方案了。

隐含假设与崩塌场景的应对方案

这套架构依赖六个核心隐含假设，一旦某个假设失效，整个范式就会出现问题，对应的应对方案如下：

场景一：知识库规模超过目录页极限

当文件数量从几十涨到几千时，系统的上下文构建模块无法容纳完整的目录列表，要么截断目录导致大模型看不到部分文件，要么导致系统提示词突破16KB的上下文上限。更隐蔽的问题是，即使提示词可以容纳，大模型在面对上百条目录项时也无法准确找到所需文件，注意力分散导致召回率下降。

对应的补变手段包括： 1. 一级补变：将技能模块按目录分类，只在目录页展示类别而非具体文件 2. 二级补变：引入search_files工具，通过文件名和标题进行关键词匹配，让大模型先搜索再读取 3. 三级补变：将部分检索服务迁移到云端，回到传统RAG方案

场景二：文件名和标题失去语义可识别性

大模型的自主路由依赖文件名可以暗示文件内容，如果文件名是自动生成的UUID、使用内部代号，或者大量同质化的标题，大模型会无法正确判断文件内容，只能乱试或放弃检索。触发这种情况的原因包括系统自动归档机制破坏了语义命名、多语言混杂、专业领域术语过强等。

补变手段包括： 1. 强制要求文件名描述内容 2. 为每个目录添加INDEX.md文件维护目录摘要 3. 要求文件首行必须为人类可读的标题

场景三：使用了不够强大的大模型

如果切换到弱模型，大模型无法稳定完成自主检索。补变手段包括： 1. 缩短ReAct循环的最大调用次数 2. 预加载高频内容到系统提示词中 3. 简化目录页只展示最相关的技能模块 4. 回退到传统RAG方案

场景四：需要实时响应的低延迟场景

“查看目录→读取文件→整合信息→回答”是串行的多轮大模型调用，每一轮都需要数秒到十秒的时间，如果需要读取多个文件，总延迟可能达到30秒，这对于实时控制场景完全无法接受。这类场景包括智能家居语音助手、紧急通知、短回合社交聊天等。

补变手段包括： 1. 添加分级路由，在大模型调用前通过轻量代码识别意图 2. 预热缓存高频文件 3. 异步预读高概率文件 4. 支持流式响应提升用户感知

场景五：多用户或高并发的知识更新场景

当前架构假设单个大模型维护一份记忆，使用read-modify-write的乐观锁机制，如果出现多用户同时对话、心跳任务和用户对话并发的情况，会出现数据覆盖的问题。补变手段包括： 1. 添加文件级锁 2. 按用户分文件存储记忆 3. 使用仅追加的存储模式 4. 将共享状态迁移到云端

场景六：知识为连续大段落而非离散文档

MiniClaw的“文件即知识单元”的假设适合离散的小文档，但对于长文档、长会议转写、法律合同等需要跨节引用的内容，大模型无法通过一次read_file获取所需信息，也没有分块和排序的基础设施来定位具体段落。补变手段包括： 1. 离线预切分长文档 2. 添加按章节读取的工具 3. 为长文档添加目录摘要 4. 回退到传统RAG方案

综合判断：何时需要进行补变？

可以通过一张决策表来判断是否需要进行补变：

总体原则是先观察失败模式，不要预防性地引入复杂组件，MiniClaw的“零RAG基础设施”在90%的个人场景中都足够好用，过早引入向量存储会破坏其低成本纯本地的产品定位。

元层面的崩塌：架构的时代依赖性

MiniClaw的整个上下文工程哲学，本质是押注前沿大模型的能力会持续增强、价格会持续下降。如果未来出现前沿模型价格上涨、模型能力被监管限制、隐私法规要求完全本地化等情况，那么“用大模型智能替换基础设施复杂度”的权衡就会被打破，整个架构的根基会被动摇，届时MiniClaw可能需要切换到纯本地小模型加传统RAG的方案，那将是另一个完全不同的产品。

这也提醒我们，任何AI代理架构都是和当下的大模型生态绑定的工程权衡，没有永恒正确的方案，MiniClaw的优雅之处正在于它清醒地接受了这种时代依赖，成为特定时期LLM生态下的最优近似解。

参考资料

本文相关的参考内容包括Transformer架构相关的基础理论，以及智能代理与检索增强生成的前沿研究。