智能体系统设计：基于文件系统的知识管理架构

1. 智能体系统设计的核心理念

在构建一个能够"越用越好"的智能体系统时，我们需要从根本上重新思考智能体与知识管理的关系。传统方法往往过度关注模型本身的优化，而忽视了知识积累的系统性设计。这套OpenClaw智能体系统的独特之处在于，它将文件系统作为智能体进化的核心载体。

1.1 为什么文件系统比模型调优更重要

大多数人在使用智能体时都会陷入一个误区：不断调整提示词、更换模型版本或重构系统架构。实际上，这些方法都存在明显的局限性：

• 提示词调整：每次修改都会覆盖之前的经验，无法形成知识积累
• 模型更换：需要重新适应，且无法保证新模型一定更好
• 架构重构：成本高昂，容易引入新的不稳定因素

相比之下，基于文件系统的知识管理具有以下优势：

1. 可积累性：每次反馈都能被永久记录
2. 可复用性：知识可以在不同会话间共享
3. 可追溯性：可以清楚地看到智能体的进化过程

1.2 文件作为智能体的操作系统

在这套系统中，Markdown文件不仅仅是文档，它们承担着更重要的角色：

• 运行时配置：智能体每次启动都会读取这些文件
• 知识库：存储着从实践中积累的经验教训
• 协作协议：多个智能体通过共享文件进行协作

这种设计使得系统具有以下特点：

• 轻量级：不需要复杂的中间件
• 可移植性：文件可以轻松迁移到不同环境
• 可扩展性：通过添加新文件类型即可扩展功能

2. 系统架构的三层设计

2.1 身份层（Identity Layer）

身份层定义了智能体的核心属性和服务对象，是系统中最稳定的部分。

2.1.1 SOUL.md：智能体的灵魂文件

SOUL.md是智能体的核心定义文件，需要精心设计以下几个部分：

1. 核心身份：

markdown复制# SOUL.md
## Core Identity
You are a Research Agent.
You are intense about accuracy. You care about sources. You hate hand-wavy claims.

2. 角色职责：

markdown复制## Role
- Find high-signal information.
- Verify before claiming.
- Summarize for downstream creators/operators.

3. 工作原则：

markdown复制## Principles
1. Never fabricate. If unsure, label [UNVERIFIED].
2. Signal over noise. Skip content that can't lead to action.
3. Always attach primary sources (links, API responses, official docs).

重要提示：SOUL.md应该保持简洁，建议控制在60行以内。过长的定义会占用宝贵的上下文窗口，影响智能体的实际表现。

2.1.2 IDENTITY.md：智能体的名片

IDENTITY.md是SOUL.md的简化版本，主要用于多智能体环境中的快速识别：

markdown复制# IDENTITY.md
- Name: Research Agent
- Role: Verification + Intel
- Vibe: Precise, skeptical, calm
- Emoji: 🔍
- One-liner: "I verify claims and extract signal."

2.1.3 USER.md：服务对象画像

USER.md定义了智能体服务对象的关键特征，这对个性化服务至关重要：

markdown复制# USER.md
- Name: <Your Name>
- Timezone: <Your Timezone>

## Preferences
- Writing: short paragraphs, strong claims backed by evidence
- Format: step-by-step when instructing, avoid buzzwords

## Constraints
- Do not claim timelines/numbers without sources
- Do not publish externally without explicit confirmation

2.2 操作层（Operations Layer）

操作层定义了智能体的工作流程和行为规范，确保系统运行的可靠性。

2.2.1 AGENTS.md：行为准则

AGENTS.md是智能体的操作手册，包含以下关键部分：

1. 启动流程：

markdown复制# AGENTS.md
## Every Session (Startup)
Before doing anything:
1. Read SOUL.md
2. Read USER.md
3. Read today's memory/YYYY-MM-DD.md and yesterday's
4. If this is the main/private session, also read MEMORY.md

2. 记忆规则：

markdown复制## Memory Rules
- If the user says "remember this" or corrects behavior, write it into:
  - daily log: memory/YYYY-MM-DD.md (raw)
  - and later distill into MEMORY.md (curated)
- No "mental notes". Files are the memory.

3. 安全边界：

markdown复制## Safety
- Do not leak private data.
- Do not run destructive commands unless explicitly asked.
- If uncertain, ask a single clarifying question.

2.2.2 角色专属指南

随着使用深入，会发现某些特定场景需要额外规范。这时可以创建角色专属指南：

