Second Brain Structure

A ready-to-use second brain for entrepreneurs, operated by Claude.

Clone it, answer a fifteen-minute interview, and get a personalized knowledge workspace: plain markdown under git, typed frontmatter, and an assistant that files, distills, and retrieves everything about your work. Runs in Claude Code (terminal, desktop app, IDE, web) and in Claude Cowork if you never want to touch a terminal.

Where a note-taking app stops at storage, this workspace keeps going: every artifact gets a predictable address, a typed schema, and wiki-link relations, so an agent (or you, six months from now) can find it from the question alone.

Why

The trigger is always the same story: a commitment made in a meeting that nobody wrote down, a brief buried three email threads deep, a client call that starts with five minutes of "where did we leave off". The notes exist, but they live in a doc here and an inbox there, and nothing connects them.

A second brain only works if filing is effortless and retrieval is instant. This one is built agent-first: strict path conventions, typed YAML frontmatter, and generated indexes make the whole workspace navigable by Claude, whether you run Claude Code or Claude Cowork. You paste an email or dump your meeting notes; the agent identifies what it is, files it at the right path with the right name and the right schema, and pulls the full context back before your next call.

Methodologies like PARA or Zettelkasten rely on your discipline to keep the system coherent. Here the discipline is encoded in the structure and enforced by the tooling, and your only ritual is a weekly fifteen-minute review.

Features

• Guided first-run setup (/sb-init): a coach-style interview (why you need this, how you work, how you communicate) that writes your charter and business context, configures your profile (agency, freelance, solopreneur, personal), and prunes the zones you will not use.
• Three-zone architecture: sources/ for raw artifacts, knowledge/ for distilled patterns, atlas/ for maps and entities, plus an inbox/ buffer and archives/ for retired projects.
• Predictable addressability: strict naming (YYYY-MM-DD-{type}-slug.md), one canonical location per artifact, generated indexes. The agent guesses the path from the question alone.
• 15 typed schemas: every note carries YAML frontmatter validated against a canonical schema (email, meeting, research, decision, person, client context, ...), so structure survives at scale.
• Daily capture (/capture): paste an email, a transcript, raw notes or an idea; the skill detects the content type, resolves the target entity and project, and files it with schema-correct frontmatter. -i processes the aged inbox item by item.
• A curation cycle that keeps it alive: /curate scans and proposes, /distill promotes recurring patterns into reusable knowledge, /moc-new maps dense topics, /archive retires dead projects. Human validation on every action.
• Office skills included: emails calibrated on your own voice and each contact's preferences, meeting minutes, commercial proposals, summaries, and a weekly activity dashboard.
• Health check (/sb-doctor): nine read-only checks covering orphan notes, broken conventions, frontmatter drift, stale indexes, and inbox age.
• Semantic search (optional): Basic Memory indexes the workspace into a local knowledge graph the agent queries through MCP. Local-first, nothing leaves your machine.
• Obsidian-ready: graph color groups preconfigured, Dataview live indexes plus agent-readable static versions generated by script.
• A demo client in the box: a fictional client (Globex) with context file, emails, meeting notes and distilled knowledge, so you can see the system working before filing anything real.
• No lock-in: plain markdown under git. No database, no proprietary format, readable with any editor, works offline.

Quickstart

1. Get the workspace

git clone https://github.com/philippe-desplats/second-brain.git my-second-brain

Or click Use this template on GitHub to start from your own repository (then clone it, or download it as a ZIP if you do not use git). Either way, keep your copy private: it will hold your clients, your emails, your strategy.

2. Run the guided setup

With Claude Code (terminal, desktop app, or IDE): open the folder, start a session, and launch the setup skill.

cd my-second-brain
claude

/sb-init

With Claude Cowork (no terminal): in the Claude desktop app, open Cowork, click Work in a Folder, select the my-second-brain folder, then ask:

Read .claude/skills/sb-init/SKILL.md and run the setup interview.

Both paths run the same interview: why you want a second brain, what your work looks like, how you communicate. The assistant then writes your charter and context files, configures the workspace for your profile, and optionally wires up Basic Memory for semantic search. Nothing is written before you approve a recap, and /sb-init -r reconfigures an initialized workspace later. Fifteen minutes in, you have a working system, not an empty folder. More on the surface differences in Run it your way.

