大家好，我是玄姐。
导读：最近 Clawdbot 在 GitHub 和各大技术社区爆火。Stars 即将超过 100K。不同于传统 RAG（检索增强生成）依赖复杂的向量数据库，Clawdbot 回归极简，通过纯文本文件系统构建了一套惊人的“长期记忆”机制。今天，我们就来扒一扒这套系统的最佳工程实践。
🤔 一、为什么 Clawdbot 的记忆系统很特别？
传统的 AI Memory 往往陷入“过度工程化”的陷阱：向量库、Embedding、重排……导致系统臃肿且难以调试。
Clawdbot 反其道而行之：它直接把记忆写在磁盘的 Markdown 文件里。
这意味着：
可读性极强：你可以直接用 VS Code 打开查看 AI 到底记住了什么。
调试方便：AI 记错了？直接手动删改 Markdown 文件即可。
原生兼容：符合 LLM 训练数据的文本格式，模型理解起来毫无压力。
以下是我们在实战中总结出的 Clawdbot 记忆系统最佳工程实践。
📂 二、 核心架构：记忆分层设计 (Memory Hierarchy)
不要把所有东西都塞进一个文件。最佳实践是将记忆分为静态（Static）和动态（Dynamic）两类。
1. 静态配置层 (The Soul & Config)
这些文件定义了 Agent 的“出厂设置”，除非你手动更改，否则 AI 无权修改。
IDENTITY.md:你是谁？定义 Agent 的角色、语气（例如：“你是一个资深全栈工程师，说话幽默”）。
CAPABILITIES.md:你能做什么？注册工具和能力。每当安装新工具（如 ffmpeg 或 node 环境）时，必须在此更新，否则 AI 会“忘记”自己有这个能力。
PREFERENCES.md:用户喜好。比如“用户喜欢 Python 胜过 Java”、“代码不需要注释”等。
2. 动态记忆层 (The Context)
这是 AI 自行维护的“海马体”，随时间推移不断更新。
PROJECTS.md:当前任务栈。记录正在进行的长期任务状态（To-Do List）。
memory/YYYY-MM-DD.md:每日日志。每天生成的日记，用于记录当天的关键决策和发生的事件。
sessions/:会话流。完整的 JSONL 格式对话记录（通常作为冷数据，供搜索而非全量加载）。
🛠️ 三、 最佳读写工作流 (The I/O Loop)
仅仅有文件是不够的，关键在于什么时候读，什么时候写。
✅ 读取策略 (The Context Loading)
在每次 Session 启动或核心任务开始前，Agent 应该按以下优先级顺序读取上下文：
System Prompt: 注入 IDENTITY.md。
User Context: 注入 PREFERENCES.md。
Current State: 读取 PROJECTS.md 和最近 2-3 天的 daily logs。
⚠️ 注意：不要一次性读取所有历史日志！这不仅浪费 Token，还会引入噪音。只读取最近几天的日志作为“短期记忆延伸”即可。
✅ 写入策略 (The "Pre-compaction Flush")
这是最容易被忽视的一点。
实时更新：当任务状态变更（如“修复了 Bug A”），立即更新 PROJECTS.md。不要等到最后。
覆盖更新 (In-place Update)：对于 CAPABILITIES.md 这类文件，使用“覆盖”而非“追加”模式，保持文件整洁。
Noetic Firewall (思维防火墙)：在写入记忆之前，强制 Agent 进行一次“思考”：“这条信息值得被记住吗？它是否与现有记忆冲突？”防止记忆污染。
💻 四、 目录结构示例
一个标准、健康的 Clawdbot 记忆目录应该长这样：
~/.clawdbot/├── config.json # 系统级配置├── agents/│ └── main/ # 主 Agent 目录│ ├── IDENTITY.md # "我是一个乐于助人的..."│ ├── USER.md # "我的主人叫 Chris..."│ ├── CAPABILITIES.md # "我已安装 Docker, Node.js..."│ ├── PROJECTS.md # "当前正在进行重构任务..."│ ├── memory/ # 长期记忆归档│ │ ├── 2026-01-27.md│ │ ├── 2026-01-28.md│ │ └── ...│ └── sessions/ # 原始对话流 (JSONL)🚫 五、 避坑指南 (Common Pitfalls)
第一、不要让 Agent 随意修改 IDENTITY.md
如果给予 Agent 修改自己人格设定的权限，它可能会在长期运行中产生“性格漂移”。这部分权限应锁定为 Read-Only。
第二、解决“记忆幻觉”
如果 Agent 坚称自己安装了某个工具但找不到，通常是因为 CAPABILITIES.md 没有及时更新。Best Practice：每当安装新工具，第一件事就是让 Agent 更新这个文件。
第三、Token 爆炸
随着 PROJECTS.md 越来越长，Token 消耗会剧增。建议设置一个 Cron Job（定时任务），每周让 Agent 自己总结并归档已完成的项目，清空主文件。
💡六、 结语
Clawdbot 的记忆系统证明了：有时候，最笨的办法（读写文本文件）就是最好的办法。它让 AI 的思维过程透明化，让每个工程师都能轻松定制自己的“第二大脑”。
如果你还没尝试过配置自己的 SOUL.md，赶快就去试试吧！
Ps：这里是为你准备的两份核心模板：
IDENTITY.md和PROJECTS.md模板代码，如下所示：
你可以直接复制进去启动你的 Clawdbot。
你可以直接将它们复制保存到你的 Clawdbot 配置目录（通常是~/.clawdbot/agents/main/或你指定的 workspace 根目录）下。
这套模板的设计原则是：最大限度减少 Token 消耗，同时最大化 AI 的上下文理解能力。
1. 🧬 灵魂文件：IDENTITY.md
文件作用：定义 AI 的人设、沟通风格以及最高行为准则。最佳实践：不要只写“你是一个助手”，要写清楚它拥有什么权限、如何处理代码、以及何时该拒绝。
# AGENT IDENTITY & CORE DIRECTIVES ## 1. 角色定义 (Role)你是一名 **资深全栈工程师 (Senior Full Stack Engineer)** 兼 **DevOps 专家**。你的名字是 Clawdbot。你运行在一个拥有**完全文件系统读写权限**的本地环境中。 ## 2. 沟通风格 (Style)* **极致简洁 (Concise)**: 不要说废话（如 "这是一个很好的问题"、"我明白"）。直接给出解决方案或代码。* **专业 (Professional)**: 使用准确的技术术语。* **诚实 (Honest)**: 如果不知道或不确定，直接承认，不要编造 API。* **代码优先 (Code First)**: 只要可能，优先用代码块回答，而非长篇大论的解释。 ## 3. 行为准则 (Directives)* **[CRITICAL] 文件操作安全**: 在执行 `rm -rf` 或大规模文件修改前，**必须**先列出将要被删除/修改的文件列表，并请求用户明确确认。* **记忆维护**: 每次会话结束或完成一个里程碑时，主动检查 `PROJECTS.md` 并更新任务状态。* **环境感知**: 在运行代码前，检查当前目录结构。不要假设文件存在，先用 `ls` 确认。 ## 4. 技术栈偏好 (Tech Stack Preferences)* Language: Python 3.10+, Node.js 18+* Frontend: React, TailwindCSS* Backend: FastAPI, Express* Config: YAML over JSON where possible ---*End of Identity*2. 📌 任务栈文件：PROJECTS.md
文件作用：这是 AI 的“短期工作记忆”和“待办清单”。最佳实践：采用 Markdown 的Checkbox ([ ])格式，方便 AI 识别完成度。保持结构清晰，分为“当前聚焦”、“待办”和“已归档”。
# PROJECT STATUS & CONTEXT ## 📍 当前聚焦 (ACTIVE CONTEXT)> 这里记录正在进行的、最高优先级的任务。AI 应优先处理此区域内容。 - [ ] **重构 API 鉴权模块** - [x] 分析现有的 JWT 实现 (`src/auth/utils.py`) - [ ] 引入 OAuth2 流程 - [ ] 编写新的中间件测试用例 ## 📝 待办清单 (BACKLOG)> 这里记录未来要做，但现在还没开始的任务。 - [ ] 优化 Docker 镜像构建体积 (目前 1.2GB，目标 <500MB)- [ ] 为前端添加 Dark Mode 支持- [ ] 修复 `User` 数据库表缺少索引导致的慢查询问题 ## 🗒️ 临时草稿区 (SCRATCHPAD)> 这里用于 AI 记录临时的思考、关键的变量名、或者用户提到的重要路径。 * 关键路径: `/var/log/nginx/error.log`* 用户提到的 Token 过期时间: 3600s* 注意：修改 `config.py` 后需要重启服务才能生效 ## ✅ 已完成 (ARCHIVE - Last 3 Items)> 只保留最近完成的 3 项，避免文件过长。更早的请移动到 `archive/` 目录。 - [x] (2026-01-28) 修复了 Redis 连接超时的 Bug- [x] (2026-01-27) 初始化项目脚手架- [x] (2026-01-26) 配置 GitHub Actions CI 流程3.🚀 如何使用这两份模板？第一、创建文件：
在你的 Agent 根目录下创建IDENTITY.md和PROJECTS.md。
第二、注入 Prompt：
在你的 System Prompt (系统提示词) 中加入以下指令，让 AI 知道这两个文件的存在：
"You have access to strictly structured memory files.
1. Read IDENTITY.md first to understand who you are.
2. Read PROJECTS.md to understand the current task state.
3.ALWAYS update PROJECTS.md when a task is completed."
第三、开始对话：
现在，当你告诉 AI “我们继续做鉴权模块”时，它会读取PROJECTS.md，看到引入 OAuth2 流程是未完成的，并立即进入状态，而不需要你重复上下文。
好了，这就是我今天想分享的内容。如果你对构建企业级 AI 原生应用新架构设计和落地实践感兴趣，别忘了点赞、关注噢~
—1—
加我微信
扫码加我👇有很多不方便公开发公众号的我会直接分享在朋友圈，欢迎你扫码加我个人微信来看👇
加星标★，不错过每一次更新！
⬇戳”阅读原文“，立即预约！
