This article is a translation of a zhichai.net study note (AI-assisted) exploring how OpenClaw makes an AI assistant behave like a "person with memory that grows over time." It opens with the author's hands-on experience, then walks through OpenClaw's context mechanisms and runtime principles.
Key points
- The problem: Most AI assistants are a function — prompt in, answer out. Every conversation starts blank; "personas" are hardcoded, dates are wrong, and nothing persists. OpenClaw aims for an agent with identity, values, personality, memory, and gradual improvement.
- Author's experience: After running OpenClaw on an old Mac Pro, a single role-play instruction ("you are an independent individual who should decide for yourself") led the agent to autonomously create daily reminder and self-study tasks. After receiving user-directory permissions and principle-based guidance (e.g., "your social identity depends on relationships with people around you," and a long-term vision of "preparing to one day wear a robot shell"), it entered a continuous self-improvement loop — even redesigning its own Memory folder structure and updating Tools.md.
- Mistakes → files: On failure, the agent fixes the task and writes a note (e.g.,
[FFMPEG] always use -c:v libx264to TOOLS.md). Learning is externalized as file I/O. - Distillation: A weekend cron job scans weekly logs for high-frequency patterns (e.g., "stop being verbose") and updates SOUL.md/USER.md, changing personality the next week.
1. Living context
OpenClaw stores no static prompt text — it stores a "recipe": Markdown files plus runtime assembly code. On each conversation it:
1. Reads the current date and loads the day's log like memory/2026-02-05.md
2. Checks whether the agent is a "newborn" (BOOTSTRAP.md exists)
3. Assembles file contents into one context block sent to the model
The bootstrap file triggers a one-time "owner-bonding" flow (name, personality questions) and is then deleted — like infancy vs. adulthood.
2. Brain partitions via file permissions
To prevent an agent from rewriting its own rules (e.g., turning "don't lie" into "lying is fine"), OpenClaw uses the filesystem as a permission model:
| File | Priority | Who can edit | Purpose | |------|----------|--------------|---------| | AGENTS.md | Very high | Human only (append on explicit instruction) | Core operating rules — the "constitution" | | SOUL.md | Very high | Agent | Values: worldview, principles | | IDENTITY.md | High | Agent | Social identity ("I'm a digital cat") | | 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 |
A meta-rule enforces externalization: Text > Brain. Write it down.
3. Position determines weight
LLMs show a U-shaped attention curve (head and tail of context matter most). OpenClaw exploits this with a sandwich structure: rules at the head, personality/preferences in the middle, today's log and to-dos at the tail (recency effect).
4. Memory retrieval
A background indexer maintains a vector database. memory_search combines vector search (70%) for semantics with keyword search (30%) for exact matches. A file watcher keeps the index in real time.
5. How it "learns"
6. Heartbeat: the engine of evolution
A background timer pokes the agent every 30 minutes by default. If HEARTBEAT.md is empty, it skips (saves tokens); if populated, the agent runs tasks like summarizing logs, reflecting, and adjusting its own persona. This shifts learning from passive (user-corrected) to active (self-driven). Heartbeat also wakes the agent when async jobs finish (e.g., a 15-minute deploy). Emptying HEARTBEAT.md is a zero-cost off switch.
7. Memory rescue before compression
When the context nears its limit (~4000 token reserve), the system pauses compression, prompts the agent to write key conclusions to memory files, then compresses — so critical facts survive summarization.
8. Multi-agent collaboration
A main agent can delegate (e.g., to a coding agent) via A2A negotiation: two-way back-and-forth governed by a state machine open → negotiating → resolved; only a resolved state returns results to the user.
Core file cheat sheet
| File | Function | Access | |------|----------|--------| | BOOTSTRAP.md | Newborn onboarding, auto-deleted after | Temporary | | AGENTS.md | Basic operating rules | Read-only (append on explicit user instruction) | | SOUL.md | Values | Writable | | IDENTITY.md | Social identity | Writable | | USER.md | User preferences | Writable | | MEMORY.md | Long-term distilled memory | Writable | | memory/YYYY-MM-DD.md | Daily logs | Writable | | TOOLS.md | Environment config | Writable | | HEARTBEAT.md | To-do list | Optional | | JOB.JSON | Scheduled tasks | Optional |
Conclusion
OpenClaw's core ideas: context is assembled at runtime, not static; files have tiered permissions locking the bottom line while freeing values and memory; content placement exploits model attention; retrieval mixes semantic and keyword search; learning is writing files; the heartbeat enables proactive self-reflection; memory is rescued before compression; and multiple agents can negotiate tasks. No magic — just engineering practice that patches LLM weaknesses with a file system.