3. Start filing

Read GETTING-STARTED.md for your first week with the system. The short version: feed the one flow that matters most to you first (the interview identifies it), drop anything unclear into inbox/, and run /curate -w 7 once a week.

Run it your way

The workspace is plain files plus markdown instructions, so any Claude surface that can read a folder can operate it:

Surface	Experience
Claude Code, terminal	The full experience: skills as slash commands (/sb-init, /capture, /curate), maintenance scripts, git integration
Claude Code, desktop app / IDE / web	The same skills and slash commands wrapped in a UI; open the cloned folder and work from there
Claude Cowork	No terminal at all: connect the folder via "Work in a Folder", the workspace instructions are picked up as folder context, and you drive everything conversationally
Codex CLI, OpenCode, Gemini CLI, Cursor	A root AGENTS.md orients any agent that reads the AGENTS.md standard; skills follow the open SKILL.md format these tools recognize, and Basic Memory is a standard MCP server (per-tool wiring snippets in AGENTS.md)

Skills are plain markdown instructions in .claude/skills/, not binaries. On a surface without slash commands, invoke them by asking: "read .claude/skills/capture/SKILL.md and file this email". The conventions (paths, naming, frontmatter) live in CLAUDE.md and .claude/rules/, which every surface reads the same way. Claude Code remains the reference experience; other agents are supported on a best-effort basis.

See it working before filing anything real

The workspace ships with a complete fictional client so the conventions are visible instead of theoretical:

sources/clients/globex/CLAUDE.md          # client context: preferences, contacts, stack
sources/clients/globex/website-redesign/  # a project: brief, emails, meeting notes
knowledge/ops/playbook-client-onboarding.md   # knowledge distilled from that work
atlas/people/jane-doe.md                  # a person file, wiki-linked everywhere

Open a session and ask things like "what do we know about Globex?" or "prepare a brief before my call with Jane Doe" to see retrieval in action. When you are done exploring, /sb-init offers to remove the demo, and .claude/skills/sb-init/references/demo-manifest.md lists every demo path if you prefer to delete it by hand.

The architecture: three zones

Every note lives in one of three primary zones, decided by three questions:

Question	Zone	Contents
Is it a raw artifact (email, meeting notes, deliverable, research)?	sources/	The raw material of your work, filed by entity and project
Is it distilled, reusable knowledge (pattern, playbook, guide, runbook, decision)?	knowledge/	What you learned, independent of any single client or project
Is it a map, an index, or a referenceable entity (person, topic, service)?	atlas/	The navigation layer: entry points, indexes, entity files

Two utility zones complete the picture: inbox/ (a buffer for unclassified captures, seven days maximum) and archives/ (a mirror of sources/ for dead projects, moved physically with git mv).

flowchart TD
    A[New information] --> B[inbox/ 7-day buffer]
    A -->|clear destination| C[sources/ raw artifacts by entity and project]
    B -->|classified| C
    C -->|/distill on the 3rd repetition| D[knowledge/ reusable patterns and playbooks]
    C -->|/moc-new when a topic reaches 10+ notes| E[atlas/ maps, indexes, entities]
    D --> E
    C -->|/archive after 6 months inactive| F[archives/ mirror of sources/]

Loading

What keeps it alive: the curation cycle

A second brain is maintained, not built once. Four skills form the loop:

Skill	Role	Trigger
/curate	Scans the workspace and proposes distill / archive / map actions	Weekly review (-w 7)
/distill	Promotes a recurring pattern from sources/ into knowledge/	Third repetition of the same topic
/moc-new	Creates a Map of Content in atlas/maps/	A topic reaches 10+ notes
/archive	Moves a dead project from sources/ to archives/	Project done or cancelled for 6+ months

A librarian agent orchestrates the cycle: it scans, scores candidates, and recommends. It never writes or moves anything without your approval.

The skills

Thirteen skills ship with the workspace, routed through .claude/skill-registry.md. The daily drivers are /capture (inbound filing), /curate (the weekly review), and the office suite for outbound work.

Full skill registry

