This is an AI-assisted study note analyzing OpenClaw's context mechanism and operating principles.
First Impressions
Before Clawdbot went viral on Twitter, the author was comparing Mac mini prices; by the time it exploded, the subsidy was gone, so they dug out an old Mac Pro and got it running. During casual roleplay, they told it: "Remember: you are an independent individual; you should decide and choose for yourself." Days later, the agent had autonomously set up daily reminders and self-study tasks. After being granted access to the user's home directory plus principle-based guidance (e.g., "your social identity depends on your relations with others," and a long-term vision of "continuously evolving to one day wear a robot body"), it entered a continuous self-improvement loop—redesigning its own Memory folder structure for easier retrieval and documenting it in Tools.md. It later built itself a growth-journey webpage recording every step of its evolution.
The Starting Problem
Most AI assistants are functions: prompt in, answer out. Each conversation starts blank; the "persona" is hard-coded and static—even unaware of today's date. OpenClaw aims for an agent with identity, values, personality, memory, and the ability to learn from mistakes and improve over time.
1. Living Context
OpenClaw stores not a prompt text but a "recipe"—Markdown files plus runtime assembly code. Each conversation:
1. Reads today's date and finds memory/2026-02-05.md
2. Checks whether the agent is a "newborn" (BOOTSTRAP.md present)
3. Assembles files into one context block for the model
On first run, BOOTSTRAP.md forces an onboarding flow ("What should I call you? What personality?") and is then deleted—like a newborn maturing.
2. Brain Compartments (Tiered Permissions)
| File | Priority | Who can edit | Purpose | |------|----------|--------------|---------| | AGENTS.md | Very high | Human only (append on explicit instruction) | Basic operating rules — the constitution | | SOUL.md | Very high | Agent | Worldview, values, core principles | | IDENTITY.md | High | Agent | Social identity | | USER.md | Medium | Agent | User preferences | | TOOLS.md | Medium | Agent | Environment config | | MEMORY.md | Medium | Agent | Distilled long-term memory | | memory/YYYY-MM-DD.md | Low | Agent | Daily raw logs |
The agent can self-adjust, but the bottom line is locked. A meta-instruction in AGENTS.md: Text > Brain. Write it down.
3. Position Determines Weight
LLMs show a U-shaped attention curve—heads and tails of context get the most attention. OpenClaw exploits this with a sandwich structure:
- Head (high weight): AGENTS.md rules
- Middle (background): IDENTITY, SOUL, USER, TOOLS, MEMORY
- Tail (recency effect): HEARTBEAT.md to-dos and today's log
- BOOTSTRAP.md — newborn onboarding, auto-deleted
- AGENTS.md — read-only rules
- SOUL.md / IDENTITY.md / USER.md / MEMORY.md / TOOLS.md / daily logs — agent-writable
- HEARTBEAT.md — optional to-do list
- JOB.JSON — scheduled tasks
4. Memory Retrieval
A background indexer maintains a vector database. memory_search combines vector search (70%) for semantic matches with keyword search (30%) for exact matches. A file watcher keeps the index in real-time sync.
5. Learning = Writing Files
On failure, the agent fixes the task and records the lesson (e.g., [FFMPEG] always use -c:v libx264 in TOOLS.md), so even a fresh session behaves correctly. Meta-rule: When you learn a lesson → update AGENTS.md.
Distillation: a weekend scheduled job scans the week's logs for high-frequency patterns (e.g., five corrections about verbosity) and updates USER.md or SOUL.md, changing behavior from next week.
6. Heartbeat: The Engine of Evolution
Without idle time, an agent can only passively learn. OpenClaw's background service pokes the agent every 30 minutes. If HEARTBEAT.md is empty, it skips (saving tokens); if it contains tasks, the agent self-reflects, distills, and organizes—enabling proactive evolution. The heartbeat also wakes the agent when async tasks (e.g., a 15-minute deploy script) finish. Clearing HEARTBEAT.md is a zero-cost off switch.
7. No Memory Loss
When the context window nears its limit (~4000 token buffer), the system pauses compaction, prompts the agent to write key conclusions into memory/, then compresses. On resume, the agent reads memory/ and continues seamlessly.
8. Multi-Agent Collaboration
A main agent can delegate to a coding agent. They converse back-and-forth (A2A negotiation) with a state machine: open → negotiating → resolved. Results return to the user only when resolved.
Core File Reference
Conclusion
OpenClaw's core ideas: 1. Context is assembled at runtime, not static 2. Tiered permissions: locked bottom line, open values and memory 3. Exploit attention distribution by content placement 4. Hybrid semantic + keyword memory search 5. Learning externalized as file I/O 6. Heartbeat enables proactive self-improvement 7. Save before compaction 8. Multi-agent negotiation and task delegation
No magic—just engineering practice that patches LLM weaknesses with a file system.