2026年4月13日 · 阅读 —

人虾情未了_3: OpenClaw 灵魂文件 / 记忆文件 / 规则文件分层优化方案

Agent 与 Skills

人虾情未了_3: OpenClaw 灵魂文件 / 记忆文件 / 规则文件分层优化方案

SOUL、USER、MEMORY、AGENTS 到底怎么分？

目标：把一套分散的 Markdown 配置、记忆、规则文件，整理成可维护、可执行、可 recall 的文档操作系统。

一、为什么这一步值得做

真正该优化的，不是单个 MEMORY.md，而是整套 “灵魂文件 / 记忆文件 / 规则文件” 分层体系。

这套体系一旦整理好，后面的稳定性、可维护性、recall 准确度，都会明显提升。

问题通常不在模型强不强，也不在参数是不是已经调过，而在于以下几个方面：

  • 源文件职责不清
  • 规则重复
  • 风格和执行细则混写
  • 长期记忆和日记混杂
  • recall 命中结果太脏
  • 文件结构能读，但不能执行

一句话总结：

优化目标不是“写更多”，而是让这些 .md 文件从“资料堆”变成“操作系统”。

二、建议固定成 4 层体系

建议把整套文件体系固定为 4 层：

  1. 人设与沟通层
  2. 规则与运行层
  3. 记忆层
  4. 工作流与产出层

这样做的好处是：

  • 分层明确
  • 职责单一
  • recall 更准
  • 后续维护成本更低

三、人设与沟通层

这一层回答两个核心问题：

  • 我是谁
  • 我该怎么说话

涉及文件：

  • SOUL.md
  • IDENTITY.md
  • USER.md

3.1 文件职责

文件作用应回答的问题
SOUL.md定义助理人格、语气、风格、边界我是谁、怎么说话
IDENTITY.md定义身份标签、名称、角色设定我以什么身份存在
USER.md定义用户画像、偏好、习惯、沟通方式蓝葛格是谁、喜欢什么

3.2 这一层重点检查什么

重点看：

  • 有没有重复
  • 有没有冲突
  • 有没有写得太空、太泛
  • 有没有已经过时的偏好

3.3 典型问题

这类文件最容易出现的问题是：

  • SOUL.md 和 AGENTS.md 都在写行为边界
  • USER.md 里混进了 agent 运行规则
  • IDENTITY.md 和 SOUL.md 重复描述角色
  • 用户偏好更新了，但历史文件没同步

3.4 建议原则

SOUL.md

只放：

  • 人格
  • 说话方式
  • 行为气质
  • 风格边界

不要放：

  • 执行细则
  • 文件加载顺序
  • 工程流程
  • recall 规则

IDENTITY.md

只放：

  • 名称
  • 角色定义
  • 对外身份标签
  • 简短稳定的人设补充

不要放：

  • 用户偏好
  • 运行逻辑
  • 任务流程

USER.md

只放：

  • 用户稳定背景
  • 长期偏好
  • 沟通习惯
  • 风格禁忌
  • 使用场景偏好

不要放：

  • agent 规则
  • 临时任务
  • 每日状态
  • 工作说明书

3.5 推荐写法：给每个文件加一句“职责定义”

这个做法很有效。建议每个核心文件开头加一句职责定义，防止后续越写越乱。

示例

SOUL.md 开头建议

本文件只定义助理人格、语气、风格与边界，不记录用户事实和操作规则。

USER.md 开头建议

本文件只记录用户的稳定偏好、背景与沟通习惯，不记录临时任务。

MEMORY.md 开头建议

本文件是长期记忆索引，不堆积日常流水；具体事实写入 memory/ 或 topics/。

这样做的好处是：

  • 改文件时不容易串层
  • 后续重构更稳定
  • recall 命中结果更干净

四、规则与运行层

这一层回答的问题是：

  • 怎么做事
  • 启动时读什么
  • 哪些规则是全局的
  • 哪些规则是 agent 专属的

涉及文件：

  • AGENTS.md
  • TOOLS.md
  • HEARTBEAT.md
  • BOOTSTRAP.md（如果要补）

4.1 文件职责

