Claude Code second brain: build yours with Markdown

A Claude Code second brain can start as a normal folder of Markdown notes, a short router, and a test that checks whether Claude finds the right evidence. "Second brain" is our editorial name for this workflow, not an Anthropic feature or an extra Claude Code memory system.

The goal is not to make Claude remember everything. It is to make useful knowledge findable, current, and traceable to a source. This independent guide is not affiliated with Anthropic, and the vault structure below is a claude/for method rather than an official template.

Start with questions, not a folder taxonomy

Write five questions you genuinely expect the system to answer. They determine what you need to store and how you will know retrieval worked.

Use a fictional project called Atlas for a safe first run:

1. When is Atlas scheduled to launch?
2. Who owns the user-research synthesis?
3. Why did the go-live date move, and who owns that decision?
4. Which launch date is current, and what superseded the old date?
5. What is the approved launch budget?

The fixture contains an old August 15 plan, a current September 3 decision, a compliance-review reason, and named owners. It mentions a budget discussion but no approved amount. A good answer to question five is "the vault does not say," with a supporting path. A guessed number fails.

Build the smallest useful Markdown vault

Create this structure in a disposable folder:

second-brain-vault/
├── CLAUDE.md
├── vault/
│   ├── INDEX.md
│   ├── _inbox/
│   ├── sources/
│   ├── projects/
│   ├── decisions/
│   ├── meetings/
│   └── people/
└── tests/
    ├── questions.md
    ├── answer-key.md
    └── scorecard.csv

_inbox holds material you have not checked. sources preserves original evidence or a stable source record. The other folders hold canonical notes: the current summary you expect Claude and a colleague to trust.

Obsidian is optional. Its official vault guide describes a vault as a folder on your local filesystem, so you can open this same folder in Obsidian without turning it into a proprietary database. If portability matters, its link documentation recommends standard Markdown links over application-specific Wikilinks.

Normalize one decision like this:

---
title: Atlas launch date decision
source: meetings/2026-07-02-atlas-steering.md
sourceDate: 2026-07-02
capturedAt: 2026-07-11
owner: Maya Chen
status: current
aliases:
  - Atlas release date
  - Atlas go-live
---

## Decision
Move the Atlas launch from August 15 to September 3.

## Why
The compliance review needs two additional weeks.

## Supersedes
- [Original launch plan](../projects/atlas-original-plan.md)

These fields are our proposed starter schema, not Claude Code requirements. sourceDate tells you when the evidence was created; capturedAt tells you when it entered the vault. status separates current from superseded notes. aliases covers normal wording changes without duplicating a note.

Obsidian stores note properties as YAML, according to its properties documentation. You can also edit the same text in any Markdown editor.

Add a small router, not the whole knowledge base

Put only these retrieval rules in the root CLAUDE.md:

# Knowledge retrieval
- For vault questions, read `vault/INDEX.md` first.
- Follow the narrowest relevant path and cite each note used.
- Prefer `status: current`. Report conflicts or missing facts instead of guessing.

Then make vault/INDEX.md a short map:

# Vault index
- Project scope, owner, or status: `projects/`
- Decision changes and reasons: `decisions/`, then the linked source
- Dated conversations: `meetings/`
- Roles and responsibilities: `people/`
- Original evidence: `sources/`

## Current projects
- Atlas: `projects/atlas.md`

"Router" is a metaphor. CLAUDE.md is guidance, not a programmable routing engine. Anthropic's memory documentation says Claude Code treats it as context rather than enforced configuration.

The pattern matches Anthropic's context-engineering guidance: keep lightweight paths available, then load deeper files just in time. The context-window documentation also explains that each file Claude reads adds material to active context. Loading the whole archive at startup would defeat the point.

This vault is ordinary reference knowledge, not auto memory. The Claude Code memory guide explains the official cross-session mechanisms. For the wider decision about what evidence one task needs, use Claude Code context engineering.

Run a known-answer retrieval test

Freeze answer-key.md before asking Claude anything. Give each answer its supporting path, including the expected "unknown" for the budget question.

To test the structure rather than merely quiz one vault, make a scattered baseline with the exact same facts and source text. Give its files inconsistent names and remove the router, index, aliases, and status fields. Do not give the normalized version extra evidence. Run both folders under the same conditions and hide the variant labels from whoever scores the answers.

Five questions allow 20 points per variant in each run. This scorecard is our editorial test, not an Anthropic benchmark. This fixture has not been tested with Claude Code for this article, and we have not preserved the three-run comparison. We therefore report no accuracy, token, time, or before-and-after result.

Claude Code verification shows how to preserve a checkable evidence receipt instead of accepting a confident completion message.

Repair measured misses before adding infrastructure

Start with the failure you observed. Rename an ambiguous file. Add a real alias. Fix an index route. Mark one conflicting note superseded. Link a canonical note to its source. If the fact does not exist, record the gap and ask the owner rather than generating an answer.

Consider embeddings only when repeated paraphrased questions miss relevant notes after reasonable aliases and routes are in place. Similarity search can retrieve a related passage while missing the full chronology, total, or decision context the answer needs.

Consider a knowledge graph only when saved tests repeatedly fail on typed, multi-step relationships, such as who approved what for which client. You also need stable entity names, relationship definitions, provenance, and an owner who will correct stale links. A striking graph view is not proof that this machinery is useful.

If note ingestion becomes a stable repeated procedure, a Claude Skill can hold that process. Keep the knowledge itself as inspectable files.

Where this setup still fails

Claude can follow the wrong route, overlook a file, trust a stale note, or misread two correct sources. A router improves discovery but does not guarantee recall or truth. Re-run the scorecard when the folder structure or important source material changes.

Local Markdown also does not mean model processing stays on your device. Anthropic's data-usage documentation explains that Claude Code sends prompts and model outputs over the network, with retention and training policies depending on the account and settings. Its application-data reference says file contents that pass through tools can also land in local plaintext transcripts.

Do not place passwords, API keys, regulated data, or unrestricted client archives in a beginner vault. If working inside folders and reviewing access is still unfamiliar, begin with Claude Code for non-developers.

Can Claude Code use Obsidian as a second brain?

Yes. Claude Code can read accessible Markdown files inside an Obsidian vault. Obsidian is optional: it edits and visualizes the folder, while Claude Code works with the underlying files.

Does Claude Code remember every note in a vault?

No. Ordinary notes are not all loaded automatically or recalled perfectly. Claude searches and reads files as it works, so routes, citations, current-status labels, and known-answer tests still matter.

Do I need a vector database for a Claude Code knowledge base?

Not by default. Start with clear filenames, aliases, canonical notes, and a tested index. Investigate semantic retrieval only when repeated paraphrase misses remain after those simpler repairs.

For more practical guides built around observable evidence, browse the independent Claude Code desk.