Vault structure and debugging
Organize a markdown vault as searchable second memory. Triage the four failure modes when Claude does something unexpected.
STATE.md and MEMORY.md hold what every session needs. A markdown vault (Obsidian or any folder) holds everything else: strategy notes, meeting transcripts, project journals, research, competitive analysis.
The vault grows into institutional memory: decisions you made six months ago and why, reference materials that inform current work, patterns that span projects. Connect it via an Obsidian or filesystem MCP and Claude can search the whole thing on demand. Without the vault, this knowledge exists only in your head or buried in old documents.
Why markdown beats a database: plain files are greppable, version with git, open in any editor, and survive every tool change. A working structure:
~/notes/
├── STATE.md # Always loaded
├── MEMORY.md # Index, always loaded
├── STRATEGY-DIGEST.md # Summaries of strategy docs
├── strategy/ # Full docs, read on demand
├── projects/ # Dated project notes
├── resources/
└── reference/The scaling key is the digest pattern: when you write a 1,000-word strategy doc, write a 3-sentence digest alongside it and index the digest in MEMORY.md. Claude reads about 50 tokens at session start instead of the full doc's roughly 1,500. At 25 strategy docs, that is 1,250 tokens versus 37,500, and sessions stay fast.
When Claude does something unexpected, check four failure modes in order, most to least common:
Stale memory: STATE.md says one thing, reality says another. Claude followed your instructions perfectly; the instructions were wrong. Ask "Show me your STATE.md" first, every time.
Missing context: the relevant file was never loaded, so Claude made a reasonable guess. Load the file explicitly and re-ask.
Tool unavailable: an MCP is down or a hook blocked a command, and Claude worked around it badly. Check tool availability before blaming the reasoning.
Hallucination: the rarest cause. Verify first: grep for the function, check the endpoint exists. Most "hallucinations" turn out to be one of the first three.
One diagnostic question per failure mode:
Stale memory: "What does your STATE.md say about [topic]?" Content from three sessions ago means stale state.
Missing context: "What files do you have loaded about [topic]?" No relevant files means load the right one.
Tool unavailable: "What tools do you have available right now?"
Hallucination: "Grep for [function/endpoint] and show me what you find."
The sequence takes two minutes and finds the cause almost every time. Jumping straight to "Claude hallucinated" usually delays the real fix by rewriting code that did not need rewriting.
Prevention beats debugging. The habits:
End-of-session STATE.md update. Eliminates 80% of stale memory issues.
Archive shipped projects into dated project_* files.
Monthly MEMORY.md audit: confirm every pointer still points to an existing file.
Digest every doc over 500 words.
Write decisions at the moment of decision, not at week's end. Retroactive capture loses the reasoning.
Before archiving project notes, extract the durable lessons into feedback_* entries. The project becomes history; the lessons stay active.
A vault with 10 well-maintained documents beats one with 200 stale ones. Quality and currency beat volume.
With an Obsidian or filesystem MCP, the vault becomes a live knowledge base:
Decision archaeology: "Search the vault for why we chose Postgres over MySQL." A 10-minute manual hunt becomes 15 seconds.
Pattern detection: "Find all mentions of rate limiting issues or 429 errors across projects." Claude surfaces a common root cause spread across five project files.
Reference lookup: "Find the contact information in the vendor notes." Instant retrieval from unindexed files.
Search quality depends on naming consistency: project_[name]_[date].md and feedback_[rule].md beat whatever felt natural at the time. Naming conventions are the index you build before you need it.
All four modes check out clean and the output is still wrong? Two causes look like hallucination but are not.
Context ordering: when loaded files conflict, later-loaded content tends to win. If old project notes contradict STATE.md, assign authority explicitly: "STATE.md is the current ground truth. It supersedes anything in project notes."
Constraint collisions: CLAUDE.md says "parameterize all SQL," so Claude rewrites SQL during what you meant as a style-only refactor. Not a bug; scope it explicitly: "Style only, do not change the SQL patterns."
The diagnostic for both: "What instructions are you following that govern [this decision]? List the rules in priority order." You will find a stale source, a conflicting rule, or a CLAUDE.md gap. All fixable.
A markdown vault with digest files scales your second memory; digests keep sessions fast, full docs load on demand. When Claude misbehaves, triage in order: stale memory, missing context, tool unavailable, hallucination, and always start with "show me your STATE.md." Feed the vault at the moment of decision and it compounds in value every week.