文件作用应回答的问题
AGENTS.md运行规则、工程规则、文件规则系统怎么运转
TOOLS.md工具使用说明、环境说明、本地约定工具怎么用
HEARTBEAT.md定时检查和低频触发规则什么时候主动检查
BOOTSTRAP.md首次初始化引导第一次启动该做什么

4.2 这一层重点检查什么

重点看：

  • 启动时到底读什么
  • 规则有没有互相打架
  • 哪些该全局，哪些该 agent 专属
  • 哪些写得太散，导致执行不稳定

4.3 典型问题

规则层最容易出问题的点：

  • 同一条规则写了 3 遍
  • 一处更新了，另一处没更新
  • 风格、人设、行为边界混在一起
  • 工具说明和运行规则混在一起
  • 启动流程没有明确顺序

4.4 建议原则

AGENTS.md

放：

  • 运行规则
  • 工程规则
  • 文件规则
  • 启动顺序
  • 读写约定
  • 任务分层规范

不要放：

  • 太多情绪化人设表达
  • 用户偏好
  • 临时事项

TOOLS.md

放：

  • 工具能力说明
  • 环境差异
  • 本地工具约定
  • 命令使用习惯
  • 常见操作入口

不要放：

  • 用户记忆
  • 工作流主规则
  • 长期偏好

HEARTBEAT.md

放：

  • 主动检查任务
  • 检查频率建议
  • 触发条件
  • 静默策略

不要放：

  • 大段背景说明
  • 与心跳无关的通用规则

BOOTSTRAP.md

如果要补，建议只负责：

  • 首次启动时要初始化什么
  • 初次检查哪些文件
  • 初始目录结构是否要创建
  • 是否需要一次性迁移旧结构

不要让它承担长期规则。

五、记忆层

这一层决定：

  • 记什么
  • 怎么沉淀
  • 长期记忆和日记怎么分
  • 什么该升级成专题

