The content of this article is based on the author's personal technical practice and independent thinking, and aims to share experience. It represents only the author's personal views.
I've been using OpenClaw extensively lately, spending several hours with it almost every day, and I've gradually gained some experience. I've seen many people say OpenClaw is difficult to use, so I want to first discuss the reasons why it's "difficult to use," and then delve into a core issue that I believe most people overlook—what is the essence of OpenClaw's increasing usability?
My conclusion: it's a bunch of Markdown files.
This isn't a joke; it's my judgment after reading its source code. Let me elaborate.
I. Why do many people find OpenClaw difficult to use?
Before discussing the core mechanisms, let's address a few common "usage issues." Many people say it's difficult to use, but this isn't a product problem; it's a problem with how you're using it.
1. Incorrect Model Selection
The model's impact on performance is decisive. The same instructions, but a different model, can produce drastically different output quality. The key understanding here is: OpenClaw itself doesn't generate intelligence; it's a framework that allows AI models to perform better. No matter how good the framework is, if the underlying model is weak, the upper limit is limited. It's like giving an intern a very detailed instruction manual; they might still not be able to do it well. But if you give the same manual to a senior engineer, they can achieve far beyond your expectations.
2. Treating the Agent as a Generalist
Many people use it by assigning one agent to do everything. They use it for coding, copywriting, and data analysis. Think about it: in the real world, don't every company have different roles? Don't experts specialize in one or a few areas? AI agents are the same. OpenClaw supports a multi-agent architecture; you can configure multiple agents, each responsible for a specific area. Moreover, from a code perspective, this isn't just a simple "division of labor"—each agent has its own independent workspace directory, independent memory database, and independent session history. In other words, an agent dedicated to code review accumulates experience solely focused on code review, unaffected by conversations involving writing weekly reports. This is similar to a company where each employee focuses on a specific area; their experience is vertical and in-depth, not horizontal and sparse.
3. The Lack of Agent Training
This is the key point I want to emphasize today. Many people install OpenClaw, use it out of the box, find it ineffective, and conclude it's unusable. But think about it: if you hire a new employee, do you expect them to perform as well as a three-year veteran on their first day?
Agents need training. You need to engage in dialogue with them, explain your preferences, help them understand your work scenarios, work together to overcome challenges, and solidify that experience. In OpenClaw terminology, this is called "creating a Standard Operating Procedure" (SOP); in more technical terms, it's called accumulating workspace files.
This is the core mechanism by which OpenClaw becomes better the more you use it, and it is also the focus of this article.
II. Core Mechanism: A self-evolving Markdown file system
I read OpenClaw's source code and clearly understood the entire "gets better with use" mechanism. In short, its architecture can be summarized in one sentence:
Before each conversation, a bunch of Markdown files are appended to the prompt; after the conversation, the agent writes back the newly learned information to these Markdown files.
It's that simple. But this simple loop forms a powerful flywheel.
Skeleton: 7 Core Markup Files
OpenClaw pre-defines 7 types of core files for each agent's workspace:
1. SOUL.md — Who is the Agent?
This file defines the agent's personality: tone, style, boundaries, and values. Interestingly, the template includes the sentence: "This file is yours to evolve. As you learn who you are, update it." This means the agent's "personality" isn't fixed in one go; it gradually adjusts itself through interaction with you. If it discovers you prefer concise and direct answers, it will incorporate this preference into its core profile.
2. USER.md — Who is the User?
This is the agent's profile of you: your name, time zone, work habits, technical preferences, and communication style. The agent updates this file each time it learns new information about you during a conversation. The longer it's used, the more accurate this profile becomes, and the more the agent "understands" you.
3. AGENTS.md — Rules of Conduct and Pitfalls Encountered
This is the most crucial file. It defines the agent's behavioral norms, and more importantly, records all the pitfalls encountered. In the source code, I saw a clear instruction in its template: "When you learn a lesson → update AGENTS.md", "When you make a mistake → document it so future - you don't repeat it." In simpler terms: if you make a mistake, write it down so you won't repeat it. This is why OpenClaw gets better with use—not because the model becomes smarter, but because the pitfall records in AGENTS.md accumulate. Each record represents experience gained at the cost of a mistake, solidified into a line of text, and permanently effective.
4. TOOLS.md — Environment Memo Record
Your working environment: SSH hostname, camera device name, file path habits, etc. Add these yourself after encountering agent pitfalls.
5. SKILL.md × N — Operation Manuals for Various Domains
Each SKILL.md defines the operation specifications for a specific domain. OpenClaw has 52 built-in skills, covering GitHub issue management, email processing, health checks, code review, etc. More importantly, you can write your own skills. For example, if you need to produce a weekly report in a specific format, you can write the format requirements, data sources, and output template into a SKILL.md file and put it in the workspace. From then on, the agent will follow this specification every time it produces a weekly report, without you needing to describe it again each time. Skill loading has a priority: built-in skills have the lowest priority, and user-defined skills in the workspace have the highest priority. This means you can override the behavior of any built-in skill.
6. memory/*.md — Daily Memory
The agent writes a date-named md file every day, recording the key points of the conversation, what was done, and what was learned. These files are indexed in an SQLite database, supporting full-text search and vector retrieval.
7. MEMORY.md — Extracted Long-Term Memory
The agent periodically extracts important content from daily memory into this file. It's like extracting the essence of notes from a diary. This file is loaded into the prompt for each conversation, so the agent's "long-term memory" is stored here.
Flesh and Blood: Custom Files Grown Co-opted by Users and Agents
The above 7 file types form the framework's default skeleton. However, a workspace is essentially a regular folder. The agent has file read and write capabilities, allowing it to create any files and directories it needs within it.
For example, an agent that helps you manage projects might, over time, develop a workspace structure like this:
workspace/
├── SOUL.md
├── USER.md
├── AGENTS.md
├── TOOLS.md
├── MEMORY.md
├── memory/
│ ├── 2026-03-01.md
│ └── 2026-03-02.md
├── projects/
│ ├── project-alpha/
│ │ ├── progress.md
│ │ ├── decisions.md
│ │ └── risks.md
│ └── project-beta/
│ └── progress.md
├── templates/
│ ├── weekly-report.md
│ └── meeting-notes.md
└── contacts/
└── team-preferences.mdThese additional files have no schema constraints; they are entirely organized by the agent itself during use. Each person's agent will ultimately develop a different form, depending on what you discuss with it, what you do with it, and in which areas you use it.
This means your agent is truly "custom-made"—it's not just about selecting a few options in the settings page; it's about it developing a knowledge system tailored specifically to you through hundreds of conversations.
III. A Self-Evolving Closed Loop
The above describes the static file structure. What's truly interesting is how these files are maintained and updated. OpenClaw designed a self-evolving closed loop for its agent:
Dialogue begins
→ Load all core Markdown files from the workspace to the system prompt
→ Agent retrieves relevant memories using `memory_search` based on the user's question
→ Agent executes tasks
→ Learns new things / makes mistakes / discovers new user preferences during the task
→ Agent writes back relevant files (AGENTS.md / USER.md / memory/*.md / MEMORY.md)
→ File changes trigger Memory index rebuilding (SQLite FTS5 + vector index)
→ Dialogue ends
Next dialogue begins
→ Load updated Markdown files
→ Search for memories with the new index
→ Agent behavior becomes more precise
→ LoopNote the two nested loops:
Outer loop: read and write Markdown (.md) files. Loaded with each conversation, updated during the conversation. This is the accumulation of "experience"—the agent learns what to do, what not to do, what you like, and what your environment is like.
Inner loop: vector index retrieval. As the number of memory files increases, the agent cannot cram all the content into the prompt (token limitations exist). Therefore, OpenClaw uses SQLite's FTS5 full-text search and SQLite-vec vector retrieval to create a hybrid search engine. Before each conversation, the agent is instructed to search relevant memories before responding, ensuring accurate information retrieval even with hundreds of memory files.
These two loops together form a complete "learning-memory-retrieval-application" system. And the storage medium for this system is entirely Markdown (.md) files.
IV. Several Key Details of Technical Implementation
To ensure this article goes beyond a conceptual discussion, I will select several specific implementation details from the source code to help you understand just how "real" this mechanism is.
Bootstrap Loading Mechanism
At the start of each conversation, the `resolveBootstrapContextForRun()` function will:
1. Read all core files in the workspace
2. Filter by conversation type (sub-agents only load a reduced subset)
3. Allow plugins to modify content via hooks
4. Limit each file to 20KB, with a total limit of 150KB; any excess will be truncated.
This budget mechanism is crucial—it means your Markdown files cannot grow indefinitely. Too much content will result in truncation. Therefore, agents need to learn to "refine," condensing the most important experiences into a limited space. This is why `MEMORY.md` (refined long-term memory) and `memory/*.md` (original log files) are separate.
Memory Hybrid Search
The memory search engine uses a hybrid weighting of 70% vector similarity and 30% keyword matching, and also supports MMR (Maximal Marginal Relevance) diversity and time decay. This means that more recent memories are given higher weight, and search results are diversified as much as possible, avoiding a purely similar mix of content.
Skill Discovery Priority Chain
Skills are scanned from 6 sources, in ascending order of priority:
1. Plugin-provided skills
2. Built-in skills
3. Managed skills (~/.openclaw/skills/)
4. Personal skills (~/.agents/skills/)
5. Project skills ({workspace}/.agents/skills/)
6. Workspace skills ({workspace}/skills/)
Skills in the user's workspace have the highest priority and can override any built-in behavior. This means you can completely "train" any skill of the agent, and the way to do this is—by writing a Markdown file.
Self-Destructive Bootstrapping
On first use, the agent executes the bootstrapping process in BOOTSTRAP.md to set IDENTITY.md, USER.md, and SOUL.md. After setup, the agent is instructed to delete BOOTSTRAP.md itself. This is a one-time initialization process and is no longer needed. The workspace status machine records the timestamp of boot completion.
V. What does this mean?
After understanding this mechanism, several inferences can be drawn:
1. The value of your Agent lies in your workspace folder.
The code is public, and the model is generic. The truly unique and irreplaceable part is the pile of Markdown files in your workspace. Those files encode your preferences, your workflows, the pitfalls you've encountered, and your project context.
Switch to another computer, copy the workspace folder over, and the experience remains unchanged. Delete that folder, and you start from scratch.
2. Training the Agent is Just Writing Markdown Files
No programming knowledge or understanding of prompt engineering techniques is required. You simply need to write your experiences, preferences, and specifications into Markdown files using natural language and place them in the workspace. OpenClaw's code will automatically inject them into the prompt at appropriate times.
You don't even need to write them yourself—during your interactions with the agent, it will automatically write what it learns into Markdown files. All you need to do is correct it when it makes mistakes, and it will remember them.
3. The difference between agents is the difference in their Markdown (md) files.
Two people using the same version of OpenClaw and the same model can have vastly different experiences. The difference lies in what they've accumulated in their workspaces. One person has been using it for three months, their workspace containing dozens of skills, hundreds of troubleshooting records, and a complete user profile; the other person has just installed it, their workspace only has the default template.
This is similar to the difference between experts in the real world—two people with similar intelligence (same model), the difference lies in their accumulated experience and knowledge (md files).
4. This may be a universal paradigm for AI agent products.
I believe OpenClaw's "markdown files as knowledge" architecture has universal applicability. Any AI agent product that wants to "get better with use" ultimately needs to solve the problems of knowledge persistence and retrieval. OpenClaw's answer is to use the simplest file format (markdown), the most universal storage method (file system), the most intuitive organization method (folders), and a search engine to connect them.
There are no fancy knowledge graphs, no complex vector database clusters; it's just a bunch of markdown files. But this bunch of markdown files carries an ever-evolving expert system—it knows who you are, what you want, how to do your job, and which pitfalls to avoid.
VI. Practical Suggestions
Finally, here are a few practical suggestions:
Proactively guide agents to develop Standard Operating Procedures (SOPs). Don't wait for agents to figure things out on their own. In areas where you already have mature workflows, directly tell them, "From now on, all tasks of this type will follow this process," and have them write it in SKILL.md.
Regularly review workspace files. What agents write themselves isn't always correct. Regularly check AGENTS.md and USER.md for outdated or inaccurate content and correct it promptly.
Utilize multiple agents effectively. Assign different agents to different domains, ensuring each agent's knowledge base remains vertical and focused. An agent dedicated solely to coding is far more effective than an agent that does everything.
Choose the right model. Again, the model is fundamental. Feeding a bunch of meticulously crafted Markdown files to a weak model will have limited impact.
Back up your workspace. This is one of your most valuable digital assets. It's recommended to manage it with Git (OpenClaw uses Git for tracking by default) and push to the remote repository regularly.
Conclusion
OpenClaw's source code spans hundreds of thousands of lines, but the core mechanism that makes it "get better with use" is essentially a loop of reading and writing Markdown (MD) files. The code provides the pipeline—channel access, model invocation, tool run, and memory indexing. But the water flowing through the pipeline is the ever-accumulating MD files.
In other words: the code determines what OpenClaw can do, the MD files determine how well it does it.
And the latter is built up, one conversation at a time, between you and your agent.