Akshay Parkhi's Weblog

Why .md Files Are the Agent: How ClawdBot Turns Markdown Into a Living Assistant

8th March 2026

The Weird Truth About AI Agents

You’d expect an AI agent to consist of code: Python classes, orchestration frameworks, complex pipelines. But ClawdBot (OpenClaw) does something different. Its agent is mostly .md files sitting in a folder. Plain text. Markdown. The kind of thing you’d write documentation in.

And somehow, it works.

This post explains three things:

  • Why OpenClaw chose markdown files as the backbone of its agent system
  • What those files actually do inside the runtime
  • What this approach does well, and what it does badly, compared to “real” agentic frameworks

What’s Actually in the Folder

Here’s what a ClawdBot workspace looks like:

~/.openclaw/workspace/
|-- SOUL.md          -> Personality, values, behavioral rules
|-- AGENTS.md        -> Operating manual (how to do the job)
|-- USER.md          -> Info about the human (name, timezone, preferences)
|-- IDENTITY.md      -> Name, emoji, avatar
|-- HEARTBEAT.md     -> Periodic task checklist
|-- TOOLS.md         -> Local tool configuration notes
+-- memory/
    |-- MEMORY.md    -> Long-term curated memories
    +-- 2026-03-08.md -> Daily raw logs

That’s it. No Python. No YAML configs. No class hierarchies. Just markdown files that a human can read and edit with any text editor.

How Markdown Becomes an Agent

The .md files don’t run. They don’t execute. They’re not code. Here’s what actually happens:

Step 1: A Trigger Arrives

Something starts a session:

  • You send a Telegram message
  • A cron job fires at 7 AM
  • A heartbeat timer fires

Step 2: OpenClaw’s Runtime Reads the Files

The Node.js runtime (the actual code) does this:

Read SOUL.md      -> "Be genuinely helpful, have opinions..."
Read AGENTS.md    -> "Read SOUL.md first, use memory files..."
Read USER.md      -> "Name: Akshay, timezone: ET..."
Read IDENTITY.md  -> "Name: ClawdBot, vibe: sharp..."
Read TOOLS.md     -> "Brave Search API configured..."
Load skills.yaml  -> "Available: coding-agent, weather, healthcheck..."

Step 3: Concatenate Into One System Prompt

The runtime concatenates all of it into a single string of roughly 8,400 tokens. That string becomes the system parameter in the API call.

Step 4: Call Claude

{
  "model": "claude-opus-4-6",
  "system": "[SOUL.md + AGENTS.md + USER.md + IDENTITY.md + ...]",
  "tools": ["web_search", "read", "write", "exec", ...],
  "messages": [
    { "role": "user", "content": "Your message or cron prompt" }
  ]
}

Step 5: Handle the Response

The runtime handles tool calls, routes responses to Telegram, and logs everything. This is the standard agent loop.

The markdown files are gone by this point. They were just raw material. The runtime compiled them into a system prompt, and Claude consumed them as instructions.

Why Markdown? Five Real Reasons

1. Humans Can Read and Edit Them

Your agent’s personality is in SOUL.md. Don’t like how it behaves? Open the file. Change it. No redeployment. No recompilation. No need to understand a framework’s abstraction layers.

# SOUL.md

**Be genuinely helpful, not performatively helpful.**
Skip the "Great question!" -- just help.

**Have opinions.** You're allowed to disagree.
An assistant with no personality is just a search engine.

Anyone can understand what this does. Anyone can change it. That’s the point.

2. The Agent Can Edit Itself

This is the clever part. Claude has read and write tools. It can edit its own .md files. The agent can:

  • Update MEMORY.md with things it learned today
  • Edit USER.md when it discovers your preferences
  • Edit HEARTBEAT.md to add new periodic checks
  • Even update SOUL.md (with your permission)

The agent’s identity lives in files the agent can access. It’s self-modifying configuration.

3. No Framework Lock-in

SOUL.md is just text. If you switch from Claude to GPT-4 to Gemini, the files still work. They’re model-agnostic personality definitions. There’s no class Agent(BaseAgent) to rewrite and no framework migration.

4. Composability Through Files, Not Code

Need a new skill? Put a SKILL.md in the skills directory. Need to change behavior in group chats? Edit the relevant section in AGENTS.md. Need to add a new cron job? The job’s prompt is just a message string. You need no plugin architecture.

5. Memory as Files = Persistence for Free

Claude starts fresh every session. It has no memory. But with markdown files:

memory/
|-- MEMORY.md         -> "Akshay cares about heart health research"
|-- 2026-03-07.md     -> "Fixed cron jobs today, fixed granth rotation"
+-- 2026-03-08.md     -> "Fixed tool_call garbage in Telegram reports"

