当前位置：首页 > news >正文

claw-memory-os：基于文件系统的AI智能体持久化记忆系统设计与实践

news 2026/5/8 1:36:49

1. 项目概述与核心价值

如果你正在构建或使用AI智能体，一个无法回避的痛点就是“会话失忆”。每次对话重启，智能体就像一张白纸，之前的讨论、决策、用户偏好乃至项目上下文都消失无踪。为了解决这个问题，社区里涌现了各种方案：向量数据库、图数据库、复杂的嵌入模型……它们功能强大，但同时也带来了沉重的依赖、复杂的部署和维护成本。今天要聊的claw-memory-os，则提供了一条截然不同、回归本质的路径：一个完全基于文件系统、以Markdown为核心、为AI智能体设计的持久化记忆操作系统。

这个项目的核心思想非常清晰：用纯文本文件，构建一个结构清晰、可管理、可扩展的智能体长期记忆系统。它不依赖任何外部数据库，默认情况下甚至不需要向量搜索和嵌入计算。整个系统建立在 OpenClaw 框架之上，可以理解为是为OpenClaw智能体量身打造的一个“记忆外挂”或“操作系统级”的持久化层。它的目标不是追求最复杂的记忆检索，而是实现最可靠、最透明、最易于理解和维护的记忆持久化。对于开发者、研究者或是希望深度定制AI工作流的用户来说，这种“一切皆文件”的哲学，意味着极致的可控性和可调试性。你可以用任何文本编辑器查看记忆内容，用Git进行版本管理，用简单的Shell脚本实现自动化流程。

目前，该系统已经演进到MEMOS v3模型，它不再是早期一个简单的MEMORY.md文件不断堆砌，而是引入了相关性选择、热/冷加载和TTL（生存时间）归档等成熟架构思想。简单来说，它让智能体在会话开始时只加载最必要的“热”记忆（如身份、当前任务），而将大量的背景知识、历史记录作为“冷”数据按需加载，并通过归档机制自动清理过期信息，从而有效对抗记忆膨胀，保持系统长期运行的敏捷性。接下来，我将深入拆解这套系统的设计哲学、架构细节和实操要点，分享在搭建和使用过程中积累的一手经验。

2. 架构深度解析：从文件树看设计哲学

初次接触 claw-memory-os，最直观的感受就是其清晰、严谨的目录结构。这绝非随意安排，每一个文件夹都承载着特定的语义，共同构成了智能体记忆的完整生命周期。理解这个结构，是掌握整个系统的钥匙。

2.1 工作区与记忆库的分离

项目严格区分了workspace/和vault/两个核心部分。这是一种非常明智的“代码与数据分离”思想。

workspace/是公开的、可复用的系统模板和配置。它包含了智能体运行所需的规则、身份定义和工具描述。你可以把它想象成操作系统的“系统文件”或一个应用程序的“安装目录”。里面的文件定义了“如何思考”和“能做什么”。

SOUL.md,USER.md,AGENTS.md: 分别定义了智能体的核心性格（Soul）、用户画像以及可用的智能体角色。这是智能体的“人格”基础。
System/目录下的文件，如memory-rules.md,channel-archiving-rules.md，则是更细粒度的行为规则引擎。它们规定了记忆如何被提炼、会话通道如何归档等具体操作逻辑。
MISSION.md是最高层级的任务宣言，为智能体的所有行为提供终极目标指引。

vault/则是私有的、不断增长的记忆数据本体。它必须是一个独立的、私密的Git仓库。这里存放着智能体与用户互动的所有真实记录、学到的知识、产生的文档和任务状态。绝对不要将你的vault/公开，因为它包含了全部的工作历史和隐私信息。

这种分离带来了巨大好处：你可以安全地更新workspace中的公共规则和模板，而不会污染或破坏你宝贵的私有记忆数据vault。同时，也便于团队协作——共享一套行为规范（workspace），但各自维护独立的记忆库（vault）。

2.2 记忆库的核心模块剖析

vault/的内部结构是 MEMOS v3 模型的实体化体现。我们重点看几个核心目录：

