A lot of “OpenClaw forgot the project” problems are not model-memory problems. They are file hygiene problems: plans, decisions, handoff notes, and session summaries live inside a chat thread, so the moment you restart, switch devices, or hand work to another agent, the useful context disappears.
The fix is not “make the model remember forever.” The fix is a small external project brain: plain Markdown files, optionally browsed in Obsidian, updated at explicit moments, and durable enough that a cold session can recover the work from disk.
A recent Reddit thread about using Obsidian as a persistent brain for Claude Code is good demand signal, but not a specification. The useful takeaway is simpler: externalize project memory into files the team can inspect, review, diff, and reuse.
If your workspace or state does not already persist cleanly, fix that first:
If you already run specialized workers, pair this guide with:
What this guide helps you finish
By the end of this guide, you should be able to:
- decide when a project brain is worth the overhead,
- store it in a folder OpenClaw can actually read,
- keep a repeatable note structure for status, decisions, sessions, and handoffs,
- verify that a restarted session can recover context without old chat history.
Who this is for (and not for)
Use this guide if:
- your work spans more than one session, day, device, or agent,
- you keep re-explaining the same project state,
- decisions or handoffs keep getting trapped in chat.
This is not the best pattern if the task is:
- a one-off prompt that finishes in one sitting,
- purely exploratory scratch work,
- blocked by missing persistence or write permissions at the workspace layer.
1) Put the right thing in the right memory layer
The cleanest setups separate three kinds of memory:
- Session state: temporary local context, back-and-forth clarification, and scratch reasoning that only matters for the current run.
AGENTS.md/USER.md/SOUL.md: durable operating rules that OpenClaw can load every session, such as coding conventions, safety boundaries, or standing role instructions.- Project brain: changing project facts that must survive restarts, such as the current plan, accepted decisions, blockers, handoffs, and session summaries.
If a fact should survive a restart but might change next week, it usually belongs in the project brain.
If a rule should apply every session, put it in AGENTS.md or USER.md, not in a session note. OpenClaw’s workspace model already supports loading those files as durable instructions. Use the project brain for live project memory, not baseline policy.
2) Put the brain in a real Markdown folder OpenClaw can read
The safest shape is boring:
- keep the brain as normal
.mdfiles, - store it either inside the workspace or in an adjacent folder/repo,
- point OpenClaw at the real folder path.
OpenClaw’s memory search supports indexing additional Markdown folders through memorySearch.extraPaths, which is the cleanest way to use an external vault without pretending chat history is the source of truth.
Conceptually, the config looks like this:
agents:
defaults:
memorySearch:
extraPaths:
- ../project-brainImportant operational details:
- OpenClaw indexes Markdown files under those paths, so keep the durable brain in
.md, not buried inside screenshots or PDFs. - Point OpenClaw at the real folder path when you can. Even if symlinks work in your environment, they add path ambiguity during setup, sync, and recovery.
- Obsidian documents symlink caveats, so ordinary folders are the safer default.
If you want the Obsidian layer, think of it as a viewer and editor over local files, not as the architecture itself. Obsidian stores notes as local files inside a vault, which is why the pattern stays portable.
If you use Obsidian, keep the setup boring
These choices help the vault stay useful outside Obsidian:
- prefer standard Markdown links over Obsidian-only wiki links if agents, Git diffs, or other editors need to read the files cleanly,
- use the Templates core plugin for repeatable note scaffolding,
- use Daily notes only if you truly review them; otherwise keep session notes in a dedicated
sessions/folder with explicit names.
If this folder lives on a Docker bind mount or remote workspace, verify it is writable before you trust it:
3) Start with six files, not sixty
Most vaults become junk because the operator creates too many note types too early.
Start here:
project-brain/
README.md
current-state.md
decision-log.md
sessions/
handoffs/
references/What each part is for:
README.md: invariant project context - goal, scope, owner, major constraints, canonical repos, dashboards, and the one definition of done.current-state.md: the single source of truth for what is true now - current phase, latest blocker, next three actions, and the artifact or branch that matters most.decision-log.md: dated decisions with reason, consequence, and reversal trigger.sessions/: short end-of-session summaries so the next session does not have to reconstruct what happened.handoffs/: explicit transfer notes when work moves between operators or sub-agents.references/: curated source material worth rereading later, not a dump of everything the browser touched.
That is enough for most teams. Add more only when one file has a real readership problem.
Minimal current-state.md
# Current state
Last updated:
Owner:
Goal:
Current phase:
What is done:
What is blocked:
Next 3 actions:
Canonical artifacts:Minimal decision-log.md entry
## 2026-03-17 - Use external project brain via extraPaths
Decision:
Reason:
Consequence:
Revisit when:4) Define the only update moments that matter
The vault stays useful only if updates happen at predictable moments. Do not ask the agent to “capture everything.” Ask it to update the brain at these points:
Session start
Read:
README.mdcurrent-state.md- the most recent relevant file in
handoffs/orsessions/
This is the fast context recovery layer. If a new session cannot orient itself from those three reads, the brain is under-specified.
Decision point
Append to decision-log.md when:
- the team chooses one path over another,
- a constraint changes,
- a rollback or retry rule changes,
- a previous assumption is no longer true.
Do not log every idea. A decision log is for choices that future-you will otherwise have to rediscover.
Session end
Write one short session note:
# Session summary
Date:
Owner:
Intent:
What changed:
Decisions made:
Artifacts / commits / links:
Open questions:
Best next action:
Suggested restart prompt:Milestone or ship point
When a milestone closes - PR merged, deploy finished, migration complete, or report delivered - update current-state.md immediately. This prevents stale status from outranking fresher session notes.
5) Give sub-agents a strict read/write contract
Sub-agents should not freestyle the vault structure. They need a read contract and a write contract.
Read contract
Before acting, a sub-agent should read:
README.mdcurrent-state.md- the latest relevant handoff note
- the latest relevant session summary
That is usually enough to restore working context without replaying the whole archive.
Write contract
After acting, a sub-agent should:
- update
current-state.mdif the project’s live truth changed, - append a
decision-log.mdentry only for a real decision, - write one session summary under
sessions/, - write one handoff note under
handoffs/only if another agent or later session must continue unfinished work.
Use a handoff note like this:
# Handoff
From:
To:
Task:
What is true now:
What is blocked:
Do next:
Read first:
Artifacts:
Avoid:Good handoff notes are not essays. They exist to answer:
- what changed,
- what matters next,
- what not to repeat,
- which files or artifacts should be read first.
If you want this protocol to survive every new chat, pin it in AGENTS.md or USER.md. If you already route specialized workers, combine that with the role boundaries in:
6) Keep the vault from becoming junk
Obsidian makes it easy to create notes. The counterweight is being strict about what earns a note.
Use these rules:
- One canonical home per fact. Live project status belongs in
current-state.md, not in five overlapping notes. - Keep session summaries short. Link artifact paths, commits, and reports instead of pasting huge logs.
- Use the brain for context, not queue management. If you need a visible execution board, keep that in
TASKS.mdand let the project brain explain the why behind it. - Archive dead handoffs. Once the work is complete and the state is reflected elsewhere, old handoffs can move to an archive folder or be deleted.
- Do a small weekly prune. Merge duplicates, delete empty stubs, and rewrite vague “thoughts” into either a decision, a task, or nothing.
- Keep secrets out. A synced vault or Git-backed repo is the wrong home for tokens, raw auth dumps, or sensitive message bodies.
If you need the execution board side of this pattern, add:
7) Run a cold-start recovery drill
Do this once before you trust the system:
- End the current session.
- Start a fresh OpenClaw session or a new agent with no prior chat context.
- Give it only the repo plus the project-brain path.
- Ask it to recover:
- the project goal,
- the current phase,
- the latest important decision,
- the active blocker,
- the best next action,
- the first artifact or file it should inspect.
- Compare the answer against
current-state.md,decision-log.md, and the latest session/handoff notes.
The drill passes when a restarted session can recover the work from files alone.
If it fails, fix the files before you fix the prompt. The whole point of the project brain is to move durable context out of ephemeral chat state.
What to do if this still feels fragile
If the pattern still feels shaky, the problem is usually one of three things:
- The files are not durable yet. Fix state, workspace, and write-permission issues first:
- The workers are not clearly separated. Fix routing and role boundaries before you multiply handoffs:
- The work is not visible enough. Add a task board so execution leaves evidence:
The success condition is not a beautiful vault. It is boring recovery. If a fresh session can reconstruct the project from the files, the brain is working.