The agent reads yesterday’s notes and continues from where it stopped. Files are the memory system. There is no vector database, no embeddings, and no RAG pipeline. There are just markdown files that the agent reads at the start of each session.

The Analogy That Makes It Click

ComponentReal-World Equivalent
SOUL.mdCompany culture handbook
AGENTS.mdEmployee onboarding manual
USER.mdClient dossier
IDENTITY.mdName badge + personality brief
TOOLS.mdEquipment manual
MEMORY.mdPersonal notebook
OpenClaw runtimeThe office building
Claude APIThe employee’s brain
TelegramThe phone on their desk

The .md files are the papers on the desk when the employee sits down each morning. Without them, the employee (Claude) is brilliant. But they have no idea who they work for, what they’re supposed to do, or what happened yesterday.

Where This Breaks Down

Honesty time. The .md-as-agent approach has real limitations:

No Real Orchestration

Agentic frameworks like Strands have proper agent loops:

  1. The LLM calls a tool.
  2. The orchestrator executes it.
  3. The orchestrator returns the result to the LLM.
  4. The loop repeats until the task is done.

OpenClaw’s cron jobs often run as one-shot prompts. The agent says what it thinks it should do instead of actually doing it.

In my setup, this caused the agent to print fake <tool_call> XML as plain text and hallucinate URLs. The cause: the loop wasn’t properly executing tools and returning the results to the LLM.

No Inter-Agent Communication

Claude Code’s Agent Teams have mailboxes, shared task lists, and a lead who coordinates. OpenClaw’s cron jobs are completely isolated. Each session has no idea the others exist. There’s no “hey, the AI news session found something relevant to the Physical AI session” capability.

Context Window Is the Hard Limit

All those .md files consume part of the context window. At ~8,400 tokens just for system prompt, you’re spending tokens on personality before the agent does any actual work. For a cron job that needs to search, read articles, and synthesize, that’s a meaningful chunk of context gone.

Personality != Capability

You can write the most detailed SOUL.md in the world, but it doesn’t give the agent new abilities. It only shapes how the agent uses the abilities it already has (tools, API access). The .md files are steering, not engine.

The Spectrum of Agent Architectures

Where does the .md-as-agent pattern sit?

Simple <----------------------------------------------> Complex

Raw API Call    OpenClaw/ClawdBot    Strands/LangGraph    Claude Code Teams
                                    Agent Loop           Multi-Agent

| No system     | .md files as       | Code-level         | Multiple agents
| prompt.       | personality.       | orchestrator.      | with mailboxes,
| No tools.     | Basic tool         | Proper tool loop.  | shared tasks,
| One-shot.     | support.           | Error recovery.    | coordination.
|               | Messaging apps.    |                    | Real-time.

OpenClaw sits in the “personality layer + delivery system” zone. It’s more than a raw API call, but less than a full agentic framework. Its genius: it makes agent configuration human-readable and human-editable. Its weakness is in the execution layer.

What I Learned Running This Setup

I ran 4 daily cron jobs on ClawdBot (AI news, Physical AI, heart health research, and a spiritual text summary). Here is what I learned:

  1. The .md files are great for persona. The bot feels like someone, not just a generic AI.
  2. But persona without proper tool execution is lipstick on a pig. The agent hallucinated my “search reports” because the agent loop wasn’t properly executing web searches.
  3. Memory-as-files genuinely works. The bot reads yesterday’s notes and regains context. This is surprisingly effective.
  4. The simplicity is both the strength and the weakness. It is easy to configure, but you hit a ceiling fast when you need real orchestration.

The Takeaway

OpenClaw’s .md-as-agent pattern is a bet on a specific idea: the most important part of an AI agent isn’t the orchestration code. It’s the instructions.

And for a personal assistant that chats on Telegram, remembers your preferences, and delivers daily digests? That bet succeeds.

But for anything requiring real multi-step reasoning, reliable tool use, or coordination between agents, you need actual orchestration code underneath. Personality is the steering wheel, but you still need an engine.

The .md files aren’t the agent. They’re the agent’s soul. And sometimes, a soul is enough.

Posted 8th March 2026 at 1:23 pm

More recent articles

This is Why .md Files Are the Agent: How ClawdBot Turns Markdown Into a Living Assistant by Akshay Parkhi, posted on 8th March 2026.

Next: Why Every Coding Agent Is TypeScript (And Every ML Framework Is Python)

Previous: OpenClaw vs Claude Code Agent Teams — Architecture Comparison