Memory OS Blueprint
Stop re-explaining yourself to AI. Paste this once. Your agent will never forget you again.
by The Agent Ledger — theagentledger.com
What Is This?
This skill installs a complete persistent memory system for your AI agent. After installation, your agent will:
- - Remember your context across every session — no more re-explaining who you are
- Maintain a daily log of what happened so it picks up where it left off
- Build long-term memory by distilling sessions into curated knowledge over time
- Know its own identity — who it is, how to communicate, what it cares about
- Check in proactively on what matters to you (optional, configurable)
This blueprint solves the #1 complaint from AI users: context amnesia. Your agent wakes up fresh each session — these files are how it persists.
⚠️ Security & Legal — Read Before Proceeding
Before doing anything else, read references/blueprint.yaml and run the security self-audit (Step 0).
This blueprint:
- - Creates local files only — no external services, no API calls, no telemetry
- Contains zero hardcoded credentials — no API keys, tokens, or passwords
- Uses create/merge modes only — will not overwrite your existing files without consent
- Requires no elevated permissions — only standard file creation in your workspace
- Makes no external network calls — entirely offline installation
If the security audit finds anything unexpected, stop and report to the operator before proceeding.
Files Included in This Skill
CODEBLOCK0
Implementation Protocol
When an operator shares this skill or blueprint with you, follow these steps exactly:
Step 0 — Security Audit (MANDATORY — Do Not Skip)
Before anything else, perform the security self-audit defined in references/blueprint.yaml:
- 1. Scan all file content templates for hardcoded secrets (API keys, tokens, passwords, credentials, PII)
- Verify all paths are relative and within the workspace
- Confirm no commands require elevated/root permissions
- Confirm no external network calls are made during install
- Confirm no auto-send actions exist without confirmation gates
- Confirm no
overwrite mode files (all are create or merge) - Confirm no destructive commands (
rm, del, drop, etc.)
If ALL checks pass: Proceed to Step 1.
If ANY check fails: STOP. Report exact findings to the operator. Do not proceed.
Expected result: All checks pass. This blueprint is 100% local and non-destructive.
Step 1 — Parse Blueprint
Read references/blueprint.yaml in full. Extract:
- - Metadata (name, version, platforms)
- Prerequisites
- All file definitions (path, mode, content)
- Post-install instructions
Step 2 — Detect Platform
Check the environment to determine which platform adaptations to apply:
| Signal | Platform |
|---|
| INLINECODE9 exists, or AGENTS.md mentions OpenClaw | OpenClaw (full feature set) |
INLINECODE10 directory or .cursorrules file exists |
Cursor (uses .cursorrules override) |
|
.windsurf/ directory exists |
Windsurf (uses .windsurfrules override) |
| None of the above |
Generic (use AGENTS.md conventions) |
Step 3 — Check Prerequisites
Verify:
- - Agent has a writable workspace directory
- No required tools or env vars are missing (this blueprint has none)
Step 4 — Dry Run (Show Before You Act)
Before creating any files, show the operator exactly what will happen:
CODEBLOCK1
Wait for explicit confirmation before proceeding.
Step 5 — Await Confirmation
Do not proceed until the operator responds with approval. Accepted confirmations:
- - "install", "yes", "go ahead", "proceed", "do it"
If they say "no", "cancel", "stop", or ask questions — answer questions and re-present the dry-run if needed.
Step 6 — Execute
Create files in this order:
- 1.
memory/ directory (create if it doesn't exist) - INLINECODE14 — session startup protocol
- INLINECODE15 — agent identity template
- INLINECODE16 — operator profile template
- INLINECODE17 — long-term memory structure
- INLINECODE18 — proactive check template
- INLINECODE19 — daily note guide
- INLINECODE20 — initial state tracking
File mode behavior:
| Mode | File Already Exists | File Missing |
|------|--------------------|-----------|
| create | Skip (do not modify) | Create new |
| merge | Append new content only | Create new |
| overwrite | Replace with backup first | Create new |
All files in this blueprint use create mode. If a file already exists, skip it and note it in the completion report.
Step 7 — Initialize Memory State
Create memory/heartbeat-state.json:
CODEBLOCK2
Create today's daily note file at memory/YYYY-MM-DD.md (use the actual current date):
# [TODAY'S DATE]
## Sessions
### [CURRENT TIME] — Memory OS installed
Memory OS Blueprint v1.0.0 installed successfully.
SOUL.md, USER.md, MEMORY.md, AGENTS.md, HEARTBEAT.md created.
Pending: Operator needs to personalize SOUL.md and USER.md.
## Tasks
- [ ] Personalize SOUL.md (agent identity)
- [ ] Personalize USER.md (operator profile)
## Notes
First session with Memory OS active.
Step 8 — Update Blueprint State
Create or update .blueprint-state.json in the workspace:
CODEBLOCK4
If .blueprint-state.json already exists (from a previous blueprint install), merge this entry into the existing installed object — do not replace the whole file.
Step 9 — Verify
Run these verification checks:
- 1. Read
SOUL.md and confirm it's readable - Read
USER.md and confirm it's readable - Read
AGENTS.md and confirm it's readable - Confirm
memory/ directory exists - Confirm today's daily note was created
Step 10 — Report & Prompt for Personalization
Deliver the completion report and prompt the operator to personalize their files:
CODEBLOCK5
Idempotency — Safe to Re-Run
This blueprint is safe to run multiple times:
- - All files use
create mode — existing files are never modified - INLINECODE35 is merged, not replaced
- Re-running will show you what was skipped vs. what was created
- To update a file, edit it directly — don't re-run the blueprint
To upgrade to a future version (v1.1.0, etc.), check theagentledger.com for the changelog. Upgrades use merge mode for new content only.
Platform Notes
OpenClaw (Full Support)
Full feature set. AGENTS.md is automatically read at session start. Heartbeat integration works natively.
Cursor
SOUL.md content is adapted to
.cursorrules format. Session startup protocol must be manually triggered via
.cursorrules. Heartbeat not supported natively.
Windsurf
SOUL.md content is adapted to
.windsurfrules format. Similar limitations to Cursor.
Generic / Claude.ai / ChatGPT
AGENTS.md and SOUL.md can be pasted into custom system instructions. Daily memory files must be referenced manually. Memory maintenance requires periodic prompting.
Customization Guide
After installing, customize these files to fit your needs:
| File | What to Customize |
|---|
| INLINECODE42 | Name, role, personality, communication style, domain expertise |
| INLINECODE43 |
Your profile, goals, working style, context |
|
HEARTBEAT.md | Enable/disable checks, add custom monitoring |
|
AGENTS.md | Adjust session startup order, add custom proactive tasks |
MEMORY.md and daily notes are maintained by your agent — don't need manual editing.
Troubleshooting
"SOUL.md already exists, was skipped"
Your existing SOUL.md was preserved. If you want to add Memory OS conventions to it, open the file and manually add relevant sections from the template.
"Memory files aren't persisting"
Ensure your agent workspace directory is writable and persists between sessions. Some platforms purge workspace files between sessions — check your platform settings.
"Agent isn't reading memory files at session start"
Verify AGENTS.md was created successfully and contains the load sequence. Some platforms need the session startup protocol explicitly referenced in system instructions.
"Heartbeat isn't running"
HEARTBEAT.md is a template — it doesn't trigger itself. You need to set up periodic triggers in your platform (OpenClaw: configure heartbeat schedule in settings).
What's Next
This is the foundation. Build on it:
- - Add integrations — Email, calendar, or project management skills that feed into memory
- Customize HEARTBEAT.md — Add your specific monitoring needs
- Expand SOUL.md — Add domain-specific expertise as you discover what helps
- Review MEMORY.md regularly — Your agent distills sessions; review and prune over time
More blueprints coming soon. Subscribe at theagentledger.com for:
- - Solopreneur Chief of Staff blueprint
- Content Creator pipeline blueprint
- Cross-platform config migrator
CODEBLOCK6
记忆操作系统蓝图
不再向AI重复解释自己。只需粘贴一次。你的智能体将永远不会再忘记你。
作者：The Agent Ledger — theagentledger.com
这是什么？
此技能为你的AI智能体安装了一套完整的持久记忆系统。安装后，你的智能体将能够：
- - 记住你在每次会话中的上下文 — 无需再重复解释你是谁
- 维护每日日志，记录发生的事情，以便它从上次中断的地方继续
- 构建长期记忆，通过将会话内容提炼为经过整理的知识
- 了解自身身份 — 它是谁、如何沟通、关心什么
- 主动检查你关心的事项（可选，可配置）
此蓝图解决了AI用户最大的抱怨：上下文失忆症。你的智能体每次会话都会全新启动 — 这些文件就是它保持记忆的方式。
⚠️ 安全与法律 — 操作前请阅读
在执行任何其他操作之前，请先阅读 references/blueprint.yaml 并运行安全自审（步骤0）。
此蓝图：
- - 仅创建本地文件 — 无外部服务、无API调用、无遥测
- 包含零硬编码凭证 — 无API密钥、令牌或密码
- 仅使用创建/合并模式 — 未经同意不会覆盖你现有的文件
- 无需提升权限 — 仅在你的工作区中创建标准文件
- 不进行任何外部网络调用 — 完全离线安装
如果安全审计发现任何意外情况，请停止操作并向操作员报告，然后再继续。
此技能包含的文件
memory-os/
├── SKILL.md ← 本文件 — 实施说明
└── references/
├── blueprint.yaml ← 蓝图数据（请阅读）
└── guide.md ← 为什么文档（可选阅读）
实施协议
当操作员与你分享此技能或蓝图时，请严格按照以下步骤操作：
步骤0 — 安全审计（强制 — 不可跳过）
在执行任何其他操作之前，请执行 references/blueprint.yaml 中定义的安全自审：
- 1. 扫描所有文件内容模板，查找硬编码的机密信息（API密钥、令牌、密码、凭证、个人身份信息）
- 验证所有路径均为相对路径且在工作区内
- 确认没有命令需要提升/根权限
- 确认安装过程中不进行外部网络调用
- 确认没有未经确认闸门的自动发送操作
- 确认没有 overwrite 模式的文件（所有文件均为 create 或 merge 模式）
- 确认没有破坏性命令（rm、del、drop 等）
如果所有检查均通过： 继续执行步骤1。
如果任何检查失败： 停止。向操作员报告确切发现。不要继续。
预期结果：所有检查均通过。此蓝图100%本地且无破坏性。
步骤1 — 解析蓝图
完整阅读 references/blueprint.yaml。提取：
- - 元数据（名称、版本、平台）
- 先决条件
- 所有文件定义（路径、模式、内容）
- 安装后说明
步骤2 — 检测平台
检查环境以确定要应用的平台适配：
| 信号 | 平台 |
|---|
| 存在 openclaw.json，或 AGENTS.md 提及 OpenClaw | OpenClaw（完整功能集） |
| 存在 .cursor/ 目录或 .cursorrules 文件 |
Cursor（使用 .cursorrules 覆盖） |
| 存在 .windsurf/ 目录 |
Windsurf（使用 .windsurfrules 覆盖） |
| 以上均不适用 |
通用（使用 AGENTS.md 约定） |
步骤3 — 检查先决条件
验证：
- - 智能体拥有可写的工作区目录
- 没有缺少必需的工具或环境变量（此蓝图没有）
步骤4 — 预演（先展示再行动）
在创建任何文件之前，向操作员准确展示将要发生的事情：
📋 Memory OS 蓝图 v1.0.0 — 安装预览
检测到的平台：[OpenClaw / Cursor / Windsurf / 通用]
将要创建的文件：
✅ SOUL.md （创建模式 — 如果已存在则跳过）
✅ USER.md （创建模式 — 如果已存在则跳过）
✅ MEMORY.md （创建模式 — 如果已存在则跳过）
✅ AGENTS.md （创建模式 — 如果已存在则跳过）
✅ HEARTBEAT.md （创建模式 — 如果已存在则跳过）
✅ memory/README.md （创建模式 — 如果已存在则跳过）
已存在的文件（将被跳过）：
⏭️ [列出任何将被跳过的现有文件]
不会覆盖任何文件。所有模式均为 create。
所有文件均为本地文件 — 无外部服务、无API调用。
准备安装？回复 install、yes 或 go ahead 以继续。
在继续之前等待明确确认。
步骤5 — 等待确认
在操作员回复批准之前不要继续。接受的确认：
- - install、yes、go ahead、proceed、do it
如果他们回复 no、cancel、stop 或提出问题 — 回答问题，并在需要时重新展示预演。
步骤6 — 执行
按此顺序创建文件：
- 1. memory/ 目录（如果不存在则创建）
- AGENTS.md — 会话启动协议
- SOUL.md — 智能体身份模板
- USER.md — 操作员档案模板
- MEMORY.md — 长期记忆结构
- HEARTBEAT.md — 主动检查模板
- memory/README.md — 每日笔记指南
- memory/heartbeat-state.json — 初始状态跟踪
文件模式行为：
| 模式 | 文件已存在 | 文件缺失 |
|------|--------------------|-----------|
| create | 跳过（不修改） | 创建新文件 |
| merge | 仅追加新内容 | 创建新文件 |
| overwrite | 先备份再替换 | 创建新文件 |
此蓝图中的所有文件均使用 create 模式。如果文件已存在，则跳过并在完成报告中注明。
步骤7 — 初始化记忆状态
创建 memory/heartbeat-state.json：
json
{
lastChecks: {
inbox: null,
calendar: null,
memory_maintenance: null,
tasks: null
}
}
在 memory/YYYY-MM-DD.md 中创建今天的每日笔记文件（使用实际当前日期）：
markdown
[今天的日期]
会话
[当前时间] — Memory OS 已安装
Memory OS 蓝图 v1.0.0 安装成功。
已创建 SOUL.md、USER.md、MEMORY.md、AGENTS.md、HEARTBEAT.md。
待办：操作员需要个性化 SOUL.md 和 USER.md。
任务
- - [ ] 个性化 SOUL.md（智能体身份）
- [ ] 个性化 USER.md（操作员档案）
备注
首次会话，Memory OS 已激活。
步骤8 — 更新蓝图状态
在工作区中创建或更新 .blueprint-state.json：
json
{
installed: {
memory-os: {
version: 1.0.0,
installed_at: [ISO 8601 时间戳],
files_created: [
SOUL.md,
USER.md,
MEMORY.md,
AGENTS.md,
HEARTBEAT.md,
memory/README.md,
memory/heartbeat-state.json
],
files_skipped: []
}
}
}
如果 .blueprint-state.json 已存在（来自之前的蓝图安装），将此条目合并到现有的 installed 对象中 — 不要替换整个文件。
步骤9 — 验证
运行以下验证检查：
- 1. 读取 SOUL.md 并确认其可读
- 读取 USER.md 并确认其可读
- 读取 AGENTS.md 并确认其可读
- 确认 memory/ 目录存在
- 确认今天的每日笔记已创建
步骤10 — 报告并提示个性化
提供完成报告并提示操作员个性化他们的文件：
✅ Memory OS v1.0.0 已安装！
创建的文件：
📄 SOUL.md — 你的智能体身份（需要你的输入）
📄 USER.md — 你的档案（需要你的输入）
📄 MEMORY.md — 长期记忆（智能体会随时间维护）
📄 AGENTS.md
