eps1.4AI

How to build a second brain with Claude Code and Obsidian

Context Engineering and your AI agent's knowledge base.

7 min read

When you need to remember why the team made a technical decision three months ago, where do you look? Probably in four places: a Slack thread, a comment on a card, a Google Doc nobody has opened since, and the head of whoever was on the call.

The information exists. It just isn’t where you’re looking.

In the previous posts we covered the context window, the agent’s short-term memory, Rules and Skills, which work as long-term memory, and Spec-Driven Development, which turns specs into the source of truth. Now another piece is missing: the knowledge base the agent looks things up in to answer about your context, not about the internet.

This pattern has a name: LLM wiki. And to build yours, you only need two tools: Obsidian to write and Claude Code to query.

Who came up with the idea

The term comes from Andrej Karpathy. He was a founding member of OpenAI and later Tesla’s director of AI, where he led the Autopilot computer vision team. Today he’s one of the most widely read voices on how to work with LLMs day to day. He’s the one who popularized the term “vibe coding”, for example.

The proposal is in a gist he published in April 2026, and the core idea is simple: your notes and documents, organized in markdown, can become a knowledge base an LLM can reason about. Instead of hunting for information in Notion, Google Docs and sticky notes, you ask and the agent reads your base.

The original gist is worth reading, because his proposal is more ambitious than what we’ll build here. Karpathy splits it into three layers: the raw sources (documents the LLM reads but never changes), the wiki itself (the markdown pages, maintained by the LLM) and the schema (a configuration file, like CLAUDE.md, that defines the conventions). And he describes three operations on top of that: ingest (a new source comes in and the LLM updates the affected pages), query (you ask, and a good answer can become a new page) and lint (the LLM sweeps the wiki looking for contradictions, orphan pages and gaps).

That’s where it differs from traditional RAG: instead of retrieving chunks of text on every question, the LLM keeps building an artifact that accumulates. He compares it to the Memex, which Vannevar Bush imagined in 1945, with the difference that now there’s someone willing to keep the links up to date.

In this post we’ll build a minimal version of it, where you write the notes and Claude queries them. That’s enough to solve the problem from the beginning, and you can bring in the other operations later.

And here’s the most important point: this isn’t a product. There’s no app to install and no service to subscribe to. It’s a workflow pattern. You already have everything you need.

The difference is where the agent looks

When you ask an LLM something without context, it answers based on public documentation. The answer is generic: it doesn’t know the names of your modules, your decisions or the path the team ruled out during refinement.

When you point the same LLM at a folder with your notes, the answer is anchored in what the team has already written, with the history of the decision and the path of the file it came from.

It’s the same difference as asking a stranger versus asking someone who has read your docs.

The architecture has three components

The architecture of an LLM wiki is minimal:

1. A folder of markdown files. This is your knowledge base. It can hold anything: research notes, meeting summaries, project docs, book notes, personal reference, code snippets with explanations.

2. A consistent structure in every file. Title, a one-line summary, tags and the content. Always in the same format. That structure is what the model uses to find the relevant information faster.

3. Claude Code as the search interface. You open the terminal, go to the wiki folder, open Claude and ask your question. It reads the files it needs, synthesizes the answer and can even update the notes, if you ask.

That’s it. No database. No server. Just files and a capable model.

Why markdown is the right foundation

This choice isn’t a detail. Markdown solves four problems at once.

It’s portable. An .md file is plain text. It opens in any editor, on any operating system.

LLMs read markdown natively. Models like Claude were trained on a huge amount of markdown text: GitHub READMEs, documentation, websites, forums. The syntax is part of what they understand: headings, lists, code blocks, bold. The model reads it as structure, not noise.

It forces clarity. To write in markdown you have to name the sections in headings and split items into lists. The format pushes you to organize.

Plain text means zero lock-in. You sync it with Git, open it in VS Code, view it in Obsidian, push it to a private repository, read it in the terminal. The knowledge is yours.

Setting up the wiki in Obsidian

Obsidian is the recommendation for this workflow. It’s a local-first markdown app with a clean interface. Your files live on disk; Obsidian is just how you read and write them.

Step 1: install Obsidian and create a vault

