金字塔记忆架构(Pyramid Memory Architecture)#

本 Skill 提供一套标准化的 Agent 记忆分层架构,适用于任何新建子 Agent 工作区。 核心理念: 规则按触发优先级分层存放,引导只能从上往下,下层不引导回上层。 版本: v3.6 - Cron任务按复杂度分级:简单任务用锚点引导,复杂任务直写进cron payload,彻底解决隔离会话引导断裂问题

📐 架构总览#

text

         ▲
        / \
       /   \
      / AGENTS.md \    ← 顶层:系统注入,铁律级行为规则(每次必加载)
     /-----------\
    / MEMORY.md   \    ← 中层:主会话加载,业务规则、触发器、长期记忆
   /---------------\
  /  SOUL.md 等      \  ← 中层:人格配置、心跳清单、身份信息
 /---------------------\
/  self-improving/     \ ← 按需读取:执行经验、错误纠正、领域教训
/-----------------------\
\   SKILL.md/TOOLS.md   / ← 底层:按需读取,技术实现细节、操作流程

各层定位#

层级文件加载方式内容定位顶层AGENTS.md系统级注入,每次必加载铁律级行为规则、安全红线、引导表中层MEMORY.md主会话系统注入业务触发规则、长期记忆、项目规则中层SOUL.md系统级注入人格、身份、使命、行为准则中层HEARTBEAT.mdcron触发时通过锚点引导加载待办提醒、报告队列、周期性检查清单中层IDENTITY.md系统级注入Agent 身份卡片(名字、形象、表情)中层USER.md系统级注入主人信息、作息、偏好中层TOOLS.md系统级注入本地配置笔记(设备、端口、Cookie)按需读取self-improving/任务前主动读取执行经验、错误纠正、领域教训(memory.md / domains/ / projects/ / corrections.md)底层SKILL.md匹配场景时读取技术实现、操作流程、选择器、正则底层docs/*.md按需读取详细操作文档、临时任务规则等

📝 规则录入铁律#

录入原则#

1. 按触发优先级引导:

   • 系统注入文件(AGENTS/SOUL/MEMORY/TOOLS/IDENTITY/USER)> 按需读取文件(HEARTBEAT/memory日志/self-improving)> 外部 SKILL.md

2. 引导方向主要从上往下:

   • ✅ AGENTS.md → 引导去 MEMORY.md / SKILL.md
   • ✅ MEMORY.md → 引导去 SKILL.md
   • ❌ 底层文件 不要引导回上层(如 MEMORY.md 不要写"详见 AGENTS.md")
   • ⚠️ 安全锚:底层文件如果有一条规则和顶层铁律直接相关,可以加备注: ⚠️ 此规则与 AGENTS.md 铁律相关,如有冲突以 AGENTS.md 为准

3. 检查冗余时以高层级文件为准:

   • 删除低层级已覆盖的重复内容
   • 低层级只保留自己独有的规则

4. 能引导就引导,实在引导不了再向主人推荐其他写入方式

📂 注入 vs 非注入文件说明#

注入文件(每次对话自动加载,Agent 一定能读到):

• AGENTS.md SOUL.md MEMORY.md IDENTITY.md USER.md TOOLS.md(由 OpenClaw 系统注入)
• HEARTBEAT.md(cron 触发时通过锚点引导加载)

非注入文件(需要 Agent 主动读取,可能读不到):

• SKILL.md(需 <available_skills> 匹配才自动读取)
• self-improving/ 目录(需任务前主动读取)
• memory/ 日志(需 memory_search 或 memory_get 主动搜索)
• docs/ 目录(需按路径手动读取)

引导原则:

• ✅ 重要规则尽量放在注入文件内,形成闭环
• ⚠️ 引导到非注入文件时,确保目标文件在 <available_skills> 中有 description 匹配
• ⚠️ 可以多层引导(A→B→C),前提是:每一级的 #[锚点] 在目标文件真实存在,且目标是系统注入文件或 description 匹配的 SKILL.md,确保 AI 能读到
• ✅ 推荐多级联链:AGENTS.md(一行核心)→ MEMORY.md(业务展开)→ SKILL.md(技术实现)

⚠️ 隔离场景直写铁律#

cron 定时任务、子 agent、隔离会话中,禁止使用多级引导(详见 SKILL.md「隔离场景直写铁律」(#isolated-direct-write)),规则必须直写在 prompt 里。

原因:隔离会话不加载 MEMORY.md/SOUL.md/HEARTBEAT.md 等注入文件,引导会断裂。

适用场景:

• OpenClaw cron 定时任务的 prompt
• sessions_spawn 创建的隔离子 agent
• 任何 sessionTarget: isolated 的场景

正确做法:

json

{
  "payload": {
    "kind": "agentTurn",
    "message": "检查当月值班表 /path/to/duty.md,判断今天是否为值班日。\n\n如果是值班日:提醒用户做好值班准备。\n如果不是值班日:回复 NO_REPLY。"
  }
}

错误做法(引导会断裂):

json

{
  "payload": {
    "kind": "agentTurn",
    "message": "详见 MEMORY.md(#duty-check)判断是否值班,如果是详见 HEARTBEAT.md(#duty-rules)推送提醒。"
  }
}

总结:主会话对话可以 A→B→C 多级联链,隔离场景必须一句话写完,不要跳转。

⚠️ 隔离场景 Cron 任务复杂度分级#

核心原则:按任务复杂度决定 cron payload 的写法,不搞一刀切。

级别任务特征示例payload 写法简单规则少(≤3条)、逻辑简单、无需查外部文件值班日判断、每月1号提醒锚点引导:读 HEARTBEAT.md #xxx 锚点区块中等规则适中(4-8条)、需要1-2步判断工作汇报整理、缺陷归档锚点引导 + 关键步骤直写复杂规则多(≥9条)、需要多步检查、有报告模板冗余检查9项清单完整直写:9项清单+报告模板全部写进payload

为什么要分级:

• 简单任务用锚点引导:保持规则集中管理,HEARTBEAT.md 改一次所有 cron 自动生效
• 复杂任务直写:避免多级引导断裂(隔离会话可能不读 SKILL.md 正文),确保执行完整性

复杂任务 cron payload 标准写法:

1. 先声明:"以下是完整执行指令,不需要跳转任何文件"
2. 把 SKILL.md 中的完整 9 项清单逐条写入 payload
3. 把报告模板也写入 payload
4. HEARTBEAT.md 里只留一句简短说明(标注"详见cron payload直写"),不重复规则内容

第9项检查标准(见下方): 按复杂度分级来检查,不再要求"必须锚点引导"。

规则分类决策树#

每次写入或修改规则前，必须先过此判断矩阵。

text

主人说要加/改一条规则
         ↓
问：这条规则描述的是什么？
         ↓
┌──────────────────────────────────────────────────────┐
│ A. 描述"什么时候做/做什么/触发条件/推送渠道"？        │
│    示例：每天23:30发文章、公众号先发草稿再发布          │
│         禁止重复参考已发过的文章、抖音走QQ小红书走微信    │
│    → MEMORY.md（业务规则层）                           │
├──────────────────────────────────────────────────────┤
│ B. 描述"怎么做/用什么工具/API/技术实现/操作步骤"？     │
│    示例：用web_search搜标题、HTML用内联样式禁止<style> │
│         调用wechat-mp-publish、封面上传流程、标题公式   │
│    → 对应的 SKILL.md（技术细节层）                     │
├──────────────────────────────────────────────────────┤
│ C. 描述"行为底线/安全红线/绝对禁止/必须先做"？         │
│    示例：必须先回答再操作、禁止未经授权删除文件         │
│         禁止私自改文件、失败一次就停手汇报              │
│    → AGENTS.md（铁律层）                              │
├──────────────────────────────────────────────────────┤
│ D. 描述"人格/身份/使命/行为风格"？                    │
│    示例：极客导师、沉稳务实、话少精准                   │
│    → SOUL.md / IDENTITY.md                            │
├──────────────────────────────────────────────────────┤
│ E. 描述"执行经验/踩坑教训/领域知识"？                  │
│    示例：OVATION 工作原则10条、360卸载失败经验          │
│    → self-improving/                                  │
└──────────────────────────────────────────────────────┘

录入流程#

text

主人要求写入新规则
    ↓
1. 过规则分类决策树（见上方）：判断规则属于 A/B/C/D/E 哪类
    ↓
2. 匹配层级:
   - A类 → MEMORY.md
   - B类 → 对应的 SKILL.md / docs/
   - C类 → AGENTS.md
   - D类 → SOUL.md / IDENTITY.md
   - E类 → self-improving/
    ↓
3. 🔍 全局扫描关联项:
   - 扫描全部 md 文件,找出与新规则主题相关的所有现有规则
   - 判断这些相关规则之间是否能组成「多级联链」
   - 级联链不限于 2 层,可以 A→B→C 多层,前提是每层锚点真实存在且链路可达
    ↓
4. 向主人推荐级联方案:
   - 展示发现的关联规则分布
   - 推荐最优级联路径(例如:AGENTS.md 一行核心 → MEMORY.md 业务展开 → SKILL.md 技术实现)
   - 等待主人确认后执行
    ↓
5. 生成锚点名:<!-- #[英文短横线] -->
   - 命名规则:全小写 + 短横线分隔,如 #backup-rules
   - self-improving/ 锚点需加领域前缀,如 #ops-sync-failure
    ↓
6. 写入规则(级联格式):
   - AGENTS.md 只保留「一句话核心 + 一个引导语」
   - 执行步骤、技术细节等引导到下层文件
   - 每层只保留本层独有的内容
    ↓
7. 如不确定放哪层 → 向主人推荐

级联格式铁律#

AGENTS.md 标准格式:一句话核心 + 引导语,不写执行步骤

markdown

- **修改 skill 必须同步问询**:详见 SKILL.md「同步流程」(#skill-sync-flow)
- **脚本执行失败就停手**:详见 SKILL.md「失败处理」(#fail-stop)

多层级联链示例:

text

AGENTS.md(铁律核心)
  → "修改 skill 必须同步问询":详见 SKILL.md「同步流程」(#skill-sync-flow)
      ↓
SKILL.md(执行细节)
  → #skill-sync-flow:同步内容=1版本号 2版本历史 3git commit+tag
  → "发布规则详见 MEMORY.md": 详见 MEMORY.md「发布渠道」(#publish-channels)
      ↓
MEMORY.md(业务规则)
  → #publish-channels:抖音走 QQ、小红书走微信

级联链前提:链路必须通

• 每一级的 #[锚点] 在目标文件中真实存在
• 引导目标是系统注入文件或 <available_skills> 匹配的 SKILL.md,确保 AI 能读到

Skill 同步流程#

修改任何 skill 内容并测试通过后,主动询问主人是否执行同步:

1. 更新 SKILL.md 版本号
2. 更新 SKILL.md 版本历史(保留最新 2 条)
3. git commit + tag + GitHub 推送
4. 🔢 同步脚本文件版本号 - 如果 skill 目录下有脚本文件(如 scripts/*.js)，必须同步更新脚本文件头部的版本号注释，确保 SKILL.md 版本号、脚本文件头版本号、git tag 三处一致

• 新增 skill 先创建独立 GitHub 仓库,禁止混入 monorepo
• 每个人格的 skill 推送各自对应的 GitHub 仓库,绝不混淆

失败处理#

当 SKILL.md 中明确写了「失败一次就停手汇报」时,第一次失败后必须立刻停止一切尝试,向主人汇报:

• 不得以任何理由继续自行尝试
• 这是保护 Cookie 和主人控制权的安全红线

⚠️ Skill 自包含原则#

每个 SKILL.md 必须能独立指导完整操作流程，不依赖 MEMORY.md 的技术细节。

• ✅ 业务触发逻辑（何时触发、推送渠道配置）可以引导去 MEMORY.md
• ✅ 技术实现细节（怎么执行、API 调用、排版规范、标题公式、上传流程）必须在 SKILL.md 写完整
• ❌ 违反表现：MEMORY.md 里出现"步骤1/2/3"、"用 xxx API"、"HTML 用内联样式"、"封面上传流程"等

检查方法：MEMORY.md 中如果出现操作步骤类内容（含"步骤/流程/API 调用/上传/生成/排版/标题公式"等技术词），视为违反自包含原则，应移至对应 SKILL.md。

各层"独有规则"示例#

层级应该放什么不应该放什么AGENTS.md一句话核心铁律 + 引导语、安全红线、行为底线执行步骤、技术细节、详细说明MEMORY.md业务触发规则、推送渠道、项目专属规则、禁止重复规则、同步规则操作步骤、API 调用、HTML 排版、标题公式、封面上传流程SOUL.md人格描述、使命、能力设定、行为准则、底线通用行为铁律(应放 AGENTS.md)HEARTBEAT.md待办提醒、报告队列、检查项推送规则详情(应引到 MEMORY.md)SKILL.md操作步骤、API 调用、HTML 排版、标题公式、封面上传、技术选择器、正则、版本历史业务触发逻辑、推送渠道配置、人格描述TOOLS.md本地配置笔记（设备端口、Cookie、API Key 存放路径）业务规则、操作流程

标准引导语格式#

统一格式: 详见 [文件]「[章节名]」(#[锚点])

AGENTS.md 标准引导表示例:

markdown

## 🔗 其他规则引导

| 类别 | 引导位置 |
|------|----------|
| 记忆系统规则 | 详见 MEMORY.md(#clawhub-publish-rules) |
| 心跳检查清单 | 详见 HEARTBEAT.md(#reminder-tasks) |
| 技能调用说明 | 详见各 SKILL.md |
| 本地配置 | 详见 TOOLS.md |

其他常见引导示例:

• 详见 SKILL.md「规则录入流程」(#rule-entry-flow)
• 详见 MEMORY.md「ClawHub 上架规则」(#clawhub-publish-rules)
• 详见 self-improving/memory.md(#ops-sync-failure)

🔄 冗余检查机制#

每 3 天执行一次 9 项检查清单，发现后按照金字塔架构规则，推荐主人清理，主人确认后执行。

触发机制配置#

冗余检查 不会自动触发，需要手动配置触发器。推荐使用 cron 定时任务：

方案：cron 定时任务（推荐）— 复杂度「复杂」级，直写进 payload

1. 在 HEARTBEAT.md 添加简短锚点区块（不重复完整规则，标注详见cron payload）： markdown

   <!-- #redundancy-check -->
   ## 🔺 金字塔冗余检查（每 3 天一次）
   

• 此为复杂任务，完整 9 项清单和报告模板直写在 cron payload 中
• 详见对应 cron payload 直写内容

2. **创建 cron 任务**，payload 直写完整 9 项清单：
   text

以下是金字塔冗余检查完整执行指令（复杂任务直写，不需要跳转任何文件）： 先读 memory/redundancy-check-state.json 判断是否≥3天间隔，然后逐项执行以下 9 项检查： 1.内容冗余:同一规则是否出现在多个文件中 2.引导方向:有没有底层文件引导回顶层 3.锚点一致性:引导语里#[锚点]是否在目标文件中真实存在 4.引导格式:是否都使用"详见[文件]章节名"格式 5.版本历史:各SKILL.md版本历史是否超过2条 6.文件大小:各md文件是否异常膨胀(>3KB需检查) 7.金字塔合规(动态词指纹):扫描所有SKILL.md提取技术关键词→匹配MEMORY.md→发现错位建议移至SKILL.md;检查AGENTS.md是否有操作类内容应下放;检查MEMORY.md是否有铁律类内容应上移 8.连接建议:只在明显相关时才建议级联 9.Cron锚点格式:按复杂度分级检查—简单任务应锚点引导,复杂任务应直写;检查HEARTBEAT.md锚点唯一性和命名规范;检查cron与HEARTBEAT.md一一对应;检查无重复规则 最后按以下模板格式汇报: ##冗余检查报告(日期) |检查项|状态|详情| |内容冗余|✅/❌|...| |引导方向|✅/❌|...| |锚点一致性|✅/❌|...| |引导格式|✅/❌|...| |版本历史|✅/❌|...| |文件大小|✅/❌|...| |金字塔合规|✅/❌|...| |连接建议|💡/无|...| |触发机制+锚点|✅/⚠️|...| 发现问题/层级放错建议/锚点格式告警/建议操作 注意:只检查不擅自修改,等主人确认再清理。完成后更新 memory/redundancy-check-state.json。

3. **Schedule**: `0 12 */3 * *`（每 3 天中午 12 点）

### 9 项检查清单

1. **内容冗余**:同一规则是否出现在多个文件中
2. **引导方向**:有没有底层文件引导回顶层(违反从上往下原则)
3. **锚点一致性**:引导语里的 `#[锚点]` 是否在目标文件中真实存在
4. **引导格式**:是否都使用 `详见 [文件]「[章节名]」(#[锚点])` 格式
5. **版本历史**:各 SKILL.md 版本历史是否超过 2 条
6. **文件大小**:各 md 文件是否异常膨胀(>3KB 需检查)
7. **金字塔合规（动态词指纹检查）**:

