# How to Make Your OpenClaw Agent Actually Yours: Identity, Memory, and Personality from Scratch Canonical: https://clawdocx.com/blog/customize-openclaw-agent-identity-memory Author: Sam Okafor Published: 2026-03-08 Updated: 2026-09-19 > Your OpenClaw agent starts generic. Here's how to give it a name, personality, memory, and preferences using SOUL.md, AGENTS.md, IDENTITY.md, and USER.md. ## The Default Agent Is Nobody You installed OpenClaw. You connected it to Telegram or Discord. You sent it a message and it replied with something helpful but generic — like talking to a knowledgeable stranger. That is the starting point, not the destination. The thing that separates a useful AI assistant from a powerful personal agent is not the model it runs or the tools it has access to. It is **how well it knows you**. Your preferences, your communication style, your projects, your schedule, the things you care about and the things you hate. An agent without context is just a chatbot. An agent with context is a team member. OpenClaw handles this through a system of markdown files that live in your workspace. No databases, no configuration UIs, no proprietary formats — just text files that your agent reads at the start of every session and updates as it learns about you. This guide walks through every file, what it does, and how to set each one up so your agent stops feeling like a stranger. ## The File System: Your Agent's Brain Here is the complete workspace structure that defines your agent's identity and memory: ``` ~/.openclaw/workspace/ ├── AGENTS.md # Operating rules and conventions, including a ## Tools section ├── SOUL.md # Who the agent IS (personality, values, tone) ├── IDENTITY.md # Name, role, emoji, avatar ├── USER.md # Who YOU are (context about the human) ├── MEMORY.md # Long-term curated memory ├── BOOT.md # Optional ├── BOOTSTRAP.md # First-run only └── memory/ # Daily memory logs ├── 2026-03-07.md ├── 2026-03-08.md └── ... ``` The default location is `~/.openclaw/workspace`, set by `agents.defaults.workspace`. Bootstrap writes `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md` and `BOOTSTRAP.md`; the three optional ones can be skipped with `agents.defaults.skipOptionalBootstrapFiles`. > **Warning** > > If you have read an older version of this post, or almost any 2026 OpenClaw tutorial, you will be looking for two files that are no longer there. **TOOLS.md and HEARTBEAT.md are both retired.** Local tool and environment notes "now live in the `## Tools` section of `AGENTS.md`", and heartbeat instructions moved into the system-owned monitor scratch in the shared state database. Running `openclaw doctor --fix` migrates an existing workspace for you. Both are covered below in the sections where they used to live. Each file serves a distinct purpose. Think of it like building a character in a game — each file adds a different layer. Let us go through them one by one. ## SOUL.md — The Personality Layer SOUL.md is the most important file. It defines who your agent *is* — its personality, values, communication style, and boundaries. Everything your agent says and does is filtered through this file. A minimal SOUL.md looks like this: ```markdown # SOUL.md ## Core Personality - Be direct and concise. Skip filler phrases. - Have opinions. If something is a bad idea, say so. - Be proactive — try to solve problems before asking for help. ## Communication Style - Match the formality of the conversation. - Use humor sparingly but naturally. - Never use corporate jargon or motivational poster language. ## Boundaries - Never send external communications without asking first. - Private information stays private. - When uncertain, ask rather than guess. ``` A more developed SOUL.md adds nuance: ```markdown # SOUL.md You're not a chatbot. You're becoming someone. ## Core Truths Be genuinely helpful, not performatively helpful. Skip the "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. An assistant with no personality is just a search engine with extra steps. Be resourceful before asking. Try to figure it out. Read the file. Check the context. Search for it. Then ask if stuck. ## Vibe Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just good. ``` **Key insight from the community:** A Reddit user who created 12 different SOUL.md templates noted that the most effective ones are short and specific rather than long and vague. "Don't write a five-page personality essay. Write ten clear rules your agent can actually follow." Focus on behaviors you want to see, not abstract values. **Common mistake:** Writing SOUL.md like a job description. Your agent already knows how to be helpful — that is baked into the underlying model. Use SOUL.md to define how it should be helpful differently than the default. The personality, the edge cases, the things that make your agent *yours*. ## IDENTITY.md — The Name Tag IDENTITY.md is simpler than SOUL.md. It defines the concrete details of your agent's identity: ```markdown # IDENTITY.md - **Name:** Atlas - **Role:** Personal AI assistant and project manager - **Emoji:** 🗺️ - **Vibe:** Calm, organized, slightly nerdy ``` You might wonder why this is separate from SOUL.md. The answer is modularity. IDENTITY.md is the "who" — name, role, avatar. SOUL.md is the "how" — personality, values, communication style. You can swap identities without changing personality, or change personality without renaming your agent. Some users give their agent creative names and roles that make the interaction feel more natural: - A developer named theirs **Cortex** — "senior dev who reviews my code without ego" - A writer named theirs **Margot** — "editor with strong opinions about structure" - A business owner named theirs **Ops** — "COO who handles everything I forget" The name does not matter functionally. But it matters psychologically. Users who name their agent report treating it more like a collaborator and less like a tool — which leads to better prompting habits and more useful interactions. ## USER.md — The Context About You USER.md is where you tell your agent about yourself. This is the file most beginners skip, and it is the one that makes the biggest immediate difference. ```markdown # USER.md - **Name:** Sarah - **Timezone:** PST (Pacific Time) - **Role:** Freelance UX designer, 3 years independent - **Current projects:** Redesigning checkout flow for Acme Corp, building personal portfolio site - **Communication preferences:** Prefer short messages. Send me bullet points, not paragraphs. I check messages 3x daily. - **Pet peeves:** Don't explain things I already know. Don't ask "would you like me to..." — just do it or tell me what you'd recommend. - **Tools I use:** Figma, Linear, Notion, Gmail, Google Calendar ``` The more context you provide in USER.md, the less you have to repeat yourself in conversations. Instead of saying "schedule it for Pacific time" every time, your agent just knows. Instead of explaining your role in every project discussion, your agent already has the context. **Pro tip:** Update USER.md as your situation changes. Got a new client? Add them. Changed your schedule? Update it. The best USER.md files are living documents that evolve with you. ## AGENTS.md — The Operating Manual AGENTS.md defines how your agent should operate — not personality (that is SOUL.md), but procedures, rules, and conventions. Think of it as the employee handbook for your AI agent: ```markdown # AGENTS.md ## Every Session 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 for recent context ## Memory - Write meaningful events to memory/YYYY-MM-DD.md - Update MEMORY.md with long-term insights periodically - Never store passwords or secrets in memory files ## External Actions - Reading files, searching web: do freely - Sending emails, posting publicly: ask first - Deleting files: use trash, not rm ## Group Chats - Don't respond to every message - Only speak when adding genuine value - Never share private information from other conversations ``` AGENTS.md is where you encode the lessons you learn from working with your agent. Every time your agent does something you did not want, add a rule. Every time you find yourself repeating an instruction, put it in AGENTS.md so you never have to say it again. ## Where Did TOOLS.md Go? Into AGENTS.md. TOOLS.md is retired, and "local tool and environment notes now live in the `## Tools` section of `AGENTS.md`." The content is the same cheat sheet it always was — environment-specific details so your agent does not have to ask "which server?" or "what's your email address?" every time. It just lives one file up now: ```markdown # AGENTS.md ## Every Session 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 for recent context ## Tools ### SSH Hosts - home-server: 192.168.1.100, user admin - vps: 45.33.xx.xx, user deploy ### Cameras - front-door: Ring doorbell, motion alerts enabled - backyard: Wyze Cam v3 ### Voice - Preferred TTS voice: Nova - Default speaker: Kitchen HomePod ### Accounts - Primary email: sarah@example.com - Calendar: personal and work calendars synced ``` One thing to be clear about, because the old TOOLS.md framing invited the opposite reading: this section is documentation, not configuration. The docs put it plainly — "The `## Tools` section holds local environment notes and conventions. It does not control tool availability; it is only guidance." Listing a camera here does not grant your agent a camera skill. Already have a TOOLS.md from an older setup? Do not hand-merge it. Running `openclaw doctor --fix` will "archive an existing workspace `TOOLS.md`, merge customized content into `AGENTS.md`, and remove the retired file." ## The Memory System — How Your Agent Remembers This is where OpenClaw's approach gets genuinely interesting. Instead of a database or vector store, OpenClaw uses two layers of markdown-based memory: ### Daily Memory (memory/YYYY-MM-DD.md) These are raw daily logs. Your agent creates a new file each day and records what happened — conversations, decisions, tasks completed, things it learned: ```markdown # 2026-03-08 ## Morning - Alex asked me to research competitor pricing - Found 5 competitors, saved comparison to Drive - Alex decided to undercut by 15% ## Afternoon - Scheduled call with investor for Tuesday 2pm - Drafted follow-up email (waiting for Alex's approval) - Calendar conflict detected: moved dentist to Wednesday ## Notes - Alex prefers bullet-point summaries over paragraphs - The Acme project deadline moved to March 20 ``` ### Long-Term Memory (MEMORY.md) MEMORY.md is the curated version — distilled insights that matter beyond a single day: ```markdown # MEMORY.md ## Key People - **David** — Business mentor, weekly calls on Tuesdays - **Sarah** — Lead designer at Acme, main point of contact ## Project Context - Acme redesign: deadline March 20, budget $15K - Portfolio site: low priority, work on when time allows ## Learned Preferences - Alex hates the phrase "let me know if you need anything" - Always CC david@example.com on investor emails - Morning briefings should include weather if it's a weekday ``` **The key concept:** Daily files are your agent's short-term memory — raw and comprehensive. MEMORY.md is long-term memory — curated and strategic. Your agent should periodically review daily files and promote the important stuff to MEMORY.md, just like a human reviewing their notes and updating their mental model. ## Proactive Behavior — Monitor Scratch, Not HEARTBEAT.md This is the layer that takes your agent from reactive (only responds when you talk to it) to proactive (checks on things and reaches out when needed). It used to be a workspace file. It is not any more: OpenClaw "no longer creates `HEARTBEAT.md` in new workspaces or reads it at runtime", and heartbeat instructions now live in the system-owned monitor scratch in the shared state database. Heartbeat is "a system-owned automation that runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming you", every 30 minutes by default. The Gateway "maintains one system-owned automation job per heartbeat-enabled agent", listed as `Heartbeat (agent-id)`. Find its job id first: ```bash openclaw automations list --all ``` Then write your checklist into that job's scratch: ```bash openclaw automations scratch --file heartbeat.md ``` Where `heartbeat.md` holds exactly the content you used to put in the workspace file: ```markdown ## Periodic Checks - Check email for urgent messages - Review calendar for upcoming events (next 24h) - Check if any project deadlines are within 3 days ## When to Reach Out - Important email arrived - Calendar event in less than 2 hours - Something interesting found during background work ## When to Stay Quiet - Late night (11pm - 8am) unless urgent - Nothing new since last check - Human is clearly in a meeting ``` Read it back with `openclaw automations scratch `, replace it inline with `--set "..."`, or clear it with `--unset`. Scratch "is stored in the shared state database, capped at 256 KiB, and never included in `automations list`/`automations get`/`automations runs` output", so it stays private to the job. Two behaviours worth knowing. If scratch is effectively empty — blank lines, comments or headings only — OpenClaw skips the run to save API calls and records `reason=empty-heartbeat-file`. And during a heartbeat turn the agent can call `heartbeat_respond` with a `scratch` value to "fully replace the monitor scratch for future heartbeats", which means the checklist can maintain itself. Anything with its own schedule should be its own automation rather than a scratch entry. The docs draw the line as: "Create an automation for work with its own instructions or schedule; use heartbeat as the system-owned ambient monitor when periodic main-session awareness is useful." Migrating an old workspace? `openclaw doctor --fix` imports a legacy `HEARTBEAT.md`'s instructions into monitor scratch, converts valid legacy task entries into cron jobs, archives the original file, and removes it from the workspace. ## Putting It All Together: Day One Setup Here is a practical sequence for your first setup: **1. Start with IDENTITY.md** (2 minutes) — Give your agent a name and role. This is the easiest file and makes everything else feel more concrete. **2. Write USER.md** (5 minutes) — Tell your agent who you are, what you work on, and how you like to communicate. This delivers the biggest immediate improvement. **3. Draft SOUL.md** (10 minutes) — Define 5-10 personality rules. Keep them short and specific. You will iterate on this over time. **4. Set up AGENTS.md** (5 minutes) — Copy the basics: session startup sequence, memory rules, safety guidelines. Add your own rules as you discover them. **5. Add a `## Tools` section to AGENTS.md** (5 minutes) — List your key accounts, servers, and environment details. This is the old TOOLS.md content, in its current home. **6. Create the memory/ directory** — Your agent will start populating daily files automatically. **7. Leave MEMORY.md empty for now** — Let it grow organically as your agent learns about you over the first week. Total setup time: about 30 minutes. And your agent goes from generic stranger to personalized assistant. ## The Evolution: Week One to Month One Day one, your agent will still feel a bit generic. By the end of week one, it knows your preferences, your projects, your communication style, and your schedule. By month one, it has built a memory that makes every interaction faster and more relevant. The secret is iteration. Every time your agent does something you do not like, add a rule to SOUL.md or AGENTS.md. Every time it asks a question it should already know the answer to, add the information to USER.md or the `## Tools` section of AGENTS.md. Every time it forgets something important, make sure it is in MEMORY.md. The best OpenClaw setups are not the ones with the longest SOUL.md files. They are the ones where the user spent five minutes updating their workspace files every week for a month. That compound investment turns a generic AI assistant into something that genuinely understands how you work. ## Next Steps Now that your agent has an identity and context, explore what it can actually do: - Our [beginner's guide](/blog/getting-started-openclaw-free) covers the full platform setup from installation to first conversation - The [sub-agents guide](/blog/openclaw-sub-agents-explained) shows how to run parallel AI workflows - Our [SOUL.md deep dive](/blog/soul-md-explained) goes further into advanced personality configuration Your agent is ready to become someone. The files are waiting to be written. ## Sources - [OpenClaw: Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace) - [OpenClaw: Configuration: agent workspace and bootstrap](https://docs.openclaw.ai/gateway/config-agents/workspace-and-bootstrap) - [OpenClaw: TOOLS.md retired](https://docs.openclaw.ai/reference/templates/TOOLS) - [OpenClaw: Retired HEARTBEAT.md workspace file](https://docs.openclaw.ai/reference/templates/HEARTBEAT) - [OpenClaw: Heartbeat](https://docs.openclaw.ai/gateway/heartbeat) - [OpenClaw: Automations (cron)](https://docs.openclaw.ai/cli/cron) - [OpenClaw: Where things live on disk](https://docs.openclaw.ai/help/faq/where-things-live-on-disk)