I've always wanted to keep notes, somewhere I'd actually return to them. The thing that stopped me, every time, wasn't the app. I've tried Notion, Obsidian, Bear, Apple Notes. It was figuring out how to organize them. I can't sit comfortably with a pile that isn't organized well, so I'd stall before I started, rearranging folders in my head instead of writing anything down.

For a while I thought I'd organize notes the way I refactor code: a clean hierarchy, everything in its proper place. But notes aren't code. They don't have to be filed into one correct tree, and the organizing doesn't have to be my job. A second brain only works if it stays organized, and staying organized is a separate job from the thinking you're actually trying to do. So I decided to hand that job to an agent: I'd feed it the raw thoughts, and it would work out the structure and keep it current.

What I wanted was a knowledge base an AI agent could navigate and maintain for me, without a vector database, without a managed service, without any infrastructure. Just Markdown files and enough structure that any agent could find its way around.

So I built the Knowledge Base Builder, an Agent skill that turns a folder of notes into something an LLM can traverse. Then I used it on myself.

The approach is called progressive disclosure. It's a UX Design Concept, and it works really well with AI Agents. Every folder has an index.md listing its contents with one-line summaries. Every note has a summary in its frontmatter. The root index.md carries a navigation protocol that tells any agent how to explore the base. When an agent needs to answer a question, it reads the root index, scans summaries, and opens only the notes that look relevant. No embeddings, no database, no search service. The filesystem is the state; Markdown is the wire format.

Here's a hypothetical example: the structure matches the real layout, but the file names are made up:

second-brain/
├── CLAUDE.md
├── index.md
├── projects/
│   ├── index.md
│   ├── api-gateway-redesign.md
│   └── onboarding-flow.md
├── ideas/
│   ├── index.md
│   ├── cli-for-deployments.md
│   └── weekly-digest-bot.md
├── research/
│   ├── index.md
│   ├── observability-tools.md
│   └── event-driven-architecture.md
└── epiphany/
    ├── index.md
    ├── feedback-loops-matter.md
    └── scope-creep-signal.md

I started with an empty directory and a single instruction in CLAUDE.md (a file Claude Code reads at the start of every session): whenever I share anything worth preserving, extract knowledge from it and integrate it into the structure. Then I just talked. Literally: I use Claude Code on mobile and give most of my input by voice. A thought goes in at the speed I'd tell it to a friend. It doesn't have to survive the delay between having an idea and finding a keyboard.

Over one session, the base grew to cover specs for projects I'm building, raw ideas not yet ready to be projects, research on agent frameworks and coding tools, a content strategy, and two personal realizations I'd captured while they were still fresh. The agent organized each one, wrote the frontmatter summary, updated the relevant index.md, and kept the root index current. I never touched the structure myself.

That CLAUDE.md instruction is the part that makes it work longer than two weeks. Without it, I'd still be manually deciding where each note goes. With it, every conversation becomes a knowledge capture session by default.

Here's the CLAUDE.md that drives the whole thing:

# The Second Brain
 
This directory is a personal knowledge base — a second brain for capturing ideas,
projects, and session notes.
 
## Agent Behavior
 
**Every interaction should contribute to the knowledge base.** When the user shares
information, thoughts, plans, or asks questions, the agent should:
 
1. Answer or assist with the immediate request
2. Proactively extract meaningful, durable knowledge from the conversation
3. Use the `/knowledge-base-builder` skill to organize and integrate that
    knowledge into the existing structure
 
## Knowledge Base Skill
 
Always use the `knowledge-base-builder` skill (via `Skill tool`) when:
- The user shares new ideas, projects, or plans
- A conversation surfaces information worth preserving
- Notes or content need to be organized or indexed
- The user asks to "save", "remember", "add", or "organize" something
 
The skill creates `index.md` files and per-note summaries that make the knowledge
base navigable without a vector DB.
 
## Git Sync
 
This knowledge base is a git repository synced to GitHub. The agent should commit
and push to remote:
- Automatically, when there are 10 or more file changes accumulated since the
    last commit
- Immediately, when the user explicitly asks to commit or push
 
Commit messages should be concise and describe what was added or updated (e.g. "add
runbook skill spec and blog post draft", "update research notes with agent isolation
and social automation").
 
## Structure
 
- `ideas/` — seeds and concepts before they become projects
- `projects/` — engineering project notes, plans, and progress logs
- `research/` — deep-dive notes and curated resources by topic
- `epiphany/` — personal realizations worth capturing before they fade
- `index.md` — top-level index of the knowledge base

Every note follows the same pattern: frontmatter with a summary, then content.

---
title: Runbook Skill — Spec
created: 2026-06-16
status: shipped
tags: [claude-code, skill, runbooks, automation, devops]
summary: A Claude Code skill that reads a Markdown runbook and executes it step by step.
---

The summary field is what makes the whole thing navigable. When an agent scans an index.md, it reads summaries, not full notes. A good summary lets the agent decide in one sentence whether to open the file. I've learned to be specific: too vague and the agent has to open everything; too narrow and it misses related questions.

A few days in, I opened Claude Code on my phone, started a fresh session with no context, and pointed it at my second brain GitHub repo. Then I spoke a question out loud. It found the right note. That was the moment I stopped treating this as an experiment.

I haven't touched the organization since I set it up.