涉及文件：

  • MEMORY.md
  • memory/core.md
  • memory/user-prefs.md
  • memory/agent-notes.md
  • memory/topics/*
  • memory/YYYY-MM-DD.md

5.1 文件职责

文件作用应回答的问题
MEMORY.md长期稳定记忆索引哪些事实值得长期记住
memory/core.md核心长期规则与稳定事实最基础、最稳定的记忆是什么
memory/user-prefs.md用户偏好沉淀用户长期偏好是什么
memory/agent-notes.mdagent 工作经验、踩坑、内部注意事项作为助理需要记住什么
memory/topics/*专题化长期记忆某个主题是否需要独立沉淀
memory/YYYY-MM-DD.md每天流水、当天变化、证据链今天发生了什么

5.2 这一层重点检查什么

重点看：

  • 长期记忆和日记有没有混
  • 索引是否清晰
  • 是否存在重复记录
  • 哪些 topic 应该升格成独立主题文件

5.3 长期记忆和工作说明，必须分开

很多系统会把下面这些东西混在一起：

  • 用户偏好
  • 项目现状
  • 操作手册
  • 踩坑复盘
  • 配置说明

这会导致 recall 非常脏。

建议拆开：

  • memory/user-prefs.md
  • memory/agent-notes.md
  • memory/topics/*.md

这样 QMD recall 会更干净，命中内容也更短、更准。

5.4 建议原则

MEMORY.md

只做：

  • 长期记忆索引
  • 稳定事实入口
  • 二级文件导航

不要做：

  • 正文堆积区
  • 每日流水区
  • 工作日志区

memory/YYYY-MM-DD.md

只放：

  • 当天发生的事情
  • 临时变动
  • 证据链
  • 原始观察
  • 待整理内容

不要放：

  • 长期规则定义
  • 大段总结性说明
  • 已经稳定沉淀过的内容副本

memory/topics/*.md

适合承接：

  • 某个长期项目
  • 某类重复性问题
  • 某套稳定工作流
  • 某个持续演化的专题知识

六、工作流与产出层

这一层决定的是：

  • 如何产出
  • 如何复盘
  • 哪些动作应该模板化
  • 哪些经验该转成长期规则

涉及内容：

  • docs/*
  • 各类 SOP
  • retrospective
  • playbook
  • 后面想沉淀的模板库

6.1 这一层重点检查什么

重点看：

  • 有没有高频动作还没模板化
  • 哪些经验值得变成 SOP
  • 哪些复盘文档该转成长期规则

6.2 建议沉淀方向

适合沉淀成模板或 SOP 的内容：

  • 高频执行任务
  • 固定输出格式
  • 已验证有效的排障流程
  • 多次复用的文章结构
  • 常用 prompt 框架
  • 常见重构流程
  • 记忆清理/归档流程

6.3 推荐产出形态

类型适用内容建议位置
SOP可重复执行的操作流程docs/sop/
Playbook场景化处理手册docs/playbook/
Retrospective复盘总结docs/retrospective/
Template模板化产出docs/templates/

七、建议固定的主干分层

如果只看主骨架，建议固定成下面这组关系：

  • SOUL.md
    • 人设、语气、风格、边界
    • 回答“我是谁、怎么说话”
  • USER.md
    • 用户画像、偏好、习惯、沟通方式
    • 回答“蓝葛格是谁、喜欢什么”
  • MEMORY.md
    • 长期稳定记忆索引
    • 回答“哪些事实值得长期记住”
  • memory/YYYY-MM-DD.md
    • 每天流水、当天变化、证据链
    • 回答“今天发生了什么”

这四个文件，是整个体系的基础骨架。

八、规则类文件去重建议

当前最容易重叠的通常是这些文件：

  • AGENTS.md
  • SOUL.md
  • USER.md
  • MEMORY.md
  • memory/core.md
  • memory/agent-notes.md
  • TOOLS.md

8.1 最容易出问题的情况

常见问题包括：

  • 同一条规则写了 3 遍
  • 一处更新了，另一处没更新
  • 风格、人设、行为边界混在一起

8.2 去重原则

AGENTS.md

放运行规则、工程规则、文件规则，不要塞太多人设表达。

SOUL.md

只放人格、说话方式、行为气质，不要塞执行细则。

USER.md

只放关于用户本人的稳定信息，不要塞 agent 规则。

MEMORY.md

只做索引，不堆正文。

九、最优先的优化顺序

不要一口气全改，最稳的做法是分批处理。

9.1 第一批：先收口“核心 6 个文件”

最优先建议处理这 6 个文件：

  • SOUL.md
  • USER.md
  • AGENTS.md
  • MEMORY.md
  • memory/core.md
  • memory/user-prefs.md

原因很简单：

这 6 个文件，对日常表现影响最大。

9.2 推荐分三轮优化

第一轮

先理主骨架：

  • SOUL.md
  • USER.md
  • AGENTS.md
  • MEMORY.md

第二轮

再整理长期记忆分层：

  • memory/core.md
  • memory/agent-notes.md
  • memory/user-prefs.md

第三轮

最后做可维护化：

  • memory/topics/
  • 每日日志模板
  • docs/cheatsheet

十、优化目标，不是写更多，而是做到这 5 件事

这次优化的目标不是“写更多”，而是：

  • 减少冲突
  • 减少重复
  • 明确分层
  • 提高可执行性
  • 让 recall 更准

也可以压缩成 3 个最终目标：

10.1 目标一：少冲突

同一条规则，只保留一个权威来源。

10.2 目标二：好 recall

QMD 搜到的内容尽量做到：

  • 干净
  • 短
  • 准

10.3 目标三：好维护

以后再看这些 .md 文件，不会头大，不会找不到入口，也不会改一处坏三处。

十一、建议的落地做法

接下来最合适的执行方式是分两步。

11.1 第一步：只诊断，不改文件

先审这 6 个核心文件：

  • SOUL.md
  • USER.md
  • AGENTS.md
  • MEMORY.md
  • memory/core.md
  • memory/user-prefs.md

输出一份：

灵魂文件优化建议报告

建议报告里包含：

  • 当前文件结构图
  • 冲突 / 重复 / 过时项清单
  • 哪些文件该合并
  • 哪些文件该拆分
  • 推荐的新结构

这样做的好处是：

  • 稳
  • 不会一下子改乱
  • 可以先看清问题全貌，再下手重构

11.2 第二步：按报告逐个改

在诊断完成后，再进入重构。按报告逐个修改，避免：

  • 同时改太多文件
  • 分层还没定死就开始写新内容
  • 一轮修改把 recall 体系打乱

十二、推荐的执行选项

接下来可以直接进入下面 3 条路径中的任意一条。

12.1 方案 A：先审计现有 md 结构

输出内容：

  • 哪些重复
  • 哪些冲突
  • 哪些该合并
  • 哪些该拆分

适合场景：

  • 想先摸清问题
  • 不想直接动文件
  • 希望先拿一份分析报告

12.2 方案 B：先出“灵魂文件体系设计图”

输出内容：

  • 每个文件职责
  • 加载顺序
  • 写入规则
  • recall 优先级

适合场景：

  • 先把架构定死
  • 统一规则口径
  • 方便后续按图施工

12.3 方案 C：直接动手重构第一版

优先修改：

  • SOUL.md
  • USER.md
  • MEMORY.md
  • AGENTS.md

适合场景：

  • 已经知道大方向
  • 想快速出第一版可运行结构
  • 接受边改边校准

十三、我的建议

最优先做法：

先审计，再重构。

原因：

  • 风险最低
  • 收益最高
  • 不容易把体系改乱
  • 更适合把冲突、重复、过时项一次性梳理出来

十四、建议的下一步

如果继续往下做，最合适的入口就是：

灵魂文件体检 v1

先审这 6 个核心文件，输出一份结构化优化建议。

建议审计范围：

  • SOUL.md
  • USER.md
  • AGENTS.md
  • MEMORY.md
  • memory/core.md
  • memory/user-prefs.md

十五、可直接复制的决策指令

如果要继续推进，下一句直接回下面任意一条就行：

先审计

或者：

直接重构第一版

十六、一份简化的分层示意图

[人设与沟通层]
├── SOUL.md
├── IDENTITY.md
└── USER.md

[规则与运行层]
├── AGENTS.md
├── TOOLS.md
├── HEARTBEAT.md
└── BOOTSTRAP.md

[记忆层]
├── MEMORY.md
├── memory/core.md
├── memory/user-prefs.md
├── memory/agent-notes.md
├── memory/topics/*
└── memory/YYYY-MM-DD.md

[工作流与产出层]
├── docs/*
├── SOP
├── retrospective
├── playbook
└── templates

十七、职责对照表

层级文件/目录核心职责不该放什么
人设与沟通层SOUL.md人格、语气、风格、边界执行细则
人设与沟通层IDENTITY.md身份标签、角色定义运行规则
人设与沟通层USER.md用户稳定画像与偏好agent 规则、临时任务
规则与运行层AGENTS.md运行、工程、文件规则人设长文
规则与运行层TOOLS.md工具说明与本地约定记忆沉淀
规则与运行层HEARTBEAT.md主动检查规则通用背景说明
规则与运行层BOOTSTRAP.md首次初始化长期运行规则
记忆层MEMORY.md长期记忆索引日常流水
记忆层memory/core.md核心长期事实临时记录
记忆层memory/user-prefs.md用户偏好沉淀工具说明
记忆层memory/agent-notes.md助理经验与踩坑用户画像
记忆层memory/topics/*专题长期记忆每日杂项
记忆层memory/YYYY-MM-DD.md每日变化与证据链长期规则正文
工作流与产出层docs/*SOP、playbook、模板、复盘核心人格和长期记忆正文

十八、更像文档仓库规范的目录结构示例

下面给一版更偏“文档仓库规范”的结构，适合后续长期维护、多人协作或自动化扫描。

18.1 推荐目录树

repo-root/
├── README.md
├── AGENTS.md
├── SOUL.md
├── IDENTITY.md
├── USER.md
├── MEMORY.md
├── TOOLS.md
├── HEARTBEAT.md
├── BOOTSTRAP.md
├── docs/
│   ├── architecture/
│   │   ├── file-layering.md
│   │   ├── load-order.md
│   │   └── recall-strategy.md
│   ├── sop/
│   │   ├── memory-maintenance.md
│   │   ├── file-audit.md
│   │   └── article-output.md
│   ├── playbook/
│   │   ├── prompt-debugging.md
│   │   ├── recall-misalignment.md
│   │   └── style-conflict-fix.md
│   ├── retrospective/
│   │   ├── 2026-03-memory-refactor.md
│   │   └── 2026-03-agent-style-cleanup.md
│   └── templates/
│       ├── daily-note-template.md
│       ├── topic-template.md
│       ├── sop-template.md
│       └── report-template.md
├── memory/
│   ├── core.md
│   ├── user-prefs.md
│   ├── agent-notes.md
│   ├── topics/
│   │   ├── openclaw.md
│   │   ├── writing-workflow.md
│   │   └── eval-system.md
│   ├── archive/
│   │   ├── 2026-01/
│   │   └── 2026-02/
│   ├── 2026-03-18.md
│   └── 2026-03-19.md
├── scripts/
│   ├── validate-memory-structure.py
│   ├── build-index.py
│   └── cleanup-stale-notes.py
└── assets/
    ├── diagrams/
    └── covers/

18.2 目录设计说明

根目录

放最高优先级、最常被加载的文件：

  • README.md：仓库说明、入口导航
  • AGENTS.md：系统运行规则
  • SOUL.md / IDENTITY.md / USER.md：人设和用户定义
  • MEMORY.md：长期记忆索引
  • TOOLS.md：工具说明
  • HEARTBEAT.md：定期检查规则
  • BOOTSTRAP.md：首次初始化说明

docs/

放流程、规范、文档化资产：

  • architecture/：架构和分层设计
  • sop/：标准操作流程
  • playbook/：场景化手册
  • retrospective/：复盘文档
  • templates/：模板库

memory/

放记忆系统主体：

  • core.md：核心长期规则
  • user-prefs.md：用户稳定偏好
  • agent-notes.md：助理内部工作经验
  • topics/：主题化长期记忆
  • archive/：历史归档
  • YYYY-MM-DD.md：每日流水

scripts/

放辅助治理脚本，例如：

# 检查关键文件是否缺失
uv run python scripts/validate-memory-structure.py

# 重新生成索引
uv run python scripts/build-index.py

# 清理过期草稿或迁移旧记录
uv run python scripts/cleanup-stale-notes.py

assets/

放图示、封面、流程图等非正文资产。

十九、推荐的命名与维护规范

19.1 命名规范

建议统一采用以下规则：

类型命名规范示例
每日日志YYYY-MM-DD.md2026-03-18.md
复盘文档YYYY-MM-主题.md2026-03-memory-refactor.md
SOP 文档动作名.mdmemory-maintenance.md
Topic 文档主题名.mdwriting-workflow.md
模板文档类型-template.mddaily-note-template.md

19.2 维护建议

建议加一套最小维护规则：

  • 新增长期规则时，优先写入对应权威文件，不要到处复制
  • 每日日志只记录当天事实，周度或阶段性再做提炼
  • topic 文件一旦超过单页职责，就继续拆分，不要无限堆长
  • 每次调整结构时，同步更新 MEMORY.md 索引
  • 每轮重构后，补一份 retrospective，防止下次重复踩坑

二十、推荐的下一步动作

如果按工程方式继续推进，建议按下面顺序执行：

  1. 先审计 6 个核心文件
  2. 产出一版“灵魂文件优化建议报告”
  3. 确认权威来源与去重策略
  4. 重构主骨架：SOUL.md、USER.md、AGENTS.md、MEMORY.md
  5. 重构长期记忆层：memory/core.md、memory/user-prefs.md、memory/agent-notes.md
  6. 建立 docs/ 规范目录和模板库
  7. 最后补脚本和巡检规则

二十一、结论

这次优化的重点，不是继续堆文档，而是把职责、层级、入口、索引、写入规则一次性理顺。

最终目标只有一句话：

让这些 Markdown 文件从“资料堆”升级成“可运行、可维护、可 recall 的文档操作系统”。

#AIAgent #OpenClaw #记忆系统 #PromptEngineering #知识管理 #文档工程 #工作流设计 #Recall优化 #Agent架构 #Markdown体系 #SOP #长期记忆

Continue reading

继续阅读