OpenClaw Memory 记忆系统完全指南：文件结构、Heartbeat机制与调教实践

关键词OpenClaw Memory、AI Agent记忆、本地记忆存储、Heartbeat心跳、USER.md调教一、问题背景为什么 AI Agent 需要独立的记忆系统大模型的上下文窗口有限——即使是 200K tokens 的 Claude关闭窗口后也完全忘记之前的对话。要让 AI Agent 拥有长期记忆需要在模型外部建立持久化存储。OpenClaw 的记忆架构设计原则本地存储所有记忆存在用户本地不上传云端文件即记忆以 Markdown 文件存储用户可直接阅读和编辑分层管理不同类型记忆独立存储按需加载用户可控用户可以直接查看、编辑、删除任何记忆二、没配记忆 vs 配好记忆用起来差多少使用场景没配记忆配好记忆USER.md MEMORY.md 心跳沟通偏好每次对话都要重新说我喜欢结论先行自动按你的偏好风格回复项目背景每次都要解释项目是什么开口就知道你的项目背景纠错效果同样的错误会重复犯纠正一次写进 MEMORY.md之后不再犯偏好学习告诉它 10 次也没用会自动把偏好写进文件持续生效三、记忆文件结构3.1 完整目录~/.openclaw/workspace/ ├── IDENTITY.md # Agent 身份定义 ├── SOUL.md # 行为准则和思维模型 ├── USER.md # 用户画像 ├── MEMORY.md # 核心长期记忆主索引 ├── HEARTBEAT.md # 心跳任务清单 ├── AGENTS.md # 安全规则可选 ├── memory/ │ ├── 2026-04-01.md # 每日记忆日志 │ ├── 2026-04-02.md │ └── ... └── knowledge/ ├── KNOWLEDGE-MAP.md # 知识索引 └── domain-specific/ # 专业知识文件3.2 各文件详解IDENTITY.md — 身份记忆作用定义 Agent 的人格、角色和基本特征触发时机每次会话开始时自动加载# Identity ## 基本信息 - **Name:** [Agent名称] - **Role:** [角色定义] - **Personality:** [性格特征] ## 核心特质 - [特质1例如追求细节不接受粗糙的东西] - [特质2例如结论先行不废话]SOUL.md — 行为准则作用定义 Agent 的思维方式和行为规范重点这里写的是可执行的规程不是笼统的 System Prompt# Soul ## 核心原则 - 结论先行不废话 - 重要信息必须写入文件心里记着 不存在 - 不确定时主动询问不随意假设 ## 思维模型 - 金字塔原理结论→支撑→细节 - 第一性原理 ## 记忆纪律 - 用户交代的规则立即写入 MEMORY.md - 对话中的关键决策记录日期和原因USER.md — 用户画像最该认真写的一个文件作用记录你的偏好、工作风格、项目背景更新方式对话中自动学习 手动编辑两种方式都重要# User Profile ## 沟通偏好 - 风格简洁直接避免废话 - 反馈接受直接批评不需要过度包装 - 格式优先结构化输出表格/列表 ## 当前项目 - [项目1][简短描述] - [项目2][简短描述] ## 技术栈 - 常用Python / HTML / Markdown - 工具VS Code / drawio / Playwright ## 规则和偏好 - [规则1例如代码示例用 Python不用 Java] - [规则2例如结论要量化不说很多说3倍]MEMORY.md — 核心长期记忆作用存储经过筛选的重要信息是记忆系统的主索引维护原则只记录值得长期记住的每条记忆附带日期和上下文定期清理过时条目# Memory ## 核心规则用户交代的原则 - [规则]: [交代时间] ## 关键决策记录 - [日期] [决策内容][原因和背景] ## 重要洞察 - [洞察内容]: [来源和日期] ## 项目状态 - [项目名]: [当前状态], [最后更新时间]memory/日期.md — 每日记忆命名规则YYYY-MM-DD.md# 2026-04-07 ## 今日任务 - [x] 完成了 XX 任务 - [ ] YY 任务推迟到明天 ## 关键对话 - 讨论了 [主题]结论是 [结论] ## 待整理到 MEMORY.md - [需要长期保留的重要信息]四、Heartbeat 心跳机制4.1 心跳不是闹钟是记忆的自动维护员很多人把 Heartbeat 理解为定时提醒。这只对了一部分。心跳的核心价值自动维护记忆系统防止记忆退化。每次心跳触发它会把当天对话里的关键信息写进当日记忆检查遗漏的待办定期把旧日记蒸馏进长期记忆清理过时和矛盾的记忆条目关掉心跳 vs 开着心跳对比项关掉心跳开着心跳学习记录不会更新自动更新任务追踪靠你手动自动追踪旧记忆清理堆积、矛盾定期蒸馏清理一个月后记忆越来越旧越来越懂你4.2 HEARTBEAT.md 配置示例# Heartbeat Tasks ## 每日任务 - [ ] 学习阅读1篇AI/技术文章3句话摘要存入当日记忆 - [ ] 记忆整理回顾今日对话提炼关键信息更新 MEMORY.md - [ ] ✅ 追踪检查待办标记已完成/过期的 ## 每周任务 - [ ] 记忆蒸馏将7天前的日记精华提炼进 MEMORY.md清理源文件 - [ ] 质量自检审查 MEMORY.md删除过时/矛盾条目4.3 心跳频率配置{heartbeat:{enabled:true,interval_minutes:30,quiet_hours:{start:23:00,end:07:00}}}⚠️Token 成本提醒心跳每次触发会消耗 Token。频率设置建议 30-60 分钟一次夜间关闭。五、坑记忆越多≠越好坑MEMORY.md 越来越大开始出现矛盾信息为什么踩很多人习惯让它记住但从不清理几周后 MEMORY.md 里既有用 Python 3.9又有用 Python 3.12AI 不知道该听哪个。# 查看 MEMORY.md 大小wc-l~/.openclaw/workspace/MEMORY.md# 超过 500 行建议清理# 专业知识移到 knowledge/ 目录MEMORY.md 只保留核心规则和决策解决方案每周花 5 分钟回顾 MEMORY.md删掉不再准确的条目把专业知识归档到knowledge/目录。六、记忆安全风险说明记忆文件包含你的工作习惯、项目信息、决策思路。2026年3月工信部安全通告中特别提及记忆文件泄露可被用于精准社会工程攻击。基本安全配置# 1. 确认 Gateway 绑定地址必须是 127.0.0.1grephost~/.openclaw/openclaw.json# 2. 确认记忆目录权限chmod700~/.openclaw/workspace/# 3. 敏感信息不要存进记忆文件echoSENSITIVE_KEYxxx~/.openclaw/.env# 确保 .env 在 .gitignore 中记忆文件不应存储的内容不应存储应该存储密码、API Key、Token偏好和风格设定他人的私密信息项目概要非敏感部分具体薪资/合同条款工作习惯和规则七、初始化清单刚装好就做□ 编辑 USER.md填写沟通风格、当前项目、技术栈最重要 □ 编辑 IDENTITY.md定义 Agent 的名字和角色 □ 编辑 SOUL.md写入希望 Agent 遵守的核心原则 □ 配置 HEARTBEAT.md设置你需要的定时任务 □ 检查 Gateway 绑定地址是否为 127.0.0.1八、常见问题 QAQ记忆文件可以用 git 管理吗可以但要注意.gitignoreecho.env~/.openclaw/.gitignoreechomemory/~/.openclaw/.gitignore# 每日日记通常不需要同步建议同步IDENTITY.md、SOUL.md、USER.md、MEMORY.md、HEARTBEAT.mdQ换了电脑记忆能带走吗可以直接复制目录# 备份cp-r~/.openclaw/workspace/ ~/Desktop/openclaw-backup/# 在新电脑恢复安装好 OpenClaw 后cp-r~/openclaw-backup/ ~/.openclaw/workspace/不绑账号不锁云端完全可迁移。Q为什么不用向量数据库存记忆OpenClaw 选择文件系统是刻意权衡方案优点缺点文件系统当前透明、可编辑、人类可审计语义检索能力弱向量数据库语义检索强对用户不透明在个人助手场景下你能看到、能修改、能信任比检索速度快 0.1 秒更重要。系列导航第1篇认识 OpenClaw第2篇安装路线选择第3篇Skill 技能系统第4篇Memory 记忆调教本篇第5篇安全加固第6篇Token 省钱手册第7篇小红书全流程第8篇数据分析实战更多内容请关注【一深思AI】