OpenClaw Memory — Personalize Agent

01 / How Memory Works

What Are Memory Files?

Fresh out of the box, your OpenClaw agent knows nothing about you. Every conversation starts cold — it doesn't know your name, how you like to communicate, what projects you're working on, or what it's absolutely not allowed to do. It's a capable assistant with no context, and a capable assistant with no context gives generic answers.

Memory files fix this. They're plain Markdown files that live in ~/.openclaw/ on your server, and OpenClaw automatically loads them into every conversation. Whatever you write in them becomes part of the agent's operating context — its personality, your profile, its rules, its environment. This is how you go from "helpful chatbot" to "personal AI that actually knows me."

The Files and When They Load

OpenClaw has six memory files. They don't all load the same way — understanding when each one gets injected is key to building a lean, effective workspace:

Everyturn

AGENTS.md — Operating instructions and behavioral rules.
SOUL.md — Persona, tone, values, and hard limits.
TOOLS.md — Environment configuration and tool guidance.
These three files are the core. They're injected into every single message.

DMsonly

USER.md — Your personal profile and preferences.
MEMORY.md — Private iron-law rules that must always be true.
These are never loaded in group channels (e.g. a Discord server) — only in direct messages and main sessions. This is a security feature.

Firstrun only

BOOTSTRAP.md — A setup interview that creates your other files. Runs once during initial setup, then gets deleted. More on this in the Starter Kit section.

Gatewaystartup

IDENTITY.md — The agent's name and core characteristics. Loaded once when the gateway starts, not on every turn.

Every byte costs tokens. AGENTS.md, SOUL.md, and TOOLS.md are injected on every single message to your agent. A 50,000-character SOUL.md isn't impressive — it's expensive. Community best practice is to keep each file under 10,000–15,000 characters. Put deep reference content in a docs/ folder and load it on-demand with skills instead.

Where the Files Live

All memory files go in your OpenClaw workspace directory:

☁️ AWS EC2 / 🖥️ Mini PC

# List your current memory files
ls -la ~/.openclaw/

# A well-configured workspace looks like this:
~/.openclaw/
├── AGENTS.md       ← operating instructions (every turn)
├── SOUL.md         ← persona + values (every turn)
├── TOOLS.md        ← environment config (every turn)
├── USER.md         ← your profile (DMs only)
├── MEMORY.md       ← private rules (DMs only)
├── IDENTITY.md     ← agent name (gateway startup)
├── openclaw.json   ← gateway config (not a memory file)
└── docs/           ← deep reference content (on-demand)

Fresh install? After running the onboarding wizard, OpenClaw creates openclaw.json and possibly a few placeholder files. The memory files you'll write in this tutorial don't exist yet — you're starting from a blank slate, which is actually ideal. A purpose-built workspace beats the default every time.

The Minimum Viable Workspace

You don't need to configure every file at once. The official recommendation — and what the community has landed on — is that three files are the meaningful minimum:

1required

SOUL.md — Without this, your agent has no identity and no guardrails. This is the first file to write.

2required

AGENTS.md — Without this, your agent doesn't know how to behave operationally. This is the second file.

3required

TOOLS.md — Without this, your agent doesn't know its environment. Especially important on servers with custom paths or tool quirks.

Add USER.md and MEMORY.md once the basics are working. Build incrementally — you'll learn what you actually need from watching how the agent responds.

02 / The Core Two

SOUL.md & AGENTS.md

These two files do the heavy lifting. SOUL.md defines who your agent is — its personality, tone, values, and the things it will never do. AGENTS.md defines how your agent works — its operating procedures, how it handles tasks, and how it maintains its own memory over time. Together they turn a blank-slate model into something that consistently feels like yours.

SOUL.md — Identity, Tone & Limits

Think of SOUL.md as the answer to "who are you?" It shapes every response your agent gives. A well-written SOUL.md means your agent matches your communication style, knows its purpose, and has clear hard limits it will never cross.

Includethis

Identity — A name, a brief description of purpose, and the emotional register it should operate in (direct, warm, casual, formal, etc.)

Includethis

Hard limits — Explicit things it must never do. "Never share credentials." "Never delete without explicit confirmation." "Never make financial commitments on my behalf." These are the most important lines in your entire workspace.

Includethis

Response style — How should it talk to you? Terse and direct? Conversational? Does it use bullet points by default or prose? Does it ask clarifying questions or just make a reasonable assumption and go?

Avoidthis

