OpenClaw file naming: your Markdown files have spaces — and your AI agent is blind

In 2026, companies deploying autonomous agents like OpenClaw all make the same mistake. Not a model error. Not a prompt error. A naming error.

They create files called YouTube Secrets.md, Business Ideas (v2).md, Notes réunion 14 mars.md. With spaces. Parentheses. Accents. Random capitalization. And then they wonder why their agent can't find anything, confuses files, and hallucinates paths that don't exist.

And an AI agent with poorly named files is an employee working in an office where every filing cabinet label is written in pencil, backwards, in personal shorthand.

Here's the naming protocol that transforms an amateur OpenClaw into an enterprise intelligence system.

I. Why naming is an architecture problem, not aesthetics

When you name a file YouTube Secrets.md with a space, three things happen in the guts of your workspace.

1. The filesystem fights you

Linux encodes the space as %20 or requires escape quotes. Every bash command, every Python script, every system call has to handle this ambiguity. The agent can do it — but it's wasted compute solving a problem you created.

2. The vector index gets polluted

OpenClaw's vector embeddings engine indexes filenames as semantic tokens. A name like youtube-secrets.md produces two clean tokens: "youtube" and "secrets". A name like YouTube Secrets (draft v2 final).md produces noise: parasitic tokens ("draft", "v2", "final") that pollute the vector space and reduce the precision of all future searches.

3. The agent loses structural inference

This is the crucial point. The agent reasons by structural analogy. If your files follow a consistent convention, it can predict the existence and location of a file before even searching for it. Exactly like an LLM predicts a logical URL on an e-commerce site.

If your convention is business/research/paul-graham-startup-advice.md, the agent can infer that your pricing strategy research lives at business/research/pricing-strategy-saas.md. If your names are anarchic, this inference is impossible.

II. The naming convention: the "internal slug" standard

The rule is simple. Treat every Markdown filename like a URL slug. If you wouldn't put it in a URL, don't put it in a filename.

III. The folder taxonomy: the agent's nervous system

Naming doesn't stop at files. Folders follow the same discipline.

A well-named folder is a semantic namespace. When you ask the agent "Find me our pricing strategy", it should be able to navigate to business/sales/pricing-strategy.md by logical deduction, without scanning the entire workspace.

Notice: no spaces. No uppercase. No accents. Every folder is a single word or a hyphenated compound. It's a filesystem optimized for machine reading — exactly like an /llms.txt is a website optimized for machine reading. The logic is identical. We spent 30 years structuring the web for Google's robots. Now we structure our workspace for AI agents.

Root-level files — the critical layer

Files directly under business/ (not in a subfolder) are the files the agent consults first. It's the equivalent of your homepage. If a file is there, it's strategic.

IV. The living research protocol: name so the future can find

Here's the scenario that kills 99% of companies' productivity.

Someone does a search on Perplexity. "How Paul Graham recommends startups talk to their customers." They get an excellent synthesis. They read it. They close the tab. The file is dead. Lost in the history of a chatbot nobody will ever reopen.

Three months later, the same topic comes up in a meeting. Nobody remembers the details. They redo the search. They waste 30 minutes. It's a permanent cycle of waste that companies accept as fate.

The summary in the chat is useful in the moment. But the real value is the file. paul-graham-customer-development.md now exists in the workspace. The vector embeddings engine has indexed it. The next time anyone — human or agent — approaches the topic of "customer development" or "client discovery", this file will automatically surface as context.

And the filename is critical. paul-graham-customer-development.md contains four high-value semantic tokens. If you had named this file recherche-3.md or notes-pg.md, the vector indexing would be deficient. The agent would never make the connection between "customer development" and this file.

V. The heartbeat and auto-maintenance: files that live without you

A correctly configured OpenClaw doesn't just store files. It maintains them.

The heartbeat — a heartbeat.md file that executes automatically every 15 minutes — is the process that makes files truly "alive". Without heartbeat, your Markdown files are archives. With heartbeat, they're organisms that evolve.

The minimal heartbeat configuration

VI. Slack + living files: democratizing enterprise intelligence

When OpenClaw is connected to Slack via a dedicated private channel (#team-openclaw), every team member has access to the entire Markdown knowledge base.

This is where naming discipline pays its highest dividends.

When a developer types @OC1 show me the onboarding playbook, the agent navigates to business/playbooks/ and finds onboarding-new-team-member.md instantly. Because the filename contains the semantic tokens "onboarding", "new", "team", "member". If the file were called playbook-7.md, the agent would have to open every file in the folder to find the right one. That's wasted compute and added latency for your team.

When a salesperson types @OC1 what mistakes to avoid in client negotiation?, the agent cross-references business/mistakes.md with business/sales/ and business/reminders/ to build a contextualized answer. Because the filenames and folder names are semantic anchors that the embeddings engine can link together.

It's an internal search engine powered by your own knowledge, structured by your own conventions, and accessible by natural language to the entire team. But only if the fuel — the files — is clean.

Conclusion

Naming conventions are not a cosmetic detail. They're the invisible infrastructure that determines whether your AI agent is a competent colleague or a lost intern in an open office.

The web took 15 years to standardize URL slugs. Companies adopting AI agents today don't have 15 years. They have 6 months before naming discipline becomes a measurable competitive advantage.

Open your workspace. Look at your file tree. If you see spaces, uppercase letters, (v2 final) — you have your first task of the day. Rename everything. Your agent will thank you by becoming 10x more effective.