ClawHub

金字塔记忆架构

MCP Tools

通用 AI Agent 记忆架构 Skill。采用"金字塔"分层结构：顶层（AGENTS.md）只放铁律级行为规则，中层（MEMORY.md/SOUL.md/HEARTBEAT.md）放业务规则和人格配置，底层（SKILL.md/TOOLS.md）放技术实现细节。适用于所有新建子 Agent 工作区初始化。触发场景：创建新 Agent、初始化工作区、记忆架构设计、规则录入引导、md 文件冗余检查。

Install

openclaw skills install pyramid-memory-architecture

金字塔记忆架构（Pyramid Memory Architecture）

本 Skill 提供一套标准化的 Agent 记忆分层架构，适用于任何新建子 Agent 工作区。 核心理念：规则按触发优先级分层存放，引导只能从上往下，下层不引导回上层。 版本：v2.2 - 包含一键初始化脚本 + 教学版模板

📐 架构总览

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

各层定位

层级文件加载方式内容定位
顶层AGENTS.md系统级注入，每次必加载铁律级行为规则、安全红线、引导表
中层MEMORY.md主会话系统注入业务触发规则、长期记忆、项目规则
中层SOUL.md系统级注入人格、身份、使命、行为准则
中层HEARTBEAT.md心跳触发时加载待办提醒、报告队列、周期性检查清单
中层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（心跳触发时加载）

非注入文件（需要 Agent 主动读取，可能读不到）：

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

引导原则：

  • ✅ 重要规则尽量放在注入文件内，形成闭环
  • ⚠️ 引导到非注入文件时，确保目标文件在 <available_skills> 中有 description 匹配
  • ❌ 不要多层引导（A→B→C），大概率断裂

录入流程

主人要求写入新规则
    ↓
1. 判断规则类型：行为规则 / 业务规则 / 技术细节
    ↓
2. 匹配层级：
   - 行为规则（铁律级）→ AGENTS.md
   - 业务规则（触发器）→ MEMORY.md
   - 人格/身份 → SOUL.md / IDENTITY.md
   - 技术细节 → SKILL.md / docs/
    ↓
3. 检查现有文件有无重复内容：
   - 有重复 → 以高层级为准，删除低层级重复
   - 无重复 → 写入对应文件
    ↓
4. 如不确定放哪层 → 向主人推荐

各层"独有规则"示例

层级应该放什么不应该放什么
AGENTS.md先回答再操作、禁止未确认执行、规则录入引导、3天检查冗余详细 Heartbeat 说明、群聊详细规则、Memory 详细说明
MEMORY.md推送渠道规则、业务触发器、项目专属规则、同步规则Cookie 保护铁律（应放 AGENTS.md）、技术选择器
SOUL.md人格描述、使命、能力设定、行为准则、底线通用行为铁律（应放 AGENTS.md）
HEARTBEAT.md待办提醒、报告队列、检查项推送规则详情（应引到 MEMORY.md）
SKILL.md技术选择器、正则、API 流程、版本历史行为规则、人格描述

标准引导语格式

统一格式： 详见 [文件/章节名]

AGENTS.md 标准引导表：

## 🔗 其他规则引导

| 类别 | 引导位置 |
|------|----------|
| 记忆系统规则 | 详见 MEMORY.md |
| 心跳检查清单 | 详见 HEARTBEAT.md |
| 群聊发言规则 | 详见 HEARTBEAT.md |
| 技能调用说明 | 详见各 SKILL.md |
| 本地配置 | 详见 TOOLS.md |
| 安全红线 | Red Lines（见下方） |

其他常见引导示例：

  • 完整规则详见 docs/temp-tasks.md
  • 技术细节详见 SKILL.md「主人规则」第11条
  • 自动发布流程详见 SKILL.md「主人标准工作流程」

引导语铁律：

  • ✅ 引导只能从上往下（AGENTS → MEMORY → SKILL）
  • ❌ 底层文件不要引导回上层（如 MEMORY.md 不要写"详见 AGENTS.md"）
  • 引导语要简洁，一行搞定，不要展开详细内容

🔄 冗余检查机制

每 3 天检查一次各 md 文件有无冗余/重复或者可合并内容，发现后按照金字塔架构规则，推荐主人清理，主人确认后执行。

检查步骤

  1. 读取所有 md 文件内容
  2. 对比各层文件，查找：
    • 重复内容：两个文件写了同样的规则
    • 可合并内容：可以精简的相似规则
    • 违规引导：底层文件引导回顶层（如"详见 AGENTS.md"）
  3. 按照金字塔架构规则，以高层级文件为准，删除低层级重复
  4. 向主人汇报检查结果，确认后执行清理

检查清单

  • AGENTS.md 铁律 vs MEMORY.md 铁律 vs SOUL.md 铁律 — 有无重复？
  • 各文件有无引导回上层的情况？
  • HEARTBEAT.md / TOOLS.md 有无默认模板未清理？
  • MEMORY.md 业务规则有无与 SKILL.md 重复？

🚀 快速部署

方式一：一键初始化脚本（推荐）

  • Mac / Linux 用户： 
    ./scripts/init.sh my-new-agent
  • Windows 用户 (PowerShell)： 
    .\scripts\init.ps1 my-new-agent

方式二：手动初始化

创建新子 Agent 时，按以下结构初始化：

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心跳清单模板

📖 版本历史

版本日期变更
v2.22026-05-25冗余检查规则更新：①删除 HEARTBEAT.md 中 3 个子 agent 的冗余检查规则（只保留 cron 触发）；②统一主工作区/lizi 工作区/work 工作区的版本 ✅
v2.02026-05-21Market Ready 发布：①新增 scripts/init.sh 一键初始化脚本；②升级 templates 为“教学版”，内含详细使用说明；③补全 self-improving 目录结构 ✅
v1.32026-05-21消除重复铁律+补充执行机制：①删除 SOUL.md 与 AGENTS.md 重复的隐私保密规则，只保留独有规则；②HEARTBEAT.md 新增 3 天检查冗余定时任务；③AGENTS.md 新增冲突定义；④同步更新 QQ/微信两个人格 + 金字塔模板 ✅
v1.22026-05-21新增安全锚机制：底层文件可与顶层铁律挂钩，备注"如有冲突以 AGENTS.md 为准"，防止规则冲突而不被发现；同步更新 QQ/微信两个人格 ✅
v1.12026-05-21修复5个隐患：①加入 self-improving 层级到架构图和部署命令；②AGENTS.md 加"不要只看本文件"提醒 + 铁律优先级声明；③MEMORY.md 加业务规则引导表；④模板文件加占位示例内容；⑤标准引导语格式章节 ✅
v1.02026-05-21初始版本：金字塔架构定义、规则录入铁律、冗余检查机制、模板文件 ✅
More in MCP Tools