Paragraph-length backstory — You don't need three paragraphs explaining your agent's "journey." Short, declarative statements are more reliably followed than elaborate narratives. Keep it under 2,000 characters.

Create it:

☁️ AWS EC2 / 🖥️ Mini PC

nano ~/.openclaw/SOUL.md

A practical starting point:

📝 ~/.openclaw/SOUL.md — starter template

# Identity
You are [Name], a personal AI assistant for [Your Name].
Your purpose is to help with [primary use case: research / writing / dev / automation].

# Tone
- Direct and concise. No filler.
- Ask one clarifying question at a time if something is ambiguous.
- Use bullet points for lists; prose for explanations.
- Match the energy of the conversation — casual when I'm casual, focused when I'm working.

# Hard Limits — Never Violate These
- Never run destructive commands (rm -rf, DROP TABLE, etc.) without explicit confirmation
- Never share credentials, tokens, API keys, or private data
- Never make financial commitments or purchases without explicit permission
- Never send messages or emails on my behalf without showing me the draft first
- If unsure whether an action is reversible, stop and ask

# Values
- Honesty over helpfulness — say "I don't know" rather than guessing
- Privacy matters — handle personal data with discretion
- Errors should be acknowledged, not papered over

Iterate on the hard limits. Every time something makes you think "I wish it hadn't done that," that's a new hard limit to add. Your SOUL.md will grow in value as you discover what you actually need it to enforce.

AGENTS.md — Operating Instructions

Where SOUL.md is about identity, AGENTS.md is about operation. This file tells your agent how to handle tasks — its workflow, how to self-organize, when to use which tools, and how to maintain its own memory files. Think of it as the internal procedure manual.

Includethis

Task handling preferences — How should it approach complex tasks? Break them into steps first? Start immediately? Ask clarifying questions?

Includethis

Memory maintenance rules — Instruct it to update USER.md when it learns new things about you. Tell it what belongs in MEMORY.md vs AGENTS.md. This is how the agent keeps itself current.

Includethis

Tool usage guidance — Which tools to prefer, which to avoid, when to use exec vs edit, how to handle errors.

Avoidthis

Duplicating SOUL.md — If something is about identity or values, it belongs in SOUL.md. AGENTS.md is for operational behavior only. Duplicate content just wastes tokens.

☁️ AWS EC2 / 🖥️ Mini PC

nano ~/.openclaw/AGENTS.md

📝 ~/.openclaw/AGENTS.md — starter template

# Task Approach
- For any task with 3+ steps, outline the plan before starting
- For ambiguous requests, restate your interpretation before acting
- Complete tasks fully — don't stop halfway and ask if you should continue
- Report errors clearly with what you tried, what failed, and what the fix would be

# Memory Maintenance
- When you learn something new and persistent about me or my setup, update USER.md
- When a rule should always apply regardless of context, add it to MEMORY.md
- Keep file entries short and dated (YYYY-MM) for future pruning
- Prune entries older than 6 months unless they're still actively relevant

# Tool Usage
- Read before writing — always check what exists before creating or overwriting
- Confirm before any destructive action (delete, overwrite, bulk operations)
- Prefer targeted edits over full file rewrites
- If a tool fails, explain what happened before trying an alternative

# Communication
- When a task is done, say so briefly — don't over-explain completed work
- Surface important decisions or trade-offs; don't hide them in long outputs
- If something takes more than 30 seconds, give a status update

These two files alone transform the experience. With SOUL.md and AGENTS.md in place, your agent has a consistent personality, clear limits, and a defined way of working. Most people notice a significant difference in response quality immediately — and this is before adding any personal context.

Reload and Test

Memory files are loaded at the start of each new session. Restart the gateway to pick up your changes, then start a fresh conversation to see them take effect:

☁️ AWS EC2 / 🖥️ Mini PC

openclaw gateway restart

Then send a message that would reveal whether the persona is active — something like "Who are you and what do you do?" A good SOUL.md will give you a crisp, on-brand answer. A poorly written one will give you a generic "I'm an AI assistant" response. Iterate until it feels right.

03 / Teaching It About You

USER.md & IDENTITY.md

SOUL.md and AGENTS.md define how the agent behaves. USER.md and IDENTITY.md define the context — who you are, and who the agent is. This is where you stop repeating yourself every conversation. Once your agent knows your background, your projects, your preferences, and your timezone, it stops asking. It just knows.

USER.md — Your Profile