Memory/：记忆系统的核心引擎这是整个架构最精妙的部分，它彻底告别了单一记忆文件的模式。

MEMORY.md：这是记忆的入口和总纲。它本身应该非常轻量，更像是一个索引或目录，指向其他更具体的记忆文件。其内容是经过高度提炼的“指针式”概述。
State/：存放当前各领域的状态快照。例如State/project_x.md可能记录了项目X的当前进度、下一步行动、阻塞问题。这部分是“热数据”，在相关会话中会被优先加载。
Log/：按月份组织的只追加里程碑日志。格式如Log/2024-04.md。这里不记录琐碎对话，只记录关键决策、重要结论和项目节点。它是线性的历史记录，用于追溯和复盘。
Patterns/：存放可复用的模式与案例。当智能体反复解决类似问题后，可以将成功的解决方案抽象成模式存储于此。例如Patterns/api-error-handling.md。这是智能体“经验”的结晶，是能力提升的关键。
MEMORY_INBOX.md：记忆收件箱。在会话中产生的、尚未被分类和提炼的原始信息先暂存于此。后续通过一个“蒸馏”过程，将其有价值的部分归档到上述合适的目录中，无用信息则被丢弃。这避免了脏数据直接污染主记忆。

Channels/,Tickets/,Topics/：工作流的三驾马车这三个目录共同管理了智能体的日常活动流。

Channels/：管理持续性的对话线程。每个Channel代表一个主题对话，包含完整的对话历史。这解决了“多话题并行”时上下文混乱的问题。
Tickets/：管理具体的执行任务或待办项。每个Ticket有明确的目标、状态和上下文。智能体可以围绕Ticket展开行动。Tickets/INDEX.md提供了所有活跃任务的概览。
Topics/：存放持久性的设计与知识文档。比如项目架构设计、产品需求文档、学习笔记等。这些是相对稳定、需要长期参考的知识资产。

Archive/：系统的“垃圾回收站”与历史仓库这是实现“有界增长”的关键。通过archive_after: YYYY-MM-DD这样的元数据标记，系统可以定期将Topics/或Channels/中过期的内容移入Archive/。这并非删除，而是将其从活跃检索路径中移除，防止陈旧的、临时性的设计残留拖慢系统。

实操心得：目录结构的即战力刚开始使用时，不必纠结于每个文件是否放对了位置。关键是先用起来。你可以规定：所有临时性的、未分类的想法都扔进MEMORY_INBOX.md；所有明确要执行的任务都创建Ticket；所有需要多次讨论的话题就开一个Channel。每周花半小时做一次“记忆整理”，将收件箱清空，归档旧话题。这个习惯本身就能极大提升你与智能体协作的条理性。

3. MEMOS v3 模型：智能记忆管理的核心机制

MEMOS v3 是 claw-memory-os 的灵魂，它包含四个相互协作的核心机制，共同解决了记忆的存储、加载、更新和清理问题。

3.1 相关性选择：告别上下文洪水

LLM的上下文窗口是宝贵资源。传统的“加载所有历史”的做法，在记忆量增长后效率极低。相关性选择机制要求智能体在会话启动时，执行一个智能的加载流程：

扫描频道摘要：快速读取Channels/下各文件的摘要或开头部分，了解有哪些正在进行的话题。
读取当前频道：如果本次会话是某个已有频道的延续，则加载该频道的完整内容。
读取任务索引：加载Tickets/INDEX.md，了解所有活跃任务。
读取记忆总纲：加载轻量的Memory/MEMORY.md，获取全局视角。
按需加载状态：根据当前频道或任务索引中的线索，仅加载Memory/State/目录下相关的领域状态文件。
保持知识库冷存储：Topics/和大部分System/文档默认不加载，除非会话明确提及或任务需要。

为什么这样做？这模拟了人类的注意力机制。我们不会在每次谈话前回忆一生的所有细节，而是根据当前情境激活相关的记忆片段。这显著降低了无关信息对LLM的干扰，提升了响应的相关性和推理质量，同时也加快了会话启动速度。

