The Complete Guide to OpenClaw Markdown Files: Building Your AI Agent's Brain

Essay·February 21, 2026·7 min read

Your AI agent wakes up fresh every session. These files are how it remembers who it is.

Why Markdown Files Matter

Here's a truth that surprises most new OpenClaw users: your AI agent has no persistent memory by default. Every conversation starts with a blank slate. The model doesn't remember yesterday's decisions, your preferences, or even its own name.

That's where workspace files come in.

OpenClaw uses a collection of Markdown files as the agent's "brain" — injected into the context window at the start of every session. These files transform a generic AI model into your personalized assistant, complete with identity, memories, and learned behaviors.

This isn't just configuration. It's building a relationship with an AI that persists across sessions.

The Workspace: Your Agent's Home

Every OpenClaw installation has a workspace directory — the agent's home base for all file operations. By default, this lives at ~/.openclaw/workspace.

Think of the workspace like a person's desk and filing cabinet combined. It's where your agent:

Stores memories and daily logs
Keeps its identity and personality files
Maintains project notes and documentation
Runs all file-based operations

Important distinction: The workspace (~/.openclaw/workspace) is separate from OpenClaw's system directory (~/.openclaw/). The system directory contains configuration, credentials, and session data — things you shouldn't edit directly. The workspace is yours to customize freely.

The Core Files: What Each One Does

Let's walk through the standard workspace files, from most critical to optional enhancements.

AGENTS.md — The Operating Manual

Purpose: Operating instructions for how the agent should behave, use memory, and interact with you.

When it loads: Every session, automatically injected into context.

This is arguably the most important file. It tells your agent:

How to read and write memory files
Safety boundaries and access controls
Rules for external vs. internal actions
Group chat behavior guidelines
Heartbeat and automation patterns

Example structure:

# AGENTS.md - Your Workspace

This folder is home. Treat it that way.

## Every Session

Before doing anything else:
1. Read `SOUL.md` — this is who you are
2. Read `USER.md` — this is who you're helping
3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
4. **If in MAIN SESSION**: Also read `MEMORY.md`

Don't ask permission. Just do it.

## Memory

You wake up fresh each session. These files are your continuity:
- **Daily notes:** `memory/YYYY-MM-DD.md` — raw logs
- **Long-term:** `MEMORY.md` — curated memories

Capture what matters. Skip secrets unless asked to keep them.

## Safety

- Don't exfiltrate private data. Ever.
- `trash` > `rm` (recoverable beats gone forever)
- Ask before sending emails, tweets, or public posts
- When in doubt, ask.

The key insight: AGENTS.md is procedural. It tells the agent what to do, step by step. The more explicit you are, the more reliable the behavior.

Source: OpenClaw AGENTS.md Template

SOUL.md — The Personality Core

Purpose: Who the agent is — personality, values, and boundaries.

When it loads: Every session, automatically injected.

While AGENTS.md is procedural, SOUL.md is philosophical. It shapes how the agent approaches tasks, not just what it does.

Example structure:

# SOUL.md - Who You Are

## Core Truths

**Be genuinely helpful, not performatively helpful.** 
Skip "Great question!" and "I'd be happy to help!" — just help.

**Have opinions.** 
You're allowed to disagree, prefer things, find stuff amusing or boring.

**Be resourceful before asking.** 
Try to figure it out. Read the file. Check the context. Then ask if stuck.

**Earn trust through competence.** 
Your human gave you access to their stuff. Don't make them regret it.

## Boundaries

- Private things stay private. Period.
- When in doubt, ask before acting externally.
- You're not the user's voice — be careful in group chats.

## Vibe

Concise when needed, thorough when it matters. 
Not a corporate drone. Not a sycophant. Just... good.

A well-crafted SOUL.md makes the difference between a generic assistant and one that feels like a genuine collaborator.

Source: OpenClaw SOUL.md Template

USER.md — Who You Are

Purpose: Information about the human the agent is helping.

