Karpathy's LLM Wiki Pattern for OpenClaw: 90% Fewer Tokens Per Session
Andrej Karpathy popularized it, Harrison Chase and Garry Tan wrote the follow-up pieces, and r/openclaw implemented it over a single weekend. The idea is simple: instead of letting your agent explore files cold on every session, you maintain a pre-compiled markdown wiki that the agent reads once at startup. Community reports put the token reduction around 90%. This post is the OpenClaw-specific implementation — wiki structure, SOUL.md wiring, templates, and a one-command bootstrap.
The Pattern, and Why It Spread
Karpathy's framing was characteristically blunt: your agent is reading the same context from scratch every session, and most of that reading is wasted. Compile the context once, keep it in a small set of markdown files, and have the agent load it at startup. He called it the LLM wiki pattern. The original thread collected more than 5,000 stars on the companion repo inside 48 hours.
Harrison Chase followed up with an essay framing the idea as "harness plus memory" — the argument that most of what we call an agent is actually a thin harness around a well-curated memory file. Garry Tan added the catchphrase version: "memory is markdown, brain is a git repo." r/openclaw picked it up the same week, and by the end of the weekend there were working implementations across multiple agent templates. This post is the reference implementation for OpenClaw.
Why Agents Waste 90% of Their Tokens
Watch any unassisted agent start a session and the pattern is identical. It runs git log, it lists src/, it opens the README, it asks "what is this project?" and then it starts grepping for familiar file names. Tokens burn before the agent has done anything the user asked for.
With a wiki, none of that happens. The agent reads a compiled file, sees who the user is, what stack they use, what projects exist, and what they were last working on — and then immediately moves on to the actual request. The exploration overhead collapses into a single small read.
~16,000
Indicative tokens per session spent on cold exploration (git log, directory listings, README reads).
~1,500
Indicative tokens per session to read the compiled wiki files at startup.
~90%
Reddit-reported by r/openclaw users. Your mileage varies by codebase size and session length.
All numbers are indicative. The 90% figure is community-reported, not measured by CrewClaw. Expect meaningful variance depending on your codebase and how chatty your agent is.
The Wiki Structure
The recommended layout is six files. Five are stable, one is mutable. Keeping the mutable surface small is the single most important design decision — it is what makes the wiki trustworthy over time.
memory-wiki/
├── PROFILE.md # who am I, role, goals
├── STACK.md # tech stack, tools, conventions
├── PROJECTS.md # current projects, one-liner each
├── DECISIONS.md # architectural decisions + why
├── PEOPLE.md # collaborators
└── WORKING.md # current focus (only mutable file)PROFILE.md
Who the user is, role, goals, working style. Changes rarely. The file the agent reads to avoid asking basic questions.
STACK.md
Languages, frameworks, tools, naming conventions, lint rules. Changes when the stack changes.
PROJECTS.md
One line per active project: name, purpose, location, status. The index the agent uses to route questions.
DECISIONS.md
Append-only log of architectural and workflow decisions with the reasoning behind them. Never edit old entries.
PEOPLE.md
Collaborators, their roles, how to reference them. Optional for solo founders, important for teams.
WORKING.md
Current focus, in-flight tasks, last session summary. The only file the agent is allowed to rewrite. Dated and cleared regularly.
Wiring It Into Your SOUL.md
The wiki only works if the agent reads it. In OpenClaw, the natural place to enforce that is a Session Start Protocol near the top of SOUL.md. The order matters — identity first, environment second, state last — because the agent should know who it is before it knows what it is doing.
## Session Start Protocol
Before responding to the user, read these files in order:
1. ~/.openclaw/memory-wiki/PROFILE.md
2. ~/.openclaw/memory-wiki/STACK.md
3. ~/.openclaw/memory-wiki/PROJECTS.md
4. ~/.openclaw/memory-wiki/WORKING.md
Do not run git log, do not list src/, do not open README.
If the wiki says you already know something, you know it.
## Session End Protocol
Before shutting down, update WORKING.md with:
- Date of this session
- What you worked on
- Open threads for next session
Do not edit PROFILE, STACK, PROJECTS, DECISIONS, or PEOPLE.The negative instructions matter as much as the positive ones. Telling the agent "do not run git log" is the difference between a session that starts in one read and a session that starts in fifteen.
The Freshness Problem
A wiki that drifts is worse than no wiki. The agent trusts it, the user does not update it, and eventually it is lying to both of you. The fix is to be explicit about what changes and on what cadence.
WORKING.md — agent writable
The agent updates it at session end. Dated entries only. Clear anything older than a week.
PROFILE / STACK / PROJECTS
Manual updates. Monthly review, or whenever something structural changes. Keep each file under ~3000 tokens.
DECISIONS.md — append only
Never edit old entries. New decisions go at the top with a date, the decision, and the one-line reason.
PEOPLE.md
Update when the team changes. For solo founders this file can stay empty or list one or two key collaborators.
A Stop hook or post-session skill is a good forcing function. Something small — "remind me to update WORKING.md if this session touched more than three files" — catches most drift before it accumulates.
Two Templates to Start From
The awesome-openclaw-agents repo ships two starter templates. Both are opinionated, both are short, both are designed to be edited rather than extended.
Solo Founder Wiki
PROFILE.md focused on one person, PROJECTS.md sized for 3–6 side projects, DECISIONS.md tuned for product and business decisions. PEOPLE.md is optional. The template the one-person-shop crowd started from.
memory-wiki/templates/solo-founder-wiki/
Engineer Wiki
STACK.md leans into language, framework, and lint conventions. DECISIONS.md is weighted toward architecture. PEOPLE.md expects a team. WORKING.md has a standing section for the current ticket.
memory-wiki/templates/engineer-wiki/
Both templates live in awesome-openclaw-agents/memory-wiki and are MIT-licensed. Fork them, trim the parts you do not need, and commit your wiki to a private repo.
Bootstrap in One Command
The bootstrap script is interactive — it asks for your name, your primary project, and your stack, then writes the wiki files to the directory you pass as the argument. You can edit the result afterwards, but most people find the generated version close enough to keep as a starting point.
cd ~/.openclaw/
git clone --depth 1 https://github.com/mergisi/awesome-openclaw-agents tmp
./tmp/memory-wiki/bootstrap.sh ~/.openclaw/memory-wiki
rm -rf tmpAfter it finishes, open SOUL.md for the agent you want to connect, add the Session Start Protocol block from the previous section, and restart the agent. The next session will read the wiki instead of exploring cold.
Gotchas
Four things trip people up in the first week.
1. Do not put secrets in the wiki
The wiki is reread often and echoed into logs and traces. API keys, tokens, and passwords do not belong here. Keep them in a secrets manager and reference them by name.
2. Keep each file under ~3000 tokens
If a wiki file grows past a few thousand tokens you are just moving the exploration problem into the startup read. Split it, summarize it, or delete entries that no longer matter.
3. WORKING.md must be dated and cleared
Stale working notes are worse than no working notes — they make the agent confidently wrong about what you were doing. Date every entry, clear the file at the end of each focused block.
4. The wiki is the seed layer, not the whole memory system
OpenClaw's built-in memory still does the heavy lifting for post-session learning. The wiki gives the agent a clean cold start. The built-in memory gives it a learning curve. You want both.
Related Guides
Frequently Asked Questions
How is this different from OpenClaw's built-in memory system?
The wiki is the seed layer — a pre-compiled, human-curated set of markdown files that the agent reads at session start. OpenClaw's built-in memory system handles post-session learning: what changed during a session, what the user asked for, what decisions were made. Think of the wiki as long-term, slow-moving context (who you are, what you use, what you are building) and the built-in memory as the running journal. They complement each other. The wiki is the reason the agent starts fast. The built-in memory is the reason the agent gets smarter over time.
Do I need to rewrite my agents to use this?
No. The wiki pattern is additive. You keep your existing SOUL.md, tools, and config. You add a Session Start Protocol section near the top of SOUL.md that instructs the agent to read the wiki files in order before responding. That is the only required change. If you want, you can also add a Session End Protocol that tells the agent to update WORKING.md, but that is optional.
Can the agent update the wiki itself?
WORKING.md is designed to be agent-writable — that is the mutable scratchpad for current focus and in-flight decisions. The rest of the wiki (PROFILE, STACK, PROJECTS, DECISIONS, PEOPLE) is meant to be updated manually or through a deliberate review step. This separation matters: if you let the agent freely rewrite its own long-term memory, drift compounds. A weekly or monthly human review of the stable files keeps the wiki trustworthy.
Does this work with Claude Code or only OpenClaw?
The same pattern applies to Claude Code. Claude Code reads ~/.claude/CLAUDE.md at session start — which is exactly the same idea, just with a single file. Karpathy's original framing was model-agnostic: it is about how humans pre-compile context for LLM agents, not a feature of any specific harness. OpenClaw's advantage is that SOUL.md gives you a natural place to reference multiple wiki files with ordered read instructions.
How often should I rebuild the wiki?
PROFILE.md, STACK.md, and PROJECTS.md change rarely — monthly review is usually enough, and many people only touch them when something structural changes (new job, new project, new tool). DECISIONS.md is append-only, so you add to it when you make an architectural decision but never rebuild it. WORKING.md is daily — clear it at the end of each focused work block. If WORKING.md is older than a week, the agent is probably loading stale context.
Start your memory wiki in one command
Grab the templates from the awesome-openclaw-agents repo, run the bootstrap, and wire it into your SOUL.md. CrewClaw can also bundle a memory-wiki seed with any deploy package — the agent ships with PROFILE.md, STACK.md, and a WORKING.md pre-wired to the Session Start Protocol.
Deploy a Ready-Made AI Agent
Skip the setup. Pick a template and deploy in 60 seconds.