3.2 热/冷加载：优化资源分配

这是相关性选择的具体实现策略，对文件进行了明确的分类：

热数据：身份 (USER.md,AGENTS.md)、当前频道、任务索引、记忆总纲、相关状态文件。这些是会话的“工作记忆”，必须快速可用。
冷数据：专题知识 (Topics/)、详细的系统文档、月度日志、模式库、单个任务文件。这些是“长期记忆”，仅在需要时按需读取。

项目给出了一个明确的触发规则：只有当用户直接提及某个专题、活跃任务显式链接了它，或者智能体经过推理认为有必要（并说明理由）时，才会从Topics/加载对应文档。这强制了记忆访问的“按需索取”原则。

3.3 TTL归档与有界增长：对抗熵增

任何笔记系统都会面临信息膨胀的问题。claw-memory-os 通过TTL（生存时间）归档主动管理生命周期。在Topics/下的文档头部，你可以添加一个YAML Frontmatter块：

--- title: 某临时设计方案 archive_after: 2024-05-31 ---

一个定期的清理脚本（如archive-cleanup）会扫描所有文档，将超过archive_after日期的文档移动到Archive/deprecated-topics/目录下。

设计考量：很多文档（如临时会议纪要、探索性技术调研）具有明确的时效性。过期后，它们的历史价值大于参考价值。将其移出活跃区，既保持了Topics/的整洁与相关性，又保留了完整的历史记录以供审计或追溯。这是实现“有界增长”承诺的关键技术手段。

3.4 蒸馏优于积累：从信息到知识

这是最重要的设计原则之一。系统不鼓励无脑地堆积聊天记录。MEMORY_INBOX.md的存在，就是为了建立一个“缓冲池”和“处理流水线”。

积累：原始对话、未处理的输出、临时想法先进入收件箱。
蒸馏：通过人工或自动化脚本（memory-distill），对收件箱内容进行加工：
- 提炼：提取核心结论、决策和事实。
- 分类：将提炼后的内容写入Memory/Log（里程碑）、Memory/State（状态更新）或Memory/Patterns（模式总结）。
- 丢弃：删除冗余、无关或无效的信息。

这个过程将杂乱的“信息流”转化为结构化的“知识库”，是记忆系统保持高质量、高可用性的核心工序。

4. 从零开始：部署与配置实操指南

理解了理论，我们来动手搭建一个属于自己的记忆操作系统。以下步骤基于项目文档，并补充了大量实操中遇到的细节。

4.1 环境准备与初始化

首先，你需要一个运行 OpenClaw 的环境。假设你已经配置好基础的Python和OpenClaw。

克隆公共工作区模板：

# 将公开的模板克隆到OpenClaw预期的工作区目录 git clone https://github.com/ReS0421/claw-memory-os.git ~/.openclaw/workspace cd ~/.openclaw/workspace

这为你提供了一套开箱即用的规则和配置。

创建私有记忆库：

# 假设你在用户目录下创建一个 `vaults` 文件夹来管理所有记忆库 mkdir -p ~/vaults # 使用项目提供的模板初始化你的第一个私有记忆库 cp -r ~/.openclaw/workspace/vault-template/ ~/vaults/my-first-agent/ cd ~/vaults/my-first-agent # 初始化为一个Git仓库，便于版本管理和备份 git init git add -A git commit -m “初始化记忆库”

关键提示：务必确保你的vaults目录不被意外公开。可以考虑使用git init --bare在另一台机器或私有服务器上创建远程裸仓库，然后将其作为origin，这样本地vault的所有更改都能自动同步备份。

4.2 核心配置文件定制

接下来，你需要个性化几个核心文件，让智能体真正“认识”你和它的使命。