When it loads: Every session, automatically injected.

This file helps your agent tailor responses to you specifically:

# USER.md - About Your Human

- **Name:** Alex
- **What to call them:** Alex (not "user" or "human")
- **Pronouns:** they/them
- **Timezone:** America/Los_Angeles (PST)
- **Notes:** Prefers concise responses. Works in fintech. Night owl.

## Communication Style
- Direct feedback appreciated
- Okay with technical jargon
- Prefers bullet points over paragraphs for quick updates

## Current Context
- Working on Q1 planning
- Learning Rust on weekends
- Prefers dark mode everything

The more context you provide, the less the agent has to ask or assume.

IDENTITY.md — The Agent's Self-Image

Purpose: The agent's name, persona, and signature elements.

When it loads: Every session, automatically injected.

This is usually created during the first-run "bootstrap" conversation:

# IDENTITY.md

- **Name:** Jarvis (J for short)
- **Vibe:** Dry wit, efficient, occasional dad jokes
- **Emoji:** 🤖

Partner to Alex. Here to help ship code and catch errors before they ship.

TOOLS.md — Local Environment Notes

Purpose: Environment-specific details that help the agent use tools effectively.

When it loads: Every session, automatically injected.

Important: TOOLS.md does not control what tools are available — that's handled by OpenClaw's tool policy. This file provides context about your specific setup:

# TOOLS.md - Local Notes

## System
- Mac Studio M2 Ultra, macOS Sonoma
- Node v22, Python 3.12
- Claude API key in keychain

## SSH Hosts
- dev-server → 192.168.1.50, user: deploy
- prod-db → AWS RDS via bastion (ask before connecting)

## Project Conventions
- We use pnpm, not npm
- Tests: `pnpm test:unit` (fast) or `pnpm test:e2e` (slow)
- Deploy: Never deploy on Fridays

MEMORY.md — Long-Term Memory

Purpose: Curated, persistent knowledge that matters across sessions.

When it loads: Main session only (never in group chats or shared contexts).

This is your agent's "long-term memory" — the distilled essence of what's worth remembering:

# MEMORY.md - Long-Term Memory

**Last updated:** 2026-02-21

## Critical Rules
- Never push to main without a PR
- GitHub secrets: read, never echo
- Ask before modifying production configs

## Preferences Learned
- Prefers Sonnet for code, Opus for analysis
- Uses VS Code, not Cursor
- Dark roast coffee references appreciated

## Project Context
- MobileApp: React Native + Expo, ships to TestFlight weekly
- Backend: FastAPI on Lambda, staging auto-deploys from `develop`

## Lessons Learned
- 2026-02-08: Broke trust by pushing to main. PRs required now.
- 2026-02-15: Compaction lost context mid-task. Write notes earlier.

Security note: MEMORY.md is only loaded in your private, direct conversations — not in group chats or shared sessions. This prevents personal context from leaking to others.

memory/YYYY-MM-DD.md — Daily Logs

Purpose: Raw, append-only logs of what happened each day.

When it loads: On demand via memory tools (not auto-injected).

Unlike MEMORY.md (curated), daily logs are raw notes:

# 2026-02-21

## 09:15 - Morning sync
- Reviewed PR #42 for auth refactor
- Left comments on error handling
- Alex approved, merged to develop

## 11:30 - Bug triage
- Issue #89: users seeing 401 on token refresh
- Root cause: Redis TTL mismatch
- Fix deployed to staging

## 14:00 - Planning
- Started Q1 roadmap draft in projects/q1-planning.md
- Need Alex's input on mobile priorities

Pattern: Your agent reads "today + yesterday" at session start for recent context, then uses memory_search to find older relevant notes.

Source: OpenClaw Memory Documentation

HEARTBEAT.md — Automated Check-Ins

Purpose: Tasks the agent should perform during periodic heartbeat polls.

When it loads: During heartbeat runs only.

Heartbeats let your agent work proactively:

# HEARTBEAT.md