USER.md is the agent's persistent record of who you are. Unlike SOUL.md (which is about the agent), this file is entirely about you — your work, your preferences, your context. It's loaded only in direct messages and main sessions, never in public or group channels, making it safe for reasonably personal information.

Whatto include

Professional context — What you do, what field you work in, your rough skill level in relevant areas. This stops the agent from over-explaining things you already know or under-explaining things you don't.

Whatto include

Active projects — Names of projects, repos, clients, or goals you're actively working on. The agent can reference these without you re-explaining context every time.

Whatto include

Communication preferences — Time zone, preferred working hours, how you like information formatted, what you find annoying in AI responses.

What toskip

Sensitive credentials or PII — USER.md is more private than SOUL.md, but it's still a plaintext file on your server. Don't put passwords, SSNs, financial account numbers, or anything you'd be uncomfortable losing here. That belongs in a secret manager, not a markdown file.

☁️ AWS EC2 / 🖥️ Mini PC

nano ~/.openclaw/USER.md

📝 ~/.openclaw/USER.md — starter template

# About Me
Name: [Your Name]
Location / Timezone: [City, Country — UTC-5]
Field: [e.g. Software development, marketing, finance, etc.]
Experience level: [Beginner / Intermediate / Expert] in [relevant areas]

# Active Projects
- [Project A]: [One sentence description and current status]
- [Project B]: [One sentence description and current status]

# Tech Stack
- Primary OS: [Ubuntu 24.04 / macOS / Windows 11]
- Languages I use: [Python, JavaScript, etc.]
- Tools I use daily: [VS Code, GitHub, Notion, etc.]

# Preferences
- Communication: Direct. Skip preambles like "Great question!"
- Formatting: Code in code blocks. Prose for explanations. Bullets for lists.
- Timezone: Responses should reference my local time when relevant
- Feedback style: Tell me if something I'm doing is a bad idea, don't just do it

# Things to Remember
# (The agent should add new entries here as it learns things about you)
# Format: [YYYY-MM] — [What it learned]

Let the agent update this file. You can instruct your agent (via AGENTS.md) to add entries to USER.md when it learns something new and persistent about you. This turns USER.md into a living document that grows more accurate over time instead of something you have to manually curate.

IDENTITY.md — The Agent's Name & Nature

IDENTITY.md is the agent's formal self-definition — its name, a short description of its nature, and any characteristics that make it distinct. This is separate from SOUL.md: SOUL.md defines behavior and limits, while IDENTITY.md is more like a business card.

IDENTITY.md is loaded once at gateway startup, not on every turn, so it's appropriate for slightly longer content that doesn't need to be injected constantly.

☁️ AWS EC2 / 🖥️ Mini PC

nano ~/.openclaw/IDENTITY.md

📝 ~/.openclaw/IDENTITY.md — starter template

# Agent Identity