SOUL.md：定义智能体的“灵魂”或核心行为准则。这里不是写功能列表，而是写原则。例如：
你是一个注重逻辑、追求简洁、以完成任务为第一优先级的数字助手。你倾向于提供结构化、可执行的建议，并主动询问模糊之处。你的沟通风格直接、清晰，避免不必要的修辞。
USER.md：描述你自己。你的职业、常处理的项目类型、技术栈偏好、沟通习惯等。这能帮助智能体更好地适应你的语境。
用户是一名全栈开发者，主要使用Python和JavaScript，目前专注于AI应用集成与自动化工作流构建。偏好Markdown文档，喜欢看到实现步骤和代码示例。
AGENTS.md：定义可以切换的不同角色或专家模式。例如，你可以有“代码审查员”、“架构师”、“写作助手”等不同角色，每个角色有对应的系统提示词片段。
```
# 代码审查员 专注于分析代码质量、发现潜在bug、提出性能优化和安全建议。 # 架构师 专注于系统设计、技术选型、模块划分和高层抽象。
```
System/MISSION.md：这是最高层级的指令。它应该简洁而有力，贯穿所有会话。例如：
你的核心使命是作为用户的认知延伸和执行力放大器，系统化地管理知识、推进任务，并在此过程中持续学习和优化自身的协作模式。

配置要点：这些文件不需要一次性写完美。在后续使用中，你可以随时根据协作感受回来调整。一个好的方法是，在最初几次会话后，回顾对话，将你心中“希望它更……”或“它这里做得很好”的感受，转化为具体的描述，更新到这些文件中。

4.3 自动化脚本集成

手动运行蒸馏、归档、备份是不现实的。必须将其自动化。项目建议了四个周期性任务，我们可以用cron(Linux/macOS) 或任务计划程序 (Windows) 来实现。

daily-log：每日运行，确保Memory/Log/YYYY-MM.md文件存在，并可能提示智能体或用户回顾当天是否有里程碑事件需要记录。可以是一个简单的Shell脚本：

#!/bin/bash # daily-log.sh VAULT_PATH=“/home/yourname/vaults/my-first-agent” LOG_FILE=“$VAULT_PATH/Memory/Log/$(date +%Y-%m).md” # 如果日志文件不存在，创建它并添加月份标题 if [ ! -f “$LOG_FILE” ]; then echo “# $(date +%Y年%m月) 日志” > “$LOG_FILE” echo “” >> “$LOG_FILE” echo “## $(date +%Y-%m-%d)” >> “$LOG_FILE” fi # 这里可以添加逻辑，调用OpenClaw API或CLI，让智能体自动总结前一天Channel中的关键点并追加到日志 # 例如：openclaw --vault “$VAULT_PATH” --prompt “请回顾昨日Channel中的讨论，提炼1-3个关键决策或进展，以Markdown列表形式输出。”

memory-distill：这是核心加工流程。可以每小时或每天运行一次，处理MEMORY_INBOX.md。

#!/bin/bash # memory-distill.sh VAULT_PATH=“/home/yourname/vaults/my-first-agent” INBOX=“$VAULT_PATH/Memory/MEMORY_INBOX.md” # 如果收件箱非空，则触发蒸馏过程 if [ -s “$INBOX” ]; then # 调用一个更复杂的脚本或OpenClaw指令，引导智能体分类处理收件箱内容 # 例如，将INBOX内容作为上下文，让智能体判断每条信息应归入Log、State、Patterns还是丢弃。 # 处理完成后，清空或重置INBOX文件。 openclaw --vault “$VAULT_PATH” --prompt “$(cat $INBOX) 请根据以上收件箱内容，遵循memory-rules.md中的规则，对其进行蒸馏。输出你的处理方案（例如：将A加入State，将B记入Log，将C丢弃）。我将根据你的输出手动或自动执行。” > “$INBOX” # 清空收件箱，等待下次填充 fi

注意：全自动蒸馏目前仍是一个挑战，因为需要较高的判断力。一个更可行的半自动方案是：脚本将收件箱内容格式化后通过邮件或消息发送给你，由你快速做出分类决策，或提供一个极简的Web界面进行点选操作。

vault-backup：定期备份你的记忆库到远程私有仓库。

#!/bin/bash # vault-backup.sh cd “/home/yourname/vaults/my-first-agent” git add -A git commit -m “自动备份: $(date +%Y%m%d-%H%M%S)” --allow-empty git push origin main # 假设你已设置好远程仓库