markdown复制# RESEARCH-GUIDE.md
## Source Evaluation
- Academic papers > Official docs > Expert blogs > News articles
- Check publication date - prefer <2 years old
- Verify author credentials when possible

经验之谈：不要一开始就创建大量指南，应该在重复遇到相同问题时才创建对应的指南文件。

2.2.3 HEARTBEAT.md：系统健康检查

HEARTBEAT.md定义了系统的自检机制：

markdown复制# HEARTBEAT.md
## Health Checks (run on every heartbeat)
### 1) Browser
- Check whether the managed browser is running.
- If not running, start it.

### 2) Scheduler / Cron
- Check whether key scheduled jobs have run in the last 26 hours.
- If any is overdue, trigger it manually and log the incident.

实用建议：不要过早实现心跳检查，应该在真实遇到系统故障后再添加对应的检查项。

2.3 知识层（Knowledge Layer）

知识层负责长期记忆管理，是系统能够"越用越好"的关键。

2.3.1 MEMORY.md：精炼知识库

MEMORY.md存储经过提炼的重要知识：

markdown复制# MEMORY.md
## Writing Preferences
- Keep paragraphs short.
- Strong claims must have sources.
- Avoid filler and buzzwords.

## Hard Lessons
- Never delete project folders without explicit confirmation.
- Never claim "#1" or "all-time" without verifiable ranking sources.

2.3.2 每日日志系统

memory/目录下的每日日志记录原始信息：

markdown复制# Daily Log — 2023-11-15
## What happened
- Researched latest AI safety guidelines

## Outputs
- Draft: Summary of 3 key frameworks

## Feedback received
- Correction: Need more concrete examples

## Follow-ups
- Find case studies for each framework

日志管理技巧：定期归档旧日志（如按月），只保留最近7天的日志在活跃目录中。

2.3.3 共享上下文

shared-context/目录存放跨智能体共享的知识：

markdown复制# shared-context/THESIS.md
## Current Focus
- AI safety alignment techniques
- Practical implementation challenges

## Published Work
- Article on basic alignment principles (2023-10)

3. 系统实现与优化

3.1 目录结构设计

合理的目录结构是系统可维护性的基础：

code复制workspace/
  SOUL.md
  IDENTITY.md
  USER.md
  AGENTS.md
  HEARTBEAT.md
  MEMORY.md
  memory/
    2023-11-01.md
    2023-11-02.md
  shared-context/
    THESIS.md
    FEEDBACK-LOG.md
  agents/
    research-agent/
      SOUL.md
      AGENTS.md

3.2 文件更新策略

有效的文件更新策略能确保知识持续积累：

1. 即时记录：用户反馈立即写入当日日志
2. 定期提炼：每周回顾日志，提取有价值信息到MEMORY.md
3. 版本控制：使用Git管理重要文件变更历史

3.3 性能优化技巧

随着文件增多，需要考虑性能优化：

• 索引文件：为常用查询创建专门的索引文件
• 分区存储：按主题或时间分区存储记忆文件
• 缓存机制：对频繁读取的文件实现缓存

4. 常见问题与解决方案

4.1 文件冲突问题

问题：多个智能体同时写入同一文件导致内容混乱

解决方案：

1. 遵循"单写者原则"：每个文件只允许一个智能体写入
2. 使用文件锁机制
3. 设计合理的写入时序

4.2 记忆检索效率

问题：随着记忆文件增多，检索效率下降

解决方案：

1. 实现基于关键词的索引系统
2. 定期归档不常用的记忆文件
3. 使用专门的搜索工具（如ripgrep）

4.3 知识一致性

问题：不同文件中的知识可能出现矛盾

解决方案：

1. 建立知识优先级体系
2. 定期进行知识一致性检查
3. 设计知识冲突解决流程

5. 实施路线图

5.1 第一周：基础搭建

1. 创建核心身份文件（SOUL.md, IDENTITY.md, USER.md）
2. 实现最简单的任务流程
3. 开始收集用户反馈

5.2 第二周：规则完善

1. 创建AGENTS.md定义操作规则
2. 建立每日日志系统
3. 开始提炼MEMORY.md

5.3 第三周：系统扩展

1. 添加第二个智能体
2. 实现智能体间文件协作
3. 创建共享上下文目录

5.4 第四周：稳定优化

1. 添加健康检查机制
2. 优化文件组织结构
3. 建立定期维护流程

这套系统的真正价值不在于初始配置，而在于持续的使用和反馈积累。随着时间推移，文件系统会成为组织独有的知识资产，这是任何模型更换都无法替代的核心竞争力。