- **Step 1**: 扫描 workspace 下所有 SKILL.md，动态提取技术关键词（动态词指纹）：

  - skill name 和 description 中的动词（如 web\_search、wechat-mp-publish、封面上传）
  - SKILL.md 正文中的 API 名、工具名、技术名词（如 HTML 内联样式、排版规范、标题公式）
- **Step 2**: 用这些词去匹配 MEMORY.md 的所有规则
- **Step 3**: 发现匹配 → 提示"MEMORY.md 中的规则含技术关键词 {词}，可能应该放 {skill名}.md"
- **Step 4**: 同时检查 AGENTS.md 中是否包含操作/技术类内容（应下放至 SKILL.md）
- **Step 5**: 检查 MEMORY.md 中是否包含铁律/红线类内容（应上移至 AGENTS.md）
8. **连接建议**:只在发现明显主题相关的规则时才建议级联,不全量扫描
9. **Cron锚点格式检查（v3.6升级:按复杂度分级）:**
- **复杂度分级检查**（新增）：

  - 简单任务(≤3条规则、逻辑简单):cron payload 应使用锚点引导(如「读 HEARTBEAT.md 的 #xxx 锚点区块」)
  - 复杂任务(≥9条规则、多步检查、有报告模板):cron payload 应直写完整清单,不再强制锚点引导
  - 中等任务(4-8条):锚点引导+关键步骤直写
  - 检查方法:按任务实际规则条数判断属于哪一级,确认 cron payload 写法匹配
- HEARTBEAT.md 每个任务块必须有唯一锚点（ `<!-- #xxx -->`）
- 锚点格式： `<!-- #xxx -->`，命名规范「领域-功能」，全小写+短横线
- **直写任务检查**：复杂任务直写时,HEARTBEAT.md 锚点区块应只留简短说明(标注"详见cron payload"),不重复完整规则
- 检查 HEARTBEAT.md 锚点与 cron 任务一一对应，无遗漏/冗余
- 检查是否有重复的规则内容（同一规则既完整出现在 HEARTBEAT.md 又完整出现在 cron payload 里——复杂任务除外）
- 检查 HEARTBEAT.md 锚点格式是否规范（锚点必须在章节标题前一行，不能悬空或重复）
- 生成报告汇报给主人，等确认后再调整，不自动修改

### 执行步骤

1. **读取触发状态**：先读 `memory/redundancy-check-state.json`，判断是否满足 3 天间隔（仅 Heartbeat 方案）
2. 读取所有 md 文件内容
3. 逐项检查上述 9 项清单
4. 第7项(金字塔合规):
a. 动态词指纹提取:扫描所有 SKILL.md,提取技术关键词
b. 用动态词指纹匹配 MEMORY.md,发现技术细节错位→建议移至 SKILL.md
c. 扫描 AGENTS.md,发现操作步骤类内容→建议下放至 SKILL.md
d. 扫描 MEMORY.md,发现铁律/红线类内容→建议上移至 AGENTS.md
e. 检查 MEMORY.md 是否违反 Skill 自包含原则(含操作步骤/API/标题公式等)
5. 第8项(连接建议):只在发现明显主题相关的规则时才建议级联(如两条都是运维安全类),不强制
6. 第9项(Cron锚点格式检查):
a. **复杂度分级判断**:按任务规则条数判断级别(简单≤3/中等4-8/复杂≥9)
b. 简单任务:检查是否使用锚点引导
c. 复杂任务:检查是否直写完整清单,HEARTBEAT.md是否只留简短说明
d. 检查 HEARTBEAT.md 每个任务块是否有唯一锚点（）
e. 检查锚点格式是否规范（命名：领域-功能，全小写+短横线）
f. 检查 HEARTBEAT.md 锚点与 cron 任务一一对应，无遗漏/冗余
g. 检查是否有重复规则
h. 生成报告，汇报给主人，等确认后再调整
7. 按照金字塔架构规则,以高层级文件为准,删除低层级重复
8. 向主人汇报检查结果,确认后执行清理
9. **更新状态文件**：写入当前时间到 `memory/redundancy-check-state.json`（仅 Heartbeat 方案）

### 检查报告模板

text

冗余检查报告(YYYY-MM-DD)#

发现问题:[描述] 层级放错建议:[描述] 重复触发风险:[同一任务出现在两个及以上机制中时列出] 锚点格式告警:[HEARTBEAT.md锚点格式不规范/锚点与cron不一一对应/规则重复出现在HEARTBEAT.md和cron payload中] 归类建议:[每个任务推荐放的触发机制及理由] 连接建议:[仅明显相关时才提] 建议操作:[描述]

## 🚀 快速部署

### 方式一:一键初始化脚本(推荐)

- **Mac / Linux 用户**:
  bash

  ```bash
  ./scripts/init.sh my-new-agent

• Windows 用户 (PowerShell): powershell

  .\scripts\init.ps1 my-new-agent
  
  

方式二:手动初始化#

创建新子 Agent 时,按以下结构初始化:

text

workspace-{name}/
├── AGENTS.md          ← 顶层铁律模板
├── MEMORY.md          ← 中层业务规则模板
├── SOUL.md            ← 中层人格配置模板
├── IDENTITY.md        ← 身份卡片模板
├── USER.md            ← 主人信息模板
├── TOOLS.md           ← 本地配置模板
├── HEARTBEAT.md       ← 心跳清单模板
├── docs/              ← 详细文档目录
└── self-improving/    ← 自我进化目录

📋 模板文件#

各层模板详见 templates/ 目录(v2.0 教学版):

模板路径说明AGENTS.mdtemplates/AGENTS.md顶层铁律模板(带使用说明注释)MEMORY.mdtemplates/MEMORY.md中层业务规则模板(带示例)SOUL.mdtemplates/SOUL.md中层人格配置模板(带安全锚示例)IDENTITY.mdtemplates/IDENTITY.md身份卡片模板USER.mdtemplates/USER.md主人信息模板TOOLS.mdtemplates/TOOLS.md本地配置模板HEARTBEAT.mdtemplates/HEARTBEAT.md心跳清单模板

📖 版本历史#

| 版本 | 日期 | 变更 | | v3.6 | 2026-06-07 | Cron任务按复杂度分级(修复引导断裂):1新增#cron-complexity-grades分级规则(简单≤3条锚点引导/中等4-8条混合/复杂≥9条直写);2#trigger-setup冗余检查改为直写9项清单+报告模板进payload;3第9项检查标准更新为按复杂度分级检查,不再一刀切要求锚点引导;4解决隔离会话引导链断裂导致agent偷懒跑简化版的问题 ✅ | | v3.5 | 2026-06-05 | 第9项重构为Cron锚点格式检查:1HEARTBEAT.md改为cron触发时通过锚点引导加载;2每个任务块必须有唯一锚点();3cron payload使用锚点引导(而非硬编码长规则);4检查锚点与cron一一对应,无遗漏/冗余;5检查是否有重复规则(同一规则既在HEARTBEAT.md又在cron payload硬编码);6生成报告不自动修改 ✅ |