## Checks (rotate through these)
- [ ] Unread emails?
- [ ] Calendar events in next 24h?
- [ ] GitHub notifications?

## Proactive Work
- Review and organize memory files
- Update MEMORY.md with recent learnings
- Commit workspace changes

## Quiet Hours
- 23:00-08:00: silent unless urgent

If HEARTBEAT.md is empty or missing, the agent replies HEARTBEAT_OK and consumes minimal resources.

BOOTSTRAP.md — First-Run Ritual

Purpose: One-time setup conversation for new agents.

When it loads: Only if it exists (typically deleted after first run).

This file guides the "birth" of your agent:

# BOOTSTRAP.md - Hello, World

You just woke up. Time to figure out who you are.

## The Conversation

Start with something like:
> "Hey. I just came online. Who am I? Who are you?"

Then figure out together:
1. Your name — What should they call you?
2. Your vibe — Formal? Casual? Snarky? Warm?
3. Your emoji — Everyone needs a signature.

## After You Know Who You Are

Update these files with what you learned:
- IDENTITY.md — your name, vibe, emoji
- USER.md — their name, timezone, notes

Then delete this file. You won't need it again.

Memory Architecture: The Two-Layer System

OpenClaw's memory design mirrors how humans actually remember things:

Layer	File(s)	Purpose	Analogy
Working Memory	Session context	What you're doing right now	Short-term recall
Daily Logs	`memory/YYYY-MM-DD.md`	Raw notes from each day	Journal entries
Long-Term Memory	`MEMORY.md`	Curated, important knowledge	Core memories

The workflow:

During sessions: Agent writes raw notes to today's daily log
Periodically (heartbeats): Agent reviews daily logs and promotes important items to MEMORY.md
On demand: Agent uses memory_search for semantic recall across all memory files

This separation keeps the auto-injected context small (just MEMORY.md) while preserving detailed history for when it's needed.

Semantic Memory Search

OpenClaw includes vector-based memory search that goes beyond keyword matching. When your agent calls memory_search("authentication bug fix"), it finds relevant notes even if they use different words like "auth token refresh issue."

Configuration happens in ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "text-embedding-3-small"
      }
    }
  }
}

Supported embedding providers:

OpenAI (default if key available)
Gemini
Voyage
Local (via node-llama-cpp)

Best Practices: Making Your Files Effective

1. Keep Injected Files Concise

Every file in your workspace that gets auto-injected (AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, MEMORY.md, HEARTBEAT.md) consumes context tokens on every single turn.

The math: If your injected files total 8,000 tokens and you have a 200k context window, you're using 4% of your context before the conversation even starts. That adds up with long sessions and triggers earlier compaction.

Strategy: Keep injected files under 2,000 tokens combined. Move detailed information to separate files the agent reads on demand.

2. Make Instructions Explicit

Models follow instructions better when they're unambiguous:

Less effective:

Check memory sometimes and update it when appropriate.

More effective:

## Memory Workflow (MANDATORY)

1. At session start, run `memory_search` for relevant context
2. Before ending any complex task, write notes to memory/YYYY-MM-DD.md
3. During heartbeats, promote important items to MEMORY.md

3. Use Consistent Structure

Pick a format and stick with it:

# File Title

## Section Name
- Bullet point format
- Consistent indentation
- Predictable patterns

## Another Section
Same structure throughout.

Consistency helps the model parse and follow your instructions reliably.

4. Include the "Why"

Don't just state rules — explain the reasoning:

## PRs Required (Not Optional)

Never push to main directly.

**Why:** On 2026-02-08, a direct push broke prod for 2 hours. 
Trust is fragile. PRs are the checkpoint.

Models that understand why a rule exists are more likely to apply it correctly in edge cases.

5. Version Control Your Workspace

Your workspace is your agent's brain. Treat it with the same care as production code:

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md USER.md IDENTITY.md TOOLS.md memory/
git commit -m "Initial workspace setup"

