claude-second-brain

I had fifteen years of notes scattered across four machines and a dozen Claude projects, and a habit of migrating the whole mess into whatever notes app was hot that year. Every migration cost a weekend. So I stopped betting on apps and built a convention instead.

claude-second-brain is a folder of markdown files. That is the whole idea. It's a documented structure for organizing everything you know - personal life, work, side projects - as plain text that any tool can read and any tool can write. Claude Desktop reads it. Claude Projects reads it. The API reads it. A human in any editor reads it. When the next tool ships, it reads it too. The files outlive every tool.

There is no app to install. This repo is the convention plus a small set of scripts to set it up and keep it tidy.

The Three Rules

Everything follows from three design rules, in priority order:

• One source of truth, many readers - all knowledge lives as markdown under a single root folder. Every tool reads the same files. Nobody owns the data except you.
• Context cascades from general to specific - shared knowledge at the top is available to everything below it. Anything that primes an LLM walks up the tree and composes the context it needs.
• Works flat, works nested, works partial - an empty tree still works. Every file added makes it smarter. Migration is never required, only additive.

The Structure

The root holds the always-loaded anchors and the global context:

• MEMORY.md - a short, curated digest of who you are and your current focus. A few hundred words, always loaded.
• _journal/YYYY-MM-DD.md - a daily running log that cuts across every life area.
• _meta/ - global knowledge applied to every conversation: about-me, people, jargon, preferences.

Below that, the tree splits into life areas (one top-level folder per area of life), and each life area holds projects. Every project gets two optional but high-leverage files:

• _index.md - one paragraph describing what the project is. A classifier reads these to file ad-hoc notes into the right place.
• _meta/ - reusable context primed into any LLM call scoped to that project.

The highest-leverage files are the voice files: voice-calibration.md (how you write), anti-ai-writing-style.md (the LLM tells to avoid), thinking-models.md (how you reason), and global-instructions.md (the behavioral contract every LLM in the brain follows). Those are what make downstream agents sound like you instead of generic Claude. A _meta-private/ holds anything that should never sync to a work-managed account.

Multi-Device Sync

N devices, one truth. Each machine declares its role in a per-machine config file:

• Agent host (always-on) - holds a full copy and runs scheduled maintenance agents. A Mac Mini in my case, but a Linux mini-PC, NAS, Raspberry Pi, or cheap VPS works just as well.
• Interactive machines - the laptops you actually work on. Full sync, any OS that runs Claude or a markdown editor.
• Constrained machines - devices that should only see a subset. My Windows work laptop selectively syncs one life area plus the global _meta/, so it never touches personal data. The privacy boundary is enforced by the sync tool, not custom code.

I use Google Drive Desktop (native on Mac and Windows, folder-level selective sync built in). Syncthing and Dropbox are documented alternatives. The repo ships setup-sync-mac.sh to wire a Mac in, plus a Google Drive validation gate that stress-tests propagation lag, conflict frequency, and concurrent writes before you trust it.

The Maintenance Brain

Because one machine is always on, it runs scheduled agents that curate the brain over time: re-classifying stale inbox items, rendering a daily dashboard, summarizing mail across multiple accounts into the right life areas. None of these belong to any single app - each is a small scheduled script that calls a model and writes markdown back into the tree.

The agents are themselves markdown files: frontmatter (name, schedule, scopes, host) plus a plain-language description. Two ship as examples - a calendar sync and a daily dashboard renderer. Anything that writes back to the tree goes through a "propose, don't impose" review loop so nothing mutates your real files without approval.

The Stack

• Markdown for everything - the durable layer
• Claude (Desktop, Projects, API) as the primary reader and writer
• Google Drive Desktop for cross-device sync, with Syncthing / Dropbox as alternatives
• Bash for the per-machine setup tooling
• Python for the sync validation gate and the public-mirror publish script

The format is deliberately compatible with other markdown-native runtimes, so the brain isn't locked to any single one.

Why a Convention, Not an App

Because apps die and markdown doesn't. Every proprietary format is a future migration; every cloud-only app is a future shutdown notice. Committing to a structure rather than a product means the tools become interchangeable and the knowledge stays put. Claude is the best reader of this tree today, but if something better comes along, the brain comes with it.

Get Started

The repo is the documented convention with starter templates, a conversational setup interview you load into a fresh Claude session to populate your tree, the sync tooling, and worked examples of the maintenance agents. MIT licensed. It's early and in active daily use - convention first, tooling as the need becomes obvious.

I wrote up the full story of why I built it on the blog: A Second Brain That Outlives the Apps.