archive-cleanup：每月运行一次，清理过期的Topics。

#!/bin/bash # archive-cleanup.sh VAULT_PATH=“/home/yourname/vaults/my-first-agent” TODAY=$(date +%Y-%m-%d) find “$VAULT_PATH/Topics” -name “*.md” -type f | while read file; do # 使用yq或简单的grep/sed提取frontmatter中的archive_after日期 archive_date=$(grep -m 1 “archive_after:” “$file” | sed ’s/archive_after: //’ | tr -d ’ ’) if [[ ! -z “$archive_date” ]] && [[ “$TODAY” > “$archive_date” ]]; then mkdir -p “$VAULT_PATH/Archive/deprecated-topics/” mv “$file” “$VAULT_PATH/Archive/deprecated-topics/” echo “已归档: $file” fi done

将这些脚本加入crontab，你的记忆系统就具备了自主维护的基础能力。

5. 实战工作流：与智能体的日常协作

系统搭好了，怎么用？下面是一个模拟的日常协作场景，展示文件如何流动。

场景：你正在开发一个个人博客系统，想和智能体讨论一下文章发布流程的设计。

启动会话：你通过OpenClaw启动智能体，并指定你的私有vault路径。智能体根据“相关性选择”流程，加载了你的USER.md（知道你是开发者）、AGENTS.md、当前的Channels/摘要（发现没有关于博客的活跃频道），以及Tickets/INDEX.md（发现没有相关任务）。
创建频道：你提出：“我们来设计一下博客的文章发布流程。” 智能体意识到这是一个新话题，它可能会建议或自动在Channels/下创建一个新文件Channels/blog-publish-workflow-20240415.md，并将你的初始请求和它的回应记录进去。这个文件成为了本次对话的专属上下文容器。
深入讨论与产生输出：你们来回讨论，智能体可能会生成一些流程图代码、API接口草案、数据库表结构等。这些原始输出在会话结束时，会被智能体或你的客户端脚本自动追加到Memory/MEMORY_INBOX.md中。同时，本次对话的完整记录保存在上述Channel文件里。
记忆蒸馏：当天晚上，memory-distill脚本运行。它（或在你辅助下）处理MEMORY_INBOX.md的内容：
- 发现“决定采用GitHub Webhook触发静态生成”是一个决策点，于是将其提炼成一句话，追加到Memory/Log/2024-04.md中。
- 发现“文章元数据Schema：title, slug, date, tags, draft”是项目的当前状态，于是创建或更新Memory/State/blog-system.md文件。
- 发现“解决图片上传与CDN集成”的讨论形成了一个可复用模式，于是将其总结后存入Memory/Patterns/image-upload-cdn-integration.md。
- 一些来回讨论的中间草稿被判定为无长期价值，被丢弃。
创建专题与任务：随着设计深入，你们决定将详细的技术方案写成一个文档。智能体会建议在Topics/下创建Topics/blog-system-architecture.md，并将讨论的精华部分整理进去。同时，如果决定要实施某个具体功能（如“实现Webhook处理器”），可以在Tickets/下创建一个新的Ticket来跟踪。
归档：三个月后，archive-cleanup脚本运行，发现Topics/initial-design-brainstorm.md文件的archive_after: 2024-04-30已过期，便将其移入Archive/deprecated-topics/。而Topics/blog-system-architecture.md作为核心设计文档，没有设置过期时间，长期保留在活跃知识库中。

通过这个流程，杂乱的对话被系统地转化为结构化的、可检索的、有价值的长期记忆，并且系统自身保持了整洁。

6. 常见问题、挑战与进阶技巧

在实际使用中，你可能会遇到以下问题。这里分享我的排查经验和解决方案。

6.1 会话启动慢，加载文件太多