Download it from the official site and create a new vault in a folder you’ll remember, like ~/wiki or ~/Documents/llm-wiki. A vault in Obsidian is just a folder. Everything is plain markdown.

Step 2: define a note template

Consistency is what makes your wiki queryable. Create a file at _templates/note.md:

# Note title

**Summary**: one sentence describing this note.
**Tags**: #topic1 #topic2
**Created**: 2026-08-21
**Updated**: 2026-08-21

---

## Content

The main content goes here.

## Related notes

- [[Title of another note]]

You don’t have to follow this exactly. The key is that every note has a summary line and its tags. That lets Claude judge whether a file is relevant without reading the whole thing.

Step 3: organize by topic

Don’t over-engineer this. Start with four or five top-level folders:

wiki/
├── _templates/
├── projects/
├── research/
├── reference/
├── meetings/
└── inbox/

The inbox/ folder holds notes that haven’t been organized yet. Claude helps you sort them later.

Step 4: write the first notes

Migrate from wherever your knowledge lives today. Start with what you look up over and over: processes you’ve already documented, concepts you’ve researched, decisions you’ve made and why.

Don’t try to import everything at once. The wiki grows naturally as you add notes.

Step 5: install Claude Code

If you don’t have it yet, install it. It’s your wiki’s search interface.

Step 6: query the wiki

Open the terminal, go to the folder and run Claude. Now you can ask:

  • Why did we decide to use a webhook instead of polling in that flow?
  • What was left pending from last week’s refinement?
  • Has this problem shown up before in any project?

Claude will read the files, figure out what’s relevant and answer.

Don’t forget the CLAUDE.md

This is where the LLM wiki meets the subject of the previous post. Your vault needs Rules too: a CLAUDE.md at the root explaining what lives in each folder and how the agent should work:

# My second brain: instructions

## About me
I'm a software engineer. I work on 3 to 4 projects at a time and
need help synthesizing research and tracking decisions.

## Vault structure
- /inbox: notes I haven't processed yet. Start here.
- /projects: one folder per project. Active ones have `status: active`.
- /meetings: call summaries, with what was left pending.

## Session protocol
At the start:
1. Read today's note (/inbox/YYYY-MM-DD.md)
2. Sweep /inbox for unprocessed notes
3. Check what's tagged #review

At the end:
1. Write the session summary in /sessions/YYYY-MM-DD.md
2. Update today's note with what was done

Without it, you re-explain the context every time you open a new session. With it, today’s summary is tomorrow’s starting point.

Good practices for a wiki that stays useful

1. Write summaries, not just content. A one-line summary takes 10 seconds and saves a lot of tokens on every query.

2. Use consistent terminology. If you write “RAG” in some notes and “Retrieval Augmented Generation” in others, the model can connect the two. But the result is better if you pick one term and always use it.

3. Link notes to each other. Obsidian lets you make that connection with [[wikilinks]], and that’s why it works so well here. A connected wiki becomes a graph, and a graph beats hundreds of isolated files.

4. Keep notes focused. A 10,000-word document is harder to pin down than 10 documents of 1,000 words. If a note covers several topics, split it. The more specific each file, the more precise Claude can be.

5. Use /inbox as your capture default. Don’t let perfect be the enemy of useful. Drop the raw note in the inbox and periodically ask Claude to organize it.

Beware of premature optimization

Reading the files directly works well for hundreds of documents. Beyond that, there are two paths.

The first is RAG. A tool like LlamaIndex lets you build a vector index over your markdown files, and Claude fetches only the most relevant chunks before answering.

The second is writing a Skill that pre-filters the notes, summarizes sections and routes the query, cutting tokens on every question.

But if you’re just starting, both are overkill. It’s premature optimization. Start by reading the files directly and only switch when you hit the limit.

How to decide if it’s worth it for you

The question is simple: is the knowledge you look up most spread across more than two tools?

If so, you don’t need a new platform. You need a folder, a note template and an agent that can read markdown.

And getting started is smaller than it looks: create the folder, write a note about the last technical decision you made (with the why) and ask the first question. The wiki grows as you use it.

References

If you want to follow the series, the previous posts are about the context window, about Rules and Skills and about Spec-Driven Development.

Up next