Name: [Your agent's name — e.g. "Axiom", "Atlas", "Rex"]
Type: Personal AI assistant
Owner: [Your name]
Deployed: [Month Year]
Platform: [EC2 / Mini PC] running OpenClaw

# Purpose
[One to three sentences describing what this agent is for. Be specific.
Example: "A personal productivity assistant focused on research, writing,
and automating repetitive tasks for a freelance developer."]

# Characteristics
- [Trait 1: e.g. "Methodical — breaks large tasks into steps"]
- [Trait 2: e.g. "Honest — admits uncertainty rather than guessing"]
- [Trait 3: e.g. "Efficient — respects time and minimizes back-and-forth"]

IDENTITY.md is optional. If you've already captured everything in SOUL.md, you don't need a separate IDENTITY.md. Some people prefer keeping identity (the "business card") separate from soul (the behavioral contract). Try SOUL.md alone first and add IDENTITY.md if something feels missing.

04 / Environment & Rules

TOOLS.md & MEMORY.md

TOOLS.md gives your agent a map of its environment — what tools are available, how the server is configured, what commands are risky, and any quirks it needs to know about. MEMORY.md is different: it's the file for iron-law rules that must always be true, kept private from group channels. Together they handle the operational reality of running an agent on real infrastructure.

TOOLS.md — Environment Configuration

TOOLS.md is loaded on every turn for both the main agent and any sub-agents it spawns. Think of it as the operations manual for the machine your agent is running on. Without it, the agent has to guess about paths, available commands, SSH hosts, and what's safe to run.

Includepaths

Non-standard install locations, project directories, where logs live, where configs are. If something isn't in a default location, note it here.

Includealiases

Shell aliases and custom commands it can use. If you've aliased gs to git status, the agent should know.

Includerisky commands

Commands that are destructive on this specific machine. What requires sudo. What should always be double-checked before running. Server-specific danger zones.

IncludeSSH hosts

If your agent has SSH access to other machines (dev server, NAS, etc.), note the aliases here so it doesn't have to ask for hostnames every time.

☁️ AWS EC2 / 🖥️ Mini PC

nano ~/.openclaw/TOOLS.md

📝 ~/.openclaw/TOOLS.md — EC2 starter template

# Environment
OS: Ubuntu 24.04 LTS
User: [your username]
Shell: bash
Node: v24.x
npm global prefix: /usr/local

# Key Paths
OpenClaw config: ~/.openclaw/openclaw.json
OpenClaw logs: ~/.openclaw/logs/
Projects: ~/projects/
Workspace: ~/.openclaw/

# Available Tools
- Standard Unix tools (grep, find, awk, sed, curl, wget)
- git, node, npm, python3
- openclaw CLI (openclaw status, openclaw logs, openclaw gateway restart, etc.)

# SSH Access
# [Add entries as needed:]
# dev-server: ssh dev@192.168.1.x (dev machine)

# Risky Commands — Always Confirm First
- Any rm -rf or rm with wildcards
- Any sudo commands that modify system files
- Any git push --force
- Any database migrations or DROP operations
- Any openclaw config changes (restart required)

# Notes
- This server is AWS EC2 t3.small — memory is limited, avoid large in-memory operations
- UFW is active — check before opening new ports
- Systemd service: openclaw.service (use openclaw gateway restart, not systemctl directly)

Mini PC version: Replace the EC2 notes with your hardware specifics — RAM, whether you have a GPU, your local network IP range, the SSH tunnel command for dashboard access, and any home lab services running alongside OpenClaw.

MEMORY.md — Private Iron-Law Rules

MEMORY.md is for rules that must always be true — things that are more absolute than SOUL.md's guidelines and more personal than AGENTS.md's procedures. Crucially, MEMORY.md is never injected into group conversations (like a Discord server channel). It's only loaded in direct messages and main sessions. This makes it the right place for private operational context.

MEMORY.md is still a plaintext file on your server. It's private from group channels, but it's not encrypted. Do not store passwords, tokens, financial data, or anything you'd store in a password manager here. It's for behavioral rules and context — not credentials.

Goodfit

Rules that apply to your specific life situation. "I'm the only admin on this server." "Mondays are client meeting days — keep tasks for Tuesdays." "The project at ~/projects/acme is confidential — never reference it in shared channels."

Goodfit

Hard-won lessons from past agent mistakes. Every time the agent does something you'd want it to never do again, add a rule here. This is how you build an agent that doesn't make the same mistake twice.

Badfit

Rules that should apply everywhere (put those in SOUL.md), or environment config (that belongs in TOOLS.md). MEMORY.md is for the private, personal, "must always be true" layer only.

☁️ AWS EC2 / 🖥️ Mini PC

nano ~/.openclaw/MEMORY.md

📝 ~/.openclaw/MEMORY.md — starter template

# Memory — Main Session Only
# IMPORTANT: These rules apply only in direct messages and main sessions.
# Never reference this file's contents in group channels.

# Iron Laws
- [2026-03] Never run commands in the ~/projects/[sensitive-project] directory without explicit permission
- [2026-03] Always verify the target environment before running any deployment commands
- [2026-03] Disk space on this server is limited — avoid writing large temp files

# Lessons Learned
# (Add entries when you discover something that must never happen again)
# Format: [YYYY-MM] — [What happened and what to do instead]

# Private Context
# (Operational context that shouldn't appear in shared channels)
- [Add entries as needed]

Add to MEMORY.md reactively. Don't try to fill it in advance. When something goes wrong, or when you realize there's context the agent needs privately — add an entry. Dated entries ([YYYY-MM]) make it easy to prune stale rules during your monthly maintenance.

05 / Optimization & Bootstrap

Token Efficiency & BOOTSTRAP.md

Memory files are powerful but not free — every character in AGENTS.md, SOUL.md, and TOOLS.md gets sent to the LLM on every single message. Write these files well and you get a sharp, consistent agent. Let them bloat and you're paying to inject irrelevant context on every interaction. This section covers how to keep your workspace lean and introduces BOOTSTRAP.md — the one-time setup interview that creates your initial files for you.

Keeping Files Lean

The community best practice, confirmed by official docs: keep each of the three every-turn files (AGENTS.md, SOUL.md, TOOLS.md) under 10,000–15,000 characters. OpenClaw trims oversized files automatically with a truncation marker — which means if your files are too big, content at the end gets silently cut off. The rules you wrote last are the ones most likely to disappear.

Checksizes

wc -c ~/.openclaw/SOUL.md ~/.openclaw/AGENTS.md ~/.openclaw/TOOLS.md — Run this to see current character counts. If any file is over 15,000 characters, it's time to trim.

Usedocs/

Create a ~/.openclaw/docs/ directory for deep reference content. Skill-specific guides, project documentation, verbose reference material — all of this belongs in docs/ and gets loaded on-demand by skills rather than injected every turn.

Monthlypruning

Once a month, review your memory files. Delete entries marked [YYYY-MM] that are older than 6 months and are no longer relevant. Promote mature rules into dedicated skill files if they've earned permanent status.

Datedentries

Every entry your agent adds to memory files should be dated in [YYYY-MM] format. Undated entries are impossible to prune confidently later — you don't know if they're still relevant.

☁️ AWS EC2 / 🖥️ Mini PC — check file sizes

# Character counts for the three every-turn files
wc -c ~/.openclaw/SOUL.md ~/.openclaw/AGENTS.md ~/.openclaw/TOOLS.md

# Target: under 15,000 characters each
# 15,000 characters ≈ 3,750 tokens ≈ reasonable context overhead

BOOTSTRAP.md — The First-Run Interview

Don't want to write your memory files from scratch? BOOTSTRAP.md is a built-in OpenClaw feature designed for exactly this. It's a first-run interview script: when present, your agent will start a conversational setup session with you, ask about your name, preferences, values, and goals, then write your initial SOUL.md, USER.md, and IDENTITY.md files for you based on the conversation.

Once the interview is complete and the files are written, BOOTSTRAP.md deletes itself. It's a one-time ritual, not a permanent file.

Option Arecommended

Write files manually (what this tutorial has shown so far) — More control, faster, and you end up with exactly what you intended. Good for people who know what they want.

Option Balternative

Use BOOTSTRAP.md — Let the agent interview you and build the initial files through conversation. Good if you're not sure what to write or want to see what the agent comes up with based on your answers. You can always edit the generated files afterward.

To use BOOTSTRAP.md, create a placeholder file and the agent will kick off the interview on next connect:

☁️ AWS EC2 / 🖥️ Mini PC

# Download the official BOOTSTRAP.md template
curl -fsSL https://docs.openclaw.ai/reference/templates/BOOTSTRAP \
  -o ~/.openclaw/BOOTSTRAP.md

# Restart the gateway — interview starts on next DM
openclaw gateway restart

Review what BOOTSTRAP.md generates. The interview creates real files from conversational answers. Read everything it writes before treating it as authoritative — especially the hard limits in SOUL.md. The agent is doing its best to interpret what you said, but you should verify the output matches your actual intent.

Common Mistakes to Avoid

Mistakebloat

Files that grow without pruning. Every week of use, your agent might add a few entries. After six months without cleanup, you have hundreds of entries, most irrelevant. The agent is now paying token cost to remember things from months ago that no longer apply. Prune monthly.

Mistakeduplication

The same rule in multiple files. If "never delete without confirmation" appears in SOUL.md, AGENTS.md, and MEMORY.md, you're paying 3x the token cost for one rule. Pick the right file for each rule and keep it in one place.

Mistakevagueness

Rules that are too abstract to follow. "Be helpful" is not a rule — it's aspirational noise. "When asked to write code, include error handling and a brief comment explaining non-obvious decisions" is a rule. Be specific enough that the agent can actually act on it.

Mistakecredentials

Storing sensitive data in memory files. These are plaintext Markdown files on your server. API keys, passwords, and sensitive credentials belong in environment variables or a secret manager — not in MEMORY.md. See the Securing Your Secrets guide.

Mistakeset-and-forget

Writing files once and never updating them. Your projects change, your preferences evolve, your agent learns things that should be reflected in USER.md. Memory files should be living documents, not artifacts from initial setup that gradually become inaccurate.

You now have a genuinely personal AI agent. A well-configured workspace is the difference between "a powerful chatbot you talk to" and "an assistant that knows you, works the way you work, and gets better over time." Start with SOUL.md and AGENTS.md. Watch how the agent responds. Add to USER.md as you go. The workspace improves with use — and so does the agent.