Skill	What it does
/sb-init	Guided initialization and reconfiguration (-q quick, -r reconfigure)
/capture	File inbound content at the conventional path with schema frontmatter (-i inbox mode)
/sb-doctor	Workspace health report, nine read-only checks
/curate	Weekly or monthly review, proposes curation actions (-r report-only)
/distill	Promote a recurring pattern into knowledge/ with provenance and back-links
/moc-new	Create a Map of Content for a dense topic
/archive	Retire a dead project via git mv, fixing references
/ops-resume	Summarize raw content (transcript, notes, article)
/ops-email	Draft emails calibrated on your voice and the recipient's preferences
/ops-meeting-minutes	Turn notes or a transcript into structured minutes
/ops-proposal	Draft a commercial proposal, never invents pricing
/ops-init-project	Bootstrap a new project folder with proper structure
/ops-weekly-pulse	Dashboard of the week's activity across all zones

Structure

├── CLAUDE.md            # Instructions loaded by Claude Code in every session
├── AGENTS.md            # Orientation for other agents (Codex, OpenCode, Gemini CLI)
├── sources/             # Raw artifacts: {entity}/{project}/{emails|meetings|deliverables}
├── knowledge/           # Distilled knowledge: ops/ tech/ business/
├── atlas/               # Navigation: home.md, people/, topics/, services/, maps/
├── archives/            # Mirror of sources/ for inactive projects
├── inbox/               # 7-day buffer for unclassified captures
├── basic-memory/        # Schemas (typed frontmatter) and maintenance scripts
├── templates/           # Note templates (entity context, email, map of content)
└── .claude/             # Skills, rules, agents, skill registry

Requirements

• Claude (required): Claude Code in the terminal, desktop app, IDE extension, or web for the full skill experience; or Claude Cowork for a terminal-free workspace.
• Basic Memory (recommended): local semantic search and knowledge graph over your notes. /sb-init guides the installation (uv tool install basic-memory).
• Obsidian (optional): a pleasant reading and graph view. Install the community plugin Dataview to render the live indexes in atlas/maps/; agent-readable static versions are generated alongside them either way.

Conventions at a glance

• Notes are named YYYY-MM-DD-{type}-slug.md (types: research, brainstorm, writing, meeting, strategy, note).
• Emails are named YYYY-MM-DD-{seq}-{direction}-slug.md (direction: out, in, reply).
• Nothing lives at an entity's root except its CLAUDE.md context file; every artifact belongs to a project folder.
• Every note carries typed YAML frontmatter conforming to one of the canonical schemas in basic-memory/schemas/.
• Secrets never enter the repo: .mcp.json is gitignored, use .mcp.json.example as the starting point.

Keeping your clone up to date

Once cloned, your workspace diverges from this boilerplate by design: your notes are yours. But the infrastructure (skills, rules, schemas, scripts, templates) keeps improving upstream. To pull infrastructure updates without ever touching your data:

git remote add upstream https://github.com/philippe-desplats/second-brain.git   # once
git fetch upstream
git diff HEAD upstream/main -- .claude basic-memory templates   # review first
git checkout upstream/main -- .claude basic-memory/schemas basic-memory/scripts templates
git commit -m "chore: update workspace infrastructure from upstream"

Your data zones (sources/, knowledge/, atlas/, archives/, inbox/) are never part of that checkout. Review the diff before applying: if you customized a skill or a schema locally (for example the service_type enum set by /sb-init), re-apply your customization after the update or exclude that file from the checkout.

Philosophy

Markdown because it survives every tool change. Git because history matters. Typed frontmatter because agents need structure to be reliable. Human validation on every curation action because a second brain you cannot trust is worse than no second brain at all.

Contributing

Bug reports, skill ideas, and pull requests are welcome. See CONTRIBUTING.md for how to report issues, the contribution flow, and the conventions a change must respect.

Acknowledgements

The term "second brain" was popularized by Tiago Forte's Building a Second Brain, and the zone design owes ideas to PARA and the Zettelkasten tradition. The layered architecture (immutable raw sources, an agent-maintained distilled layer, schemas that govern the workflows) echoes Andrej Karpathy's LLM Wiki pattern. The agent-first layer is made possible by Claude Code and Claude Cowork, Basic Memory, and Obsidian with Dataview.

License

MIT