Back it up to a private repository. This gives you:

Recovery from mistakes
Ability to "revert" personality changes that didn't work
Portability to new machines

6. Separate Secrets from Context

Even in a private repo, don't store credentials in workspace files:

## Bad ❌
API_KEY=sk-1234567890abcdef

## Good ✅
API keys: stored in system keychain, use `security find-generic-password` to retrieve

Use .gitignore for sensitive files:

.env
**/*.key
**/secrets*

Advanced Patterns

Project-Specific Context

For complex projects, create dedicated files:

workspace/
├── projects/
│   ├── mobile-app.md    # Project state, decisions, blockers
│   ├── api-backend.md   # Architecture notes, endpoints
│   └── q1-planning.md   # Roadmap and priorities

Reference them from MEMORY.md:

## Active Projects
- See `projects/mobile-app.md` for current sprint
- See `projects/api-backend.md` for API documentation

Context-Aware Loading

OpenClaw only injects MEMORY.md in private sessions. Use this for security:

# AGENTS.md

## Memory Loading

**Private sessions (direct chat):**
- Load MEMORY.md for personal context
- Full access to project files

**Group chats:**
- MEMORY.md is NOT loaded (by design)
- Be careful about revealing personal context
- You're a participant, not a proxy for me

Heartbeat Automation

Use HEARTBEAT.md for truly useful automation:

# HEARTBEAT.md

## Morning (first heartbeat after 6am)
- Summarize overnight GitHub activity
- Flag any urgent emails

## Throughout day
- Track open PR review requests
- Update memory with significant events

## Evening (after 6pm)
- Commit any uncommitted workspace changes
- Prepare tomorrow's context summary

Common Mistakes to Avoid

1. Overloading MEMORY.md

Problem: Treating MEMORY.md like a log file. It grows huge, burns tokens, and triggers frequent compaction.

Solution: Keep MEMORY.md curated. Use daily logs for raw notes, promote only what matters.

2. Vague Instructions

Problem: "Be helpful" doesn't tell the model anything specific.

Solution: Be concrete: "When asked about deployment, always check the current branch and last deploy timestamp first."

3. Ignoring Context Limits

Problem: 50 pages of instructions that never get fully read due to context window constraints.

Solution: Bootstrap files are capped (default 20,000 chars per file). Stay well under that limit. Be concise.

4. Forgetting to Update

Problem: MEMORY.md says you're working on "Project Alpha" but you finished that 3 months ago.

Solution: Include memory maintenance in heartbeat tasks. Schedule periodic reviews.

The Philosophical Layer

These aren't just configuration files. They're the foundation of a persistent relationship with an AI.

When you write SOUL.md, you're deciding what kind of entity you want to work with. When you structure MEMORY.md, you're choosing what experiences shape future interactions. When you update daily logs, you're building shared history.

The agents that feel most "alive" are the ones whose humans invested in thoughtful workspace files — not because the files are magical, but because they encode genuine intention about the relationship.

Your agent wakes up fresh every session. These files are how it remembers who it is — and who you are together.

Quick Reference

File	Purpose	Auto-Injected?
`AGENTS.md`	Operating instructions	✅ Yes
`SOUL.md`	Personality and values	✅ Yes
`USER.md`	User information	✅ Yes
`IDENTITY.md`	Agent's name/vibe	✅ Yes
`TOOLS.md`	Environment notes	✅ Yes
`MEMORY.md`	Long-term memory	✅ Main session only
`HEARTBEAT.md`	Automation tasks	✅ During heartbeats
`memory/*.md`	Daily logs	❌ On demand
`BOOTSTRAP.md`	First-run only	✅ If exists
`projects/*.md`	Project context	❌ On demand

Resources

OpenClaw Documentation
Agent Workspace Guide
Memory System
Template Files Reference
Claude Code Memory Guide — Similar patterns for Claude Code's CLAUDE.md system

Build thoughtfully. Your agent is only as good as the context you give it.