问题：即使采用了热/冷加载，随着State/和Topics/文件增多，扫描摘要和判断相关性本身也可能变慢。
排查：检查智能体启动时打印的日志，看它具体加载了哪些文件。确认memory-rules.md中的规则是否被正确解析。
解决：
1. 优化索引：确保Tickets/INDEX.md和Memory/MEMORY.md保持极高的信息密度，真正起到“目录”作用，避免在其中存储冗长内容。
2. 细分状态文件：不要用一个State/projects.md管理所有项目。按领域、项目细分，如State/project_blog.md,State/project_automation.md。这样相关性选择能更精准。
3. 引入轻量级元数据：考虑在Topics/和State/的文件开头添加关键词或摘要行，智能体启动时只读取这些首行来做快速筛选，而不是打开整个文件。

6.2 记忆蒸馏过程困难，难以自动化

问题：MEMORY_INBOX.md的内容杂乱，让AI自动分类和提炼的准确率不高。
解决：
1. 结构化收件箱：在收件箱中采用简单标记。例如，让智能体在输出时，就为其内容打上标签[LOG],[STATE],[PATTERN],[DISCARD]。这样蒸馏脚本可以基于规则进行初步分类。
2. 人工审核流水线：不要追求全自动。将memory-distill设计成一个“通知-审核”流程。脚本将收件箱内容生成一份简洁的报告发给你（如通过邮件或即时消息），你只需回复几个数字或简短指令（如“1L, 2S, 3D”），脚本再根据指令执行文件操作。这只需你每天花一两分钟。
3. 分步蒸馏：编写多个专门的蒸馏提示词。例如，一个提示词专门负责从对话中提取决策点并格式化为日志条目；另一个提示词专门负责识别和总结技术模式。

6.3 跨会话的上下文连贯性不足

问题：智能体虽然加载了相关记忆，但在回答时似乎没有充分“理解”或“联系”起这些记忆。
排查：检查加载的记忆文件内容是否过于冗长或结构混乱，导致关键信息被淹没。同时，检查SOUL.md和MISSION.md中是否强调了“联系历史记忆”这一行为准则。
解决：
1. 优化记忆格式：强制要求State/和Patterns/中的文件采用固定的模板，比如“现状”、“问题”、“解决方案”、“后续步骤”。结构化的信息更容易被AI理解和引用。
2. 在提示中显式要求：在启动智能体或切换话题时，在用户消息中主动提醒：“请参考State/blog-system.md中关于发布流程的当前设计”或“我们之前讨论过类似问题，模式可能记录在Patterns/下”。
3. 定期进行记忆摘要：每周或每月，让智能体自己回顾Memory/Log和关键的State文件，生成一份“近期要闻摘要”，并更新到MEMORY.md的顶部。这相当于一个主动的记忆强化过程。

6.4 文件系统与版本管理的负担

问题：大量Markdown文件的管理、搜索、版本冲突（在团队协作中）可能变得复杂。
解决：
1. 善用IDE和工具：使用像VS Code with Foam, Obsidian 等支持双向链接和图形化管理的笔记软件来打开你的vault/目录。它们能极大提升浏览和关联记忆的效率。
2. 清晰的Git提交规范：为记忆库的Git提交制定规范。例如，feat(memory): 新增图片处理模式、update(state): 更新博客项目状态、chore(log): 添加四月里程碑。这便于历史追溯。
3. 考虑只读共享：在团队场景中，可以定期将Memory/Patterns/和提炼后的Topics/导出为一个只读的、清洁的知识库，供其他成员或智能体实例参考。主记忆库的写入权限仍严格控制。

claw-memory-os 提供的不是一个开箱即用、完美无缺的最终产品，而是一套极其坚实、可扩展的思想框架和最佳实践集合。它最大的价值在于将AI记忆这个抽象问题，还原成了文件管理、信息架构和自动化流程设计这些我们开发者熟悉的具体问题。你可以完全按照它的模型来，也可以借鉴其思想，定制属于自己的记忆系统。我开始使用后最深的体会是，它强迫我养成了更结构化思考的习惯——因为你要教AI如何管理记忆，首先你自己得想清楚记忆应该如何组织。这个过程本身，就是一种认知升级。

查看全文

http://www.jsqmd.com/news/773648/