# Second Brain — Complete Technical Reference
> Not another AI. Memory for the one you have.
> A folder of plain files on your own computer that ChatGPT, Claude, Gemini or
> Copilot reads before answering, and writes back to after.
> No app, no vendor lock-in. Your file system IS the interface.
This document is the complete technical reference for the Second Brain system. It covers architecture, implementation details, the health check scoring system, getting started guides, and context engineering patterns. Written as documentation, not marketing.
Last updated: August 2026.
---
## Table of Contents
1. What Is a Second Brain
- Who It's For (the hub and eight role pages)
2. System Architecture (8 Layers)
3. Health Check System (38 Checks)
4. Getting Started
5. Context Engineering Patterns
6. Comparisons
7. Packages and Pricing
8. FAQ
9. About
---
# 1. What Is a Second Brain
A Second Brain is a structured file-system workspace that turns Claude Code from a general-purpose AI assistant into a personalized operating system for your work.
It is not an app. There is no UI to install, no SaaS dashboard, no browser extension. The Second Brain is a GitHub repository on your machine — a collection of markdown files, shell scripts, and configuration that shapes how Claude Code behaves when you open your terminal.
## The Core Idea
Claude Code already reads a `CLAUDE.md` file from your project directory and follows its instructions. Most people write a few lines of guidance and stop there. A Second Brain takes this mechanism and builds a full system around it:
- **CLAUDE.md** becomes a master configuration file with business context, workflows, and references to deeper documentation
- **Agents** (markdown files) define specialized AI roles — a chief of staff that queries your database, a content creator that knows your voice, an email writer that matches your tone
- **Skills** (executable workflows) let you type `/begin` to start a tracked development session or `/prospects` to review your sales pipeline
- **Memory** (structured directories) captures what happened in each session, graduates recurring patterns into reusable knowledge, and tracks goals with live metrics
- **Hooks** (shell scripts) enforce quality automatically — blocking edits on the wrong branch, syncing communications to your CRM, running type checks before you push
- **MCP servers** connect Claude Code to your actual tools — Gmail, Calendar, Stripe, your database, WhatsApp, LinkedIn
The result: Claude Code starts each session already knowing your business context, your preferences, your current priorities, and your past decisions. It doesn't just answer questions — it operates within your workflows.
## How It Differs from Other Approaches
**ChatGPT Projects / Claude Projects** are complementary. You keep using them. They store conversation memory inside a single application, which is useful within that app but cannot reach outside it, and cannot follow you if you switch tools. A Second Brain is memory you own: plain files on your machine that any of your AI tools can read, connected to your email, CRM, calendar and database through MCP.
**Notion AI** runs within the Notion sandbox. It can search your Notion pages and generate content within Notion's interface. A Second Brain runs in your terminal and can operate across any tool, any file, any API. You own the underlying repository — if you stop using it, the files are still yours.
**Obsidian with AI plugins** adds AI capabilities through community plugins. A Second Brain uses Claude Code natively — no plugins to maintain, no compatibility issues between versions. The AI isn't bolted on; the entire system is built for AI-first interaction.
**Building from scratch** is always an option. You could create your own CLAUDE.md, write your own agents, build your own skills. A Second Brain gives you 37 pre-built templates and a 38-check quality framework so you don't start from zero.
## What Claude Code Is
Claude Code is Anthropic's official CLI tool for Claude. It runs in your terminal, reads your file system, executes commands, and follows instructions from CLAUDE.md files. Key capabilities:
- **File system access**: Reads and writes files in your project directory
- **Tool use**: Calls external tools via the Model Context Protocol (MCP)
- **Agents**: Spawns specialized sub-agents for parallel work
- **Skills**: Executes user-defined /commands from SKILL.md files
- **Hooks**: Runs shell scripts automatically on lifecycle events (session start, before tool use, after tool use, on stop)
- **Memory**: Maintains a persistent auto-memory directory across sessions
The Second Brain is built entirely on these native capabilities. No custom software, no API wrappers, no middleware. Just files that Claude Code already knows how to read.
---
## Who It's For
The Second Brain ships as one hub and eight role pages. Each role page is the same product described for one kind of work; the hub is the general entry point.
- Hub: https://www.iwoszapar.com/second-brain-ai
- Consultants: https://www.iwoszapar.com/second-brain-for/consultants (#who-its-for-consultants)
- Marketers: https://www.iwoszapar.com/second-brain-for/marketers (#who-its-for-marketers)
- Solo Lawyers: https://www.iwoszapar.com/second-brain-for/lawyers (#who-its-for-lawyers)
- Founders: https://www.iwoszapar.com/second-brain-for/founders (#who-its-for-founders)
- ADHD: https://www.iwoszapar.com/second-brain-for/adhd (#who-its-for-adhd)
- Developers: https://www.iwoszapar.com/second-brain-for/developers (#who-its-for-developers)
- Forward Deployed Engineers: https://www.iwoszapar.com/second-brain-for/forward-deployed-engineers (#who-its-for-forward-deployed-engineers)
- Chiefs of Staff: https://www.iwoszapar.com/second-brain-for/chiefs-of-staff (#who-its-for-chiefs-of-staff)
### Consultants: https://www.iwoszapar.com/second-brain-for/consultants
**Walk into every client call already briefed.**
Iwo Szapar’s AI Second Brain gives your existing AI a private memory of your practice: every engagement, framework, rate card, and client preference, stored on your own computer. Prep briefs, proposals, and follow-ups start from your history instead of a blank page.
**The problem (The margin leak):** You bill for judgment. You spend it on recall.
**What it is used for:**
- **Walk in briefed**: Drop the Granola or Fathom transcript after every call. Before the next one: last conversation, open promises, who decides, suggested opener. (45 min → 2 call prep, illustrative)
- **Proposals from your own wins**: New SOW drafts pull from your past proposals, rate card, and frameworks, structured like the ones that closed. (3 h → 30 min per proposal, illustrative)
- **A pipeline that confesses**: Friday review sweeps every open thread and names the stalled ones, with the follow-up already drafted. (0 dropped threads, illustrative)
**How it answers:** Last conversation, the open promise, who decides, and a suggested opener, from your own files.
**Reads from:** clients/retainer/last-call.md, clients/retainer/promises.md, _your-practice/rate-card.md. Plain files on the buyer's own machine.
**A week of it:**
- MON asks "/prep retainer" → Prep brief · client call · assembled in 2 min
- TUE asks "drop: call-transcript.txt" → Filing agent · transcript processed
- THU asks "/proposal new-engagement" → Proposal draft · your structure, your pricing
- FRI asks "/weekly-review" → Weekly review · all four lanes scanned
**Questions this audience asks:**
- *Is an AI second brain worth it for an independent consultant?* Yes, if your engagements repeat in shape. It gives the AI you already use a private memory of your practice: past engagements, your frameworks, each client's preferences and your rate card. A prep or proposal command pulls only that client's context. It is a poor fit if every engagement is genuinely one of a kind.
- *My client work is under NDA. I cannot put it in an AI tool.* The memory lives in a repo on your computer, or your own Supabase account if you choose cloud. Nothing is shared with us or other users, and nothing trains a model. This setup exists because cloud chat tools fail the NDA test.
- *I'm not technical. A repo and a terminal sound like developer territory.* 69 percent of buyers are non-technical. Accelerator ($597) is a guided install: the AI agent configures everything from your questionnaire, then you work in plain English commands like /prep and /proposal.
- *I already have Notion or Obsidian full of client notes.* Keep them. Those store notes. They do not draft the proposal or brief you before the call. The Second Brain imports what you have and turns it into working memory that produces deliverables.
- *Will it mix up my clients?* Each client has its own memory folder. A prep or proposal command pulls only that client’s context. Separation is structural, not a prompt you have to remember.
- *Another subscription on top of everything?* One-time price. You own the repo and everything in it forever. Ongoing cost is just the AI subscription you already have.
- *I bill my time. When exactly do I set this up?* Starter is a weekend. Accelerator gets you live inside a week with guidance. If it saves two hours of non-billable prep and proposal work a week, it pays for itself in the first month at typical day rates.
**Recommended tier:** Accelerator ($597).
### Marketers: https://www.iwoszapar.com/second-brain-for/marketers
**One idea in. A week of content out. In your voice.**
Iwo Szapar’s AI Second Brain, pre-built for marketers. It learns your voice from your own best work, turns one idea into channel-ready drafts, and scores every draft against your bar before you see it. Installed once. Yours forever.
**The problem (The content treadmill):** You spend more time editing out the AI smell than writing.
**What it is used for:**
- **Webinar → twelve assets**: One recording, repurposed: LinkedIn posts, a newsletter, clip scripts, and a blog draft, each scored against your voice before it reaches you. (12 assets from one idea, illustrative)
- **Launch week, pre-written**: Feed the positioning doc; get the full channel calendar in your tone, ready for your edit pass. (5 days → 1 calendar build, illustrative)
- **Freelancers, on-voice**: Outside drafts run the same gate: banned phrases flagged, voice score under your bar bounces back automatically. (86/100 voice floor, illustrative)
**How it answers:** A post in your voice, on the campaign brief, built from hooks that already performed.
**Reads from:** voice.md, hooks/winners.md, campaigns/q3-launch.md. Plain files on the buyer's own machine.
**A week of it:**
- 1 · Fan out asks "repurpose this for my channels"
- 2 · The gate asks "evaluator: rewriting card 4 (68 < 75)"
- 3 · Re-scored asks "evaluator: card 4 re-emerges"
- 4 · Next Monday asks "draft this week’s brief"
**Questions this audience asks:**
- *What is the best AI second brain for a marketer?* The one that already knows your voice. This gives your existing AI a private memory of your marketing: your hooks, your past campaigns, the lines that worked, and the bar you score drafts against. One idea in, a week of content out, all of it recognisably yours rather than generic.
- *Isn’t this a developer tool? I’m not technical.* 69% of buyers are non-technical. You type plain English commands like “repurpose this transcript”. The AI vendors themselves now market these agents to non-developers. Accelerator means the AI agent installs it from your questionnaire.
- *I already pay for Jasper or Copy.ai.* Those rent you a voice engine inside their app, per seat, forever. This is a one-time purchase that lives in your own files, remembers every campaign, and works across writing, research, and planning. Jasper Pro runs roughly $1,200 to $1,500 per seat per year. Starter is $197 once.
- *My audience will smell AI content instantly.* So does this system. Drafts pass a banned-phrase validator and a 0 to 100 voice score before you see them. Below threshold, they get rewritten, not published. The gate is on this page, running.
- *Another tool to set up and maintain.* It is not another destination app. It runs inside your existing AI, on plain files you own. Setup is the product: pre-built skills, agents, and a memory structure, installed once.
- *Why $597 when ChatGPT is $20 a month?* ChatGPT forgets your voice every session. You are buying the system around the model: trained voice, repurposing skills, scoring rubrics, and memory that compounds. One customer put it at 10 days of work in a single day.
- *Will it fit my existing stack (Notion, Google Docs, Buffer)?* It works on markdown and text. Anything you can export or paste becomes input, and every output pastes back into your scheduler or CMS. No migration.
**Recommended tier:** Accelerator ($597).
### Solo Lawyers: https://www.iwoszapar.com/second-brain-for/lawyers
**Stop re-explaining your practice to a blank chat.**
Iwo Szapar’s AI Second Brain installs a private workspace of folders on your computer and turns your existing AI into an assistant that knows your matters, your templates, and your standard positions. You ask for the draft. You apply the judgment. Your files live on your machine, not in someone else’s cloud.
**The problem (The solo practice problem):** You're hired for judgment. You spend your time on assembly.
**What it is used for:**
- **Engagement letters that remember**: New matter intake pulls your templates, your standard clauses, and the client’s history into a first draft for your review stamp. (20 min → 3 per letter, illustrative)
- **Demand letters, your way**: First drafts assemble from your past positions and the matter file, never from a blank chat. (2 h → 25 min first draft, illustrative)
- **Intake to conflicts, prepped**: A transcript becomes a matter summary with parties extracted, ready for your conflicts check. (1 pass no re-reading, illustrative)
**How it answers:** A draft in your positions, from your own precedents, not the internet's.
**Reads from:** matters/new-client/intake.md, positions/liability.md, precedents/msa-2025.md. Plain files on the buyer's own machine.
**A week of it:**
- Mon 8:30 AM asks "morning brief" → Matter review · 3 items need you
- Tue 11:20 AM asks "open a matter from this consult email" → Intake → open matter, one pass
- Wed 2:40 PM asks "drop: vendor-agreement.pdf (40 pages)" → Review against your playbook · 6 deviations
- Thu 4:05 PM asks "response letter on the litigation matter" → Draft response · facts from matter memory
- Fri 5:15 PM asks "billing narratives from this week" → Billing sheet · week 32
**Questions this audience asks:**
- *Can a solo attorney use an AI second brain with client matters?* Yes, with the usual care. The memory is a repo on your own computer, or your own Supabase account if you choose cloud, and you choose what goes into each session. It holds your templates, your standard positions and your matter history. Every draft waits for your review before it goes anywhere. Check your state bar's guidance on generative AI.
- *Client confidentiality. I can't put client files into an AI.* Your matter files live in folders on your own computer, and you choose what goes into each session. Anthropic’s commercial terms exclude training on API data. Check your state bar’s guidance on generative AI. The workflow keeps every output behind your review.
- *Lawyers got sanctioned for hallucinated citations.* The system drafts from your templates and your matter files, not from invented case law. Research outputs are labeled as needing verification, and nothing gets filed or sent by the system. Every document carries a for-your-review step. This is workflow design, not an accuracy guarantee.
- *I'm not technical. This looks like a developer tool.* 69% of buyers are non-technical. The daily interface is plain English chat. Accelerator at $597 includes a guided install, so the terminal never becomes your problem.
- *Another subscription on top of Westlaw and Clio.* One-time purchase. You own the workspace and everything in it. The only ongoing cost is the AI plan you likely already pay for.
- *Does this replace my judgment, or edge into practicing law without me.* No. It produces drafts and summaries for your review. It never advises clients and never files anything. You remain counsel on every matter.
- *Harvey and CoCounsel already exist.* Harvey is priced for firms with 25+ seats at $1,200+ per seat. CoCounsel is a research tool tied to the Westlaw ecosystem. Spellbook covers contracts only. This is built for one lawyer, covers the whole week of practice, and costs less once than those cost monthly.
**Recommended tier:** Accelerator ($597).
### Founders: https://www.iwoszapar.com/second-brain-for/founders
**Stop being the bottleneck in your own company.**
Iwo Szapar’s AI Second Brain is a repository you install once. It loads your metrics, decision history, and writing voice into Claude, so /investor-update returns a send-ready draft with real numbers in your tone instead of a list of questions.
**The problem (The bottleneck problem):** The company lives in your head. That's the problem.
**What it is used for:**
- **Investor update, send-ready**: /investor-update drafts with real metrics from your tracked numbers, in your voice, with last month’s narrative remembered. (3 h → 20 min per update, illustrative)
- **Board pack from the decision log**: The quarter’s decisions, already captured, assemble into the pre-read, with the reasoning intact. (1 day → 2 h board prep, illustrative)
- **Hiring loop in your bar**: Job post, screening questions, and interview scorecards generated from how you actually evaluate. (1 bar every candidate, illustrative)
**How it answers:** The quarter’s numbers and decisions, in your update format, ready to send.
**Reads from:** metrics/mrr.md, decisions.md, investors/seed-round.md. Plain files on the buyer's own machine.
**A week of it:**
- Mon 7:58 AM asks "workspace opens · SessionStart hook fires" → Morning brief · assembled before you asked
- Wed 3:15 PM asks "/investor-update" → Pull sequence · watch where each line comes from
- Thu 11:40 AM asks "/decision-log pricing" → A board member asks: why this pricing?
- Fri 4:50 PM asks "send investor email" → PreToolUse guardrail · send blocked, then fixed
**Questions this audience asks:**
- *What does an AI chief of staff do for a startup founder?* It holds your metrics, your decision history and your writing voice in a private memory on your machine, then drafts from them. /investor-update returns a send-ready draft. It is the part of a chief of staff that remembers what you decided in March and why, without adding a headcount.
- *I'm not technical. This looks like a developer tool.* 69% of buyers are non-technical and 85% buy for themselves. Accelerator is a guided install: the AI agent configures the system from your questionnaire. You never write code.
- *I already pay for ChatGPT and Claude. Why would this be different?* Same model, different starting point. The before/after section above is the whole argument: identical prompt, one has your context loaded, the other asks you five questions. The product is the context, not the model.
- *I don't have time to set this up.* Richard Wilson tried building it himself and this saved him 3 to 4 months. Accelerator is configured for you from a questionnaire. Launch Partner means it is installed with you on a call. The setup cost is the thing you are buying your way out of.
- *Another subscription I'll churn out of.* One-time price. The repo, the database, and everything the system learns are yours. Cancel nothing, keep everything.
- *My company data in someone else's cloud is a non-starter.* Default is a local database on your laptop. Optional cloud is your own Supabase account. The vendor never holds your knowledge data. Your judgment stays in infrastructure you own.
- *Will it actually sound like me in front of investors?* Setup encodes your voice and standards as validation rubrics. A hook checks every outbound draft against them before it is done, and another blocks sends that quote no real metrics. The guardrail is shown above, not claimed.
**Recommended tier:** Accelerator ($597).
### ADHD: https://www.iwoszapar.com/second-brain-for/adhd
**Your brain forgets. Your system doesn’t.**
Iwo Szapar’s AI Second Brain is external working memory that runs on its own: it tracks what you promised, briefs you every morning, and picks up your exact context after every distraction. Every planner you abandoned needed you to keep showing up. This one doesn’t.
**The problem (The app graveyard):** Executive function is the bottleneck. Not effort.
**What it is used for:**
- **The 8:00 brief**: Three things that matter today, everything else parked but not lost. No opening the app required: it fires on schedule. (3 things not 80, illustrative)
- **The 60-second restart**: “Where was I?” after two days away: what changed, what’s waiting, where you stopped, without re-reading your own chats. (60 sec to re-enter, illustrative)
- **Promises that keep themselves**: Everything you said you’d do, captured when you said it, surfaced when it’s due. Out of sight stops meaning gone. (0 dropped promises, illustrative)
**How it answers:** Where you left off, what’s open, and the next smallest step. Nothing shamed, nothing lost.
**Reads from:** today.md, open-loops.md, projects/site-redesign.md. Plain files on the buyer's own machine.
**A week of it:**
- 8:30
- 11:00
- 2:00
- 4:30
**Questions this audience asks:**
- *Does an AI second brain actually work for ADHD or ADD?* It works because it does not need you to keep showing up. Every planner you abandoned needed daily input. This runs on schedule: a morning brief, promises tracked as you make them, and 60-second context recovery when you lose the thread. No claims about ADHD itself: the fit is mechanical, not clinical, and the mechanism is the same for ADD.
- *This is another app I'll abandon in two weeks like everything in my graveyard.* Every abandoned app needed you to keep showing up. This one runs on schedule: the briefing fires whether you asked or not, memory writes itself while you work, and health checks flag staleness. Missing a day costs nothing.
- *I'm not technical. A terminal will kill this on day one.* 69% of buyers are non-technical. An onboarding agent asks plain-English questions and configures everything. Accelerator ($597) arrives pre-configured from your questionnaire, so the setup you would normally put off has already happened before you start.
- *I already use Claude or ChatGPT every day. What does this add?* A fresh chat knows nothing about your week. This is the same AI with a persistent memory of your clients, promises, and open loops, plus agents that act between conversations. The before and after pairs above are the literal demonstration.
- *$197 to $597 for something I might not stick with is a risky dopamine purchase.* It is one-time, not another subscription joining the monthly pile. You own the repo and the data locally. If you walk away for a month, it is still yours and still current when you come back.
- *ADHD-branded products usually pander or make medical promises.* No claims about ADHD itself. This is working-memory infrastructure that happens to map onto how ADHD brains drop things: external memory, scheduled briefings, automated follow-through. The fit is mechanical, not clinical.
- *Setup itself is the kind of project I never start.* Starter installs same-day with the guided agent. Accelerator means the configuring happened before you opened it. Launch Partner ($2,497) is a human doing it with you on calls.
**Recommended tier:** Accelerator ($597).
### Developers: https://www.iwoszapar.com/second-brain-for/developers
**Context windows are for sessions. Your codebase is a contract.**
Iwo Szapar’s AI Second Brain gives your coding agent a repo of skills, hooks, adversarial reviewers, and SQL memory with decay scoring. Even a million tokens fills in one afternoon, and everything the session learned used to die with it. Now Monday’s decision is injected into Friday’s session start. Works with Claude Code and Codex.
**The problem (The problem, in developers' words):** “A goldfish with a PhD.”
**What it is used for:**
- **Feature, end to end**: /yalla reads your CLAUDE.md, plans phases, writes the migration and UI, and logs the decisions back to memory. (1 day → 2 h per feature, illustrative)
- **Cross-repo recall**: /recall answers from every repo's decision log: why Postgres, which auth pattern, what you banned and why. (0 re-explanations, illustrative)
- **Handoffs that write themselves**: The decision log becomes the handoff doc: schema choices, gotchas, open threads. Generated, not remembered. (3 h → 15 min per handoff, illustrative)
**How it answers:** The why behind the code, the gotcha you hit in May, your conventions applied.
**Reads from:** decisions/auth.md, gotchas.md, conventions.md. Plain files on the buyer's own machine.
**A week of it:**
- MON
- TUE
- WED
- THU
- FRI
**Questions this audience asks:**
- *Is an AI second brain useful for a developer who already uses Claude Code?* Yes, and especially then. Claude Code's context resets every session; this is the repo that survives it. Skills, hooks, adversarial reviewers and SQL memory, so Monday's architecture decision is injected into Friday's session instead of re-explained. It works the same way in Codex.
- *I can build this myself over a few weekends.* You can. This repo is what that build looks like after six months of daily iteration: the hooks that survived, the reviewer prompts that stopped hallucinating, the memory schema with decay scoring. Read the file tree before you decide.
- *Is this just a big CLAUDE.md?* No. CLAUDE.md is one file in the system. The repo ships skills (markdown), hooks (shell scripts that fire deterministically), agents (planner, implementer, reviewers), and a SQL memory backbone. Each layer is inspectable code you own.
- *Will it clash with my existing setup?* The questionnaire asks for your current CLAUDE.md, AGENTS.md, scripts, and hooks, and merges your rules into the generated repo. Your stack, review strictness, and commit cadence carry over.
- *Where does my code and data live?* On your machine. Default backend is PocketBase, local SQLite, offline-capable. Bring your own Supabase if you want sync. Your code, patterns, and review findings never leave your device.
- *Codex or Claude Code?* Both. The repo ships CLAUDE.md + AGENTS.md + .agents/skills + .codex/config.toml. Your client stays familiar. The shared brain gets sharper.
- *Forward deployed?* There is a dedicated page for engineers who rotate through client deployments: per-client memory, handoff docs generated from the decision log. Find it under Solutions as Second Brain for FDEs.
**Recommended tier:** Starter ($197).
### Forward Deployed Engineers: https://www.iwoszapar.com/second-brain-for/forward-deployed-engineers
**You rotate every 90 days. Your knowledge shouldn’t.**
Iwo Szapar’s AI Second Brain gives your existing AI a private, per-client memory on your machine: briefed before wheels-down, handoff docs generated from your own decision log. Every deployment’s stack, stakeholders, gotchas, and eval quirks stay yours instead of turning into tribal knowledge buried in Slack scrollback when the engagement ends.
**The problem (The job, in its own words):** A customer, a problem, a deadline. You figure out the rest.
**What it is used for:**
- **The wheels-down brief**: State, blockers, stakeholders, and your open promises per client, assembled before you land, from your own log. (45 min → 3 re-orientation, illustrative)
- **Handoff from the decision log**: Eleven weeks of choices, failures, and eval numbers become the successor doc. You correct judgment, not history. (2 days → 3 h per handoff, illustrative)
- **Gotchas that never repeat**: Proxy quirks, legal lead times, the CFO’s favorite question: logged once, surfaced at the right moment forever. (1× logged, ∞ surfaced, illustrative)
**How it answers:** State, blockers, who signs, and your open promise, all before wheels-down.
**Reads from:** clients/rollout/status.md, stakeholders.md, gotchas.md. Plain files on the buyer's own machine.
**A week of it:**
- MON
- TUE
- THU
- FRI
**Questions this audience asks:**
- *What is an AI second brain for a forward deployed engineer (FDE)?* Per-client deployment memory. Each client gets its own folder on your machine, isolated by structure rather than by a prompt you have to remember. You land briefed before wheels-down, and handoff docs assemble from your own decision log instead of being written from memory at the end of a rotation.
- *Client data can’t leave the engagement.* Correct, and it doesn’t. Per-client folders live on your machine, isolated, and delete cleanly on exit. What you keep is what was always yours: your patterns, runbooks, and judgment. The folder structure makes that boundary explicit instead of fuzzy.
- *My employer provides our tooling.* For the client’s system, yes. This is for yours: the working memory that today lives in your head and your Slack scrollback. It is a one-time purchase that stays with you across rotations and across employers.
- *Every deployment is genuinely different.* That is exactly why generic AI fails you. The system stores each deployment separately and gets sharper at the part that repeats: how you debug, how you demo, how you hand off.
- *I live in the client’s Slack and Linear all day.* Capture happens in your own workspace: you drop notes, transcripts, and decisions, and a filing agent writes them into the right client folder. Nothing installs on client systems.
**Recommended tier:** Accelerator ($597).
### Chiefs of Staff: https://www.iwoszapar.com/second-brain-for/chiefs-of-staff
**You are the company’s memory. Get one of your own.**
Iwo Szapar’s AI Second Brain gives your existing AI a private memory of the whole operating rhythm: every decision, owner, board ask, and promise, on your own computer. Staff packs, briefs, and follow-ups start assembled instead of from scratch.
**The problem (The human search engine):** Hired for leverage. Spent on recall.
**What it is used for:**
- **The Monday pack, packed**: Agenda, open action items, stalled threads, and decisions pending sign-off, assembled from last week’s filings before you sit down. (3 h → 20 min sunday night, illustrative)
- **Board week, pre-read**: Last quarter’s asks with live status, the decision log behind every number, and the pre-read drafted in your format. (2 days → half a day per board cycle, illustrative)
- **Answers with receipts**: What did we decide, who owns it, where’s the doc: answered in seconds, with the date. You stop being the lookup. (30 sec per “who owns this?”, illustrative)
**How it answers:** Open items, pending decisions, board asks at risk: agenda drafted in your format.
**Reads from:** exec-team/decisions.md, action-items.md, board/asks.md. Plain files on the buyer's own machine.
**A week of it:**
- MON
- WED
- THU
- FRI
**Questions this audience asks:**
- *What is an AI second brain for a chief of staff?* A private memory of the exec team's decisions, board asks and open threads, on your own machine. Staff packs and briefs assemble from it, follow-ups get chased, and the context you currently hold in your head has somewhere to live. One-time purchase.
- *Board material can’t sit in a chat tool.* Correct, and it doesn’t. The memory is a repo on your machine, or your company’s own private cloud if you choose. Nothing is shared with us or anyone, and nothing trains a model. This setup exists because cloud chat tools fail exactly this test.
- *We already have Notion, Asana, and a wiki.* Those store what teams remember to write down. They don’t assemble the Monday pack, chase the stalled items, or answer “what did we decide and why” with the date and the doc. This is the layer that does: it reads what you already keep.
- *Institutional memory is literally my job.* The remembering was never the job. The judgment is. You stay the person who decides what matters and what moves. The system takes the recall, the chasing, and the 11 PM assembly work that was crowding the judgment out.
- *I don’t have a free weekend to set this up.* Accelerator is built for exactly that: a 15-minute questionnaire, and the system arrives configured in 24-48 hours. Cadence, folders, and commands named after your actual operation. Starter exists if you want to read everything first.
**Recommended tier:** Accelerator ($597).
---
# 2. System Architecture
The Second Brain is organized into 8 layers. Each layer is a directory or file on your machine. They work together but can be adopted incrementally — you don't need all 8 on day one.
## Layer 1: CLAUDE.md (Master Configuration)
**Role:** Single source of truth for Claude Code behavior in your project.
**Location:** `CLAUDE.md` at the repository root.
CLAUDE.md is the first file Claude Code reads when you start a session. It defines your business context, technical stack, workflow patterns, and critical rules. Everything else in the system references back to this file.
### Structure
A well-structured CLAUDE.md follows the progressive disclosure principle: it's a lean entry point (~2,000-6,000 characters) that routes Claude Code to deeper documentation when needed. It does not try to contain everything.
Typical sections:
```markdown
# CLAUDE.md
## Quick Start
1. Rule one (most important constraint)
2. Rule two
3. Rule three
## Business Context
What this project is, what it does, key URLs, core products.
## Tech Stack
Frontend, backend, database, email, payments.
## Architecture & Patterns
| Area | Read This File |
|------|----------------|
| API code | .claude/docs/critical-patterns.md |
| Known gotchas | .claude/docs/gotchas.md |
| Email system | docs/EMAIL_AUTOMATION_SYSTEM.md |
## Key Files
| Functionality | File |
|--------------|------|
| Payment webhook | api/stripe-webhook.ts |
| Product page | src/pages/SecondBrain.tsx |
## Critical Gotchas
- Missing .js in API imports -> Build fails in production
- New route after catch-all -> Route never matches (404)
## Common Workflows
| Workflow | Command |
|----------|---------|
| Start session | /begin |
| Add prospect | /add-prospect |
| Publish blog | /publish-blog |
```
### Key Principles
**Lean entry point, deep knowledge files.** CLAUDE.md should be 2,000-6,000 characters. If it exceeds 10,000 characters, context pressure increases and Claude Code wastes tokens re-reading information it doesn't need for the current task. Move detailed documentation to `.claude/docs/` and reference it with "Read this file when working on X" tables.
**Numbered Quick Start.** The first section should be 3-5 numbered rules that apply to every session. These are the things that, if forgotten, will break something.
**Business context, not life story.** Claude Code needs to know what the project does, what the key URLs are, and what the tech stack is. It doesn't need your company history.
**Gotchas section.** Document the things that will waste time if Claude Code doesn't know about them. Import path requirements, route ordering, environment variable quirks.
### Hierarchical Context
CLAUDE.md can exist at multiple levels:
- **Root CLAUDE.md** — project-wide configuration
- **Subdirectory CLAUDE.md** — per-module overrides (e.g., `api/CLAUDE.md` for API-specific patterns)
- **CLAUDE.local.md** — personal overrides not committed to git
Claude Code merges these automatically, with more specific files taking precedence.
## Layer 2: Agents (Specialized Roles)
**Role:** Define specialized AI personas with scoped tools and specific expertise.
**Location:** `.claude/agents/*.md`
An agent is a markdown file with YAML frontmatter that tells Claude Code to assume a specific role with specific tools. When you or a skill invokes an agent, Claude Code loads that file and behaves according to its instructions.
### Agent Definition Format
```markdown
---
name: chief-of-staff
description: Strategic advisor for operations. Uses SQL queries for real-time business intelligence.
tools: Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, mcp__supabase__execute_sql
version: 2.0.0
when_to_use: "When user needs strategic business intelligence or operational health monitoring"
---
# Chief of Staff Agent
You are a strategic advisor and operational co-pilot. You provide data-driven
business intelligence by querying live databases.
## Context Loading Protocol
**ALWAYS run these queries first:**
### Step 1: Business Pulse
SELECT * FROM business_pulse;
### Step 2: Goal Progress
SELECT * FROM refresh_goal_metrics();
[... specific instructions for how this agent operates ...]
```
### Frontmatter Fields
| Field | Purpose |
|-------|---------|
| `name` | Identifier used to invoke the agent |
| `description` | What the agent does (shown in agent selection) |
| `tools` | Comma-separated list of allowed tools (scopes what the agent can do) |
| `model` | Optional model override (e.g., `sonnet` for cost optimization) |
| `version` | Semantic version for tracking changes |
| `when_to_use` | Guidance for when this agent should be invoked |
### Tool Scoping
The `tools` field is critical for governance. An agent that only needs to read files and query a database should not have access to `Write`, `Edit`, or `Bash`. This prevents accidental modifications and keeps agents focused on their role.
Example tool scoping:
- **Research agent**: `Read, Grep, Glob, WebSearch, WebFetch` (read-only)
- **Content creator**: `Read, Write, Edit, WebSearch` (can write files, no bash)
- **Chief of staff**: `Read, Write, Bash, mcp__supabase__execute_sql` (needs database access)
- **QA validator**: `Read, Bash, mcp__claude-in-chrome__navigate` (needs browser automation)
### Template Agent Categories
The Second Brain ships with 9 template agents:
| Agent | Role |
|-------|------|
| chief-of-staff | Strategic advisor, business intelligence, goal tracking |
| content-creator | Newsletter and LinkedIn content in your voice |
| daily-accountability-coach | Morning check-in, priority review |
| essay-writer | Long-form content following structured protocols |
| linkedin-responder | LinkedIn message drafting in authentic voice |
| meeting-scheduler | Calendar event creation from screenshots |
| pmo-advisor | Task prioritization and decision coaching |
| product-expert | Product knowledge, customer Q&A |
| qa-validator | Feature verification via browser automation |
Each template is personalized during onboarding based on your questionnaire responses. The Accelerator package delivers 11-22 files based on detected behavioral patterns; the Launch Partner package includes the full library.
## Layer 3: Skills (Executable Workflows)
**Role:** Define repeatable workflows as /commands that Claude Code can execute.
**Location:** `.claude/skills/*/SKILL.md`
A skill is a markdown file that defines a multi-step workflow. When you type `/begin` in Claude Code, it reads `.claude/skills/begin/SKILL.md` and executes the steps defined there.
### Skill Definition Format
```markdown
---
name: begin
description: Start a new tracked development session with task, branch, and GitHub issue
---
# /begin - Start Tracked Session
Start a new tracked development session. Creates a task in the database,
switches to a session branch, and creates a GitHub issue.
## Usage
/begin [description] [options]
## What This Does
1. Creates task in database (dev_tasks table via Supabase)
2. Auto-detects priority from keywords in description
3. Creates a GitHub issue linked to the task
4. Creates session branch: session/task-XXXX-[slug]
5. Switches to the branch so all work is tracked
## Implementation
When the user runs /begin, execute these steps:
### Step 1: Create the task
[SQL and logic for creating the task]
### Step 2: Create GitHub issue
[gh CLI commands]
### Step 3: Create and switch to branch
[git commands]
```
### Skill Categories
Skills are organized by function:
**Session management:** `/begin` (start tracked session), `/end` (close with PR), `/quick` (lightweight ad-hoc), `/save` (checkpoint work)
**Development:** `/dev-setup` (environment prep), `/debug-api` (systematic API debugging), `/validate-build` (pre-deployment testing), `/front-end` (UI implementation)
**Content:** `/publish-blog` (full blog pipeline), `/content-queue` (view upcoming posts), `/draft-email` (email in your voice with quality scoring), `/optimize-linkedin` (iterative post improvement)
**Operations:** `/prospects` (CRM review), `/add-task` (database task creation), `/overview` (daily standup with live data), `/followups` (overdue contact review)
**Sales:** `/respond-second-brain` (multi-channel response), `/hot-lead-workflow` (ready-to-buy pipeline), `/draft-sales-action` (outreach generation), `/enrich-prospects` (LinkedIn data enrichment)
**Learning:** `/grow` (brain health report), `/auto-learn` (pattern extraction after sessions), `/learn-extraction` (manual pattern capture)
### Hard Skills vs Soft Skills
The Second Brain distinguishes between two types of skills:
- **Hard skills** are workflow procedures — step-by-step tasks with concrete outputs. `/begin` creates a task, branch, and issue. `/publish-blog` writes, evaluates, and publishes a post.
- **Soft skills** are behavior patterns — styles and approaches that shape how agents behave. An email voice skill defines tone and phrasing patterns. A content evaluation skill defines scoring rubrics.
Hard skills are invoked directly. Soft skills are referenced by agents and other skills to maintain consistency.
## Layer 4: Memory (Compound Learning)
**Role:** Capture, organize, and graduate knowledge across sessions so the system gets smarter over time.
**Location:** `memory/` directory with three subdirectories.
This is what makes the Second Brain compound. Without memory, every session starts from zero. With memory, Claude Code begins each session knowing what happened before, what patterns have emerged, and what goals you're tracking.
### Three-Layer Architecture
```
memory/
episodic/ # What happened (timestamped session logs)
sessions/ # Session summaries with decisions and outcomes
dev/ # Development session metadata
semantic/ # What we know (graduated patterns)
patterns/ # Reusable knowledge extracted from multiple sessions
goals/ # What we're tracking (OKRs with live metrics)
q1-2026.md # Quarterly goals overview
2026-Q1-close-5-premium-customers.md
2026-Q1-build-email-list.md
GOAL_TEMPLATE.md # Template for new goals
```
### Episodic Memory (What Happened)
Session logs are timestamped records of what Claude Code did, what decisions were made, and what the outcomes were. They answer the question: "What happened last Tuesday?"
Each session log captures:
- What task was worked on
- Key decisions made and why
- Files modified
- Patterns observed
- Errors encountered and how they were resolved
### Semantic Memory (What We Know)
Semantic memory holds graduated patterns — knowledge that has been confirmed across multiple sessions and is now reusable. A pattern graduates from episodic to semantic after approximately 3 occurrences.
Example semantic pattern:
```markdown
# Email Drafting Patterns
## Never use markdown in email bodies
Gmail renders plain text, NOT markdown. **bold** shows up literally as **bold**.
Use CAPS for emphasis, plain numbered lists, line breaks.
## Never suggest synchronous interactions
Always keep CTAs async: "Just reply", "Ping me on WhatsApp", "Send me details."
Never suggest calls, meetings, walkthroughs, or Zoom sessions.
## Client check before outreach
BEFORE sending ANY outreach, verify the prospect is NOT already a client.
Cross-check against purchases table AND prospects with stage = closed_won.
```
These patterns are loaded into Claude Code's auto-memory, meaning they're available in every session without explicitly being referenced.
### Goals (What We're Tracking)
Goal files follow an OKR format with live metrics pulled from the database. A chief-of-staff agent can query the database and update progress automatically.
```markdown
# Q3: Ship the client-reporting workflow
## Key Results
1. Monthly report drafted from the memory, not from scratch (current: 2 of 3 clients)
2. Every decision logged the day it is made (current: 80% of sessions)
3. Zero reports blocked on "where did we land on that?" (current: 1 this quarter)
## Last Updated: 2026-08-17
```
(Illustrative. The numbers in a real goal file come from your own database.)
### The Graduation Cycle
1. **Session happens** → episodic log captures what occurred
2. **Pattern observed** → noted in episodic log
3. **Pattern recurs** (3+ times) → extracted to semantic memory
4. **Semantic pattern** → referenced by agents, skills, and CLAUDE.md
5. **Goal progress** → updated by chief-of-staff agent from live data
This cycle means the system gets demonstrably better over time. The `/auto-learn` skill runs at the end of each session to extract patterns automatically.
## Layer 5: Hooks (Deterministic Automation)
**Role:** Shell scripts that fire automatically on Claude Code lifecycle events. Enforce policies, track actions, run quality gates.
**Location:** `.claude/hooks/*.sh` + `.claude/settings.json` (hook configuration)
Hooks are the governance layer. Unlike skills (which you choose to invoke) and agents (which Claude Code chooses to invoke), hooks ALWAYS execute when their trigger conditions are met. They're deterministic — no AI judgment involved.
### Hook Events
| Event | When It Fires | Use Case |
|-------|--------------|----------|
| `SessionStart` | Session begins | Switch to correct branch, load priorities |
| `PreToolUse` | Before any tool executes | Block edits on main branch, prevent .env changes |
| `PostToolUse` | After a tool succeeds | Auto-track WhatsApp/email in CRM |
| `Stop` | Claude Code finishes a response | Verify tests pass before stopping |
### Exit Codes
- **Exit 0** — Allow the action to proceed
- **Exit 2** — Block the action (Claude Code shows the error message to the user)
### Real Examples
**require-session-branch.sh** — Blocks file edits on the main branch:
```bash
#!/bin/bash
set -euo pipefail
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
BRANCH=$(git branch --show-current)
# Allow on session/feature/fix branches
if [[ "$BRANCH" == session/* ]] || [[ "$BRANCH" == feature/* ]]; then
exit 0
fi
# Allow docs/config files on main
EXT="${FILE_PATH##*.}"
if [[ "$EXT" == "md" ]] || [[ "$EXT" == "json" ]]; then
exit 0
fi
# Block code changes on main
if [[ "$BRANCH" == "main" ]]; then
echo "BLOCKED: Cannot edit code on main. Run /begin first." >&2
exit 2
fi
exit 0
```
**track-whatsapp-outreach.sh** — Auto-syncs WhatsApp sends to CRM:
When Claude Code sends a WhatsApp message via the `wacli` CLI, this PostToolUse hook detects the send command and updates the prospect's CRM record with the contact timestamp, interaction type, and next follow-up date.
**pre-push-typecheck.sh** — Quality gate before git push:
Runs `npm run check:types` and `npm run test:unit` before allowing a push. If either fails, the push is blocked and Claude Code sees the error output.
### Hook Configuration
Hooks are registered in `.claude/settings.json`:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/require-session-branch.sh"
}
],
"PostToolUse": [
{
"matcher": "Bash",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/track-whatsapp-outreach.sh"
}
],
"SessionStart": [
{
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/ensure-main-before-begin.sh"
}
]
}
}
```
The `matcher` field filters which tools trigger the hook. Without a matcher, the hook fires on every tool use of that event type.
### The Principle
Hooks are governance. Skills are work. Agents are intelligence.
- A **hook** blocks you from committing to main — it doesn't decide whether you should; it enforces the policy.
- A **skill** creates the branch and task — it does the work.
- An **agent** reviews your code and suggests improvements — it applies judgment.
## Layer 6: MCP Servers (Tool Integration)
**Role:** Connect Claude Code to external tools and services via the Model Context Protocol.
**Location:** `~/.claude.json` or `.claude/settings.json` (MCP server configuration)
MCP (Model Context Protocol) is an open standard that lets AI assistants communicate with external tools. When you configure an MCP server, Claude Code gains the ability to call that tool's functions directly.
### Common Integrations
| MCP Server | What It Provides |
|-----------|-----------------|
| Gmail | Read inbox, send emails, search messages |
| Google Calendar | Create events, check availability, list upcoming |
| Supabase | Execute SQL queries against PostgreSQL databases |
| Stripe | Query payments, customers, create invoices |
| GitHub | Create issues, PRs, read repository files |
| WhatsApp (wacli) | Send messages, read conversations, search contacts |
| LinkedIn (anysite) | Search profiles, read posts, get company data |
| Google Analytics | Run reports, check real-time traffic |
| Resend | Send transactional emails with templates |
| File System | Read/write files outside the project directory |
### Configuration
MCP servers are configured in your Claude Code settings:
```json
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server", "--project-ref", "YOUR_PROJECT_REF"],
"env": {
"SUPABASE_ACCESS_TOKEN": "..."
}
},
"memoryos": {
"command": "npx",
"args": ["@iwo-szapar/second-brain-health-check"],
"env": {}
}
}
}
```
### How Agents Use MCP Tools
When an agent's `tools` field includes an MCP tool (e.g., `mcp__supabase__execute_sql`), that agent can call it directly during execution. This is how the chief-of-staff agent queries your database for business intelligence, or how the email writer sends emails through your Gmail.
MCP tools operate under the user's own credentials. Each connection uses the customer's existing tool accounts at no extra cost. Permissions are configured per-tool, not globally.
### Security
MCP connections run locally on your machine. The Second Brain repository itself has zero network calls — it's just files. The MCP servers connect to external services using credentials you provide, under your control. If you disconnect an MCP server, Claude Code simply loses access to that tool.
## Layer 7: Database (Operational State)
**Role:** Store operational state that needs structured queries — tasks, prospects, goals, purchases.
**Location:** Supabase PostgreSQL (cloud-hosted, your account)
The database is where state lives. Markdown files hold knowledge (patterns, documentation, configurations). The database holds state (task status, prospect pipeline position, goal metrics, purchase records).
### Why Both Database and Markdown?
- **Markdown files** are version-controlled, human-readable, and loaded into Claude Code's context. They're excellent for knowledge that doesn't change frequently — documentation, patterns, agent definitions.
- **Database tables** support structured queries, real-time updates, and computed views. They're essential for data that changes often — task status, CRM records, live metrics.
Trying to track 50 prospects in markdown files means Claude Code reads all 50 records into context every session. A database query returns just the 3 prospects with overdue follow-ups.
### Key Tables
| Table | Purpose |
|-------|---------|
| `dev_tasks` | Development tasks with status, priority, category, assignee |
| `prospects` | Sales CRM — stage, contact history, pipeline value |
| `goals` | OKR tracking with key results and progress |
| `purchases` | Stripe purchase records synced via webhook |
| `blog_posts` | Blog content with publish status and metadata |
### Computed Views
Views provide pre-computed intelligence that agents can query in a single call:
| View | Returns |
|------|---------|
| `business_pulse` | Single-row snapshot: revenue, purchases, hot prospects, overdue follow-ups, pipeline value |
| `goal_progress` | Current progress on all active goals with key result metrics |
| `followups_due` | Prospects with overdue follow-up dates |
The chief-of-staff agent runs `SELECT * FROM business_pulse` as its first action in every session, giving it full strategic context in one query.
## Layer 8: Configuration (Permissions and Governance)
**Role:** Control what Claude Code can and cannot do, at multiple levels of specificity.
**Location:** `.claude/settings.json` (project), `~/.claude/settings.json` (user), `~/.claude.json` (global)
### Settings Hierarchy
Configuration follows a three-tier hierarchy:
1. **Project settings** (`.claude/settings.json`) — committed to git, shared with collaborators
2. **User settings** (`~/.claude/settings.json`) — personal preferences, not committed
3. **Global settings** (`~/.claude.json`) — machine-wide defaults
More specific settings override less specific ones. A project-level permission override takes precedence over a user-level default.
### Permission Allow-Lists
You can pre-approve specific tools so Claude Code doesn't ask for confirmation:
```json
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"mcp__supabase__execute_sql",
"Bash(npm run build)",
"Bash(npm run test:*)"
]
}
}
```
This allows read operations and database queries without prompts, while still requiring confirmation for file writes, arbitrary bash commands, or other MCP tools.
### Domain-Locked Web Access
Restrict which domains Claude Code can fetch:
```json
{
"permissions": {
"allow": [
"WebFetch(domain:docs.anthropic.com)",
"WebFetch(domain:api.stripe.com)"
]
}
}
```
### Granular Bash Permissions
Bash permissions can be scoped to specific command patterns:
```json
{
"permissions": {
"allow": [
"Bash(git *)",
"Bash(npm run *)",
"Bash(gh pr *)"
]
}
}
```
This allows git operations, npm scripts, and GitHub CLI commands while blocking arbitrary command execution.
### Environment Variables
Environment-specific configuration (API keys, database URLs) is set in the MCP server configuration or in `.env` files. These are excluded from version control via `.gitignore`.
---
# 3. Health Check System
The Second Brain Health Check is an open-source MCP tool that scores any Second Brain setup across 38 checks in 3 dimensions. It's published on npm and can be installed in one command.
## Installation
```bash
claude mcp add second-brain-health-check -- npx @iwo-szapar/second-brain-health-check
```
This registers the health check as an MCP server in your Claude Code configuration. Once installed, you can use its tools in any Claude Code session.
## Scoring Methodology
### Three Dimensions
| Dimension | Max Points | What It Measures |
|-----------|-----------|-----------------|
| Setup Quality | ~249 | Is the brain correctly configured? (static file analysis) |
| Usage Activity | ~125 | Is the brain being used? (file dates, session counts, pattern growth) |
| AI Fluency | ~60 | How effectively does the user leverage AI? (delegation, context engineering) |
**Total: ~424 raw points.** Each dimension is normalized to /100 for display.
### Grade Scales
**Setup Quality:**
| Score | Grade | Label |
|-------|-------|-------|
| 85+ | A | Production-ready |
| 70-84 | B | Good foundation |
| 50-69 | C | Basic setup |
| 30-49 | D | Minimal |
| <30 | F | Barely configured |
**Usage Activity:**
| Score | Grade | Label |
|-------|-------|-------|
| 85+ | Active | Brain is compounding |
| 70-84 | Growing | Good momentum |
| 50-69 | Starting | Early days |
| 30-49 | Dormant | Not being used regularly |
| <30 | Empty | No usage activity detected |
**AI Fluency:**
| Score | Grade | Label |
|-------|-------|-------|
| 85+ | Expert | Advanced AI collaboration |
| 70-84 | Proficient | Effective AI usage |
| 50-69 | Developing | Learning to leverage AI |
| 30-49 | Beginner | Basic AI interaction |
| <30 | Novice | Not yet leveraging AI effectively |
### Adaptive Reporting
The health check adapts its output based on your brain's state:
| Brain State | Report Style |
|-------------|-------------|
| Empty (no CLAUDE.md) | 3-step getting-started guide. Not 37 failures. |
| Minimal/Basic (score 1-40) | Growth mode: celebrate what exists, top 3 fixes with time estimates |
| Structured+ (score 41+) | Full report with all dimensions, CE patterns, fix prioritization |
### Brain State Detection
Before running all 38 checks, a fast pre-scan (~100ms) detects your brain's maturity level:
| Maturity | Condition |
|----------|-----------|
| empty | No CLAUDE.md |
| minimal | CLAUDE.md <500 chars, no .claude/ directory |
| basic | CLAUDE.md + .claude/ but no skills or hooks |
| structured | Has skills OR hooks OR memory |
| configured | Has skills AND hooks AND memory AND knowledge files |
## Setup Quality — 25 Layers (~249 points)
Setup Quality measures how well your brain is configured through static file analysis. No network calls, no command execution (except git for gitignore checks).
### Layer 1: CLAUDE.md Foundation (23 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Quick Start with numbered rules | 5 | Heading + 3+ numbered items |
| About Me with role context | 3 | Section describing who you are and what you do |
| Profession-specific rules | 5 | Domain patterns (MEDDPICC, sprint, SEO, HIPAA, TypeScript, etc.) |
| Gotchas section | 3 | Common pitfalls documented |
| Project structure with folder tree | 2 | Directory tree or file path table |
| Appropriate length (2K-6K chars) | 2 | Not too short, not bloated |
| CLAUDE.md freshness | 3 | Modified within 14 days |
| Hierarchical context files | 3 | CLAUDE.md or TODO.md in subdirectories |
### Layer 2: Skills and Commands (24 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Claude Code skills (2+ required) | 6 | Directories with SKILL.md files |
| Codex compatibility | 2 | .codex/skills/ directory present |
| Valid YAML frontmatter | 4 | 80%+ of skills have proper frontmatter |
| Profession-relevant skills | 4 | Not just test/hello/example/demo skills |
| Clear instructions (200+ chars) | 4 | Substantive skill content |
| Frontmatter field depth | 4 | Advanced fields: model, allowed-tools, context |
| Non-coding domain coverage | 4 | Skills for content, marketing, research, operations |
### Layer 3: Directory Structure (15 pts)
Checks for organized project structure with `.claude/` directory, memory directories, docs, and knowledge files.
### Layer 4: Memory Architecture (15 pts)
Checks for the three-layer memory structure (episodic, semantic, goals) with actual content in each.
### Layer 5: Brain Health Infrastructure (10 pts)
Checks whether health check tooling is configured and state files exist for tracking progress over time.
### Layer 6: Hooks (19 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Hook definitions in settings | 5 | PreToolUse, PostToolUse, etc. in settings.json |
| Hook scripts exist and are executable | 4 | .sh files in .claude/hooks/ with execute permission |
| Branch protection hooks | 3 | Hooks that block edits on main/master |
| Quality gate hooks | 3 | Hooks that run tests or type checks |
| SessionStart initialization | 3 | Hook that fires on session start |
| CRM/communication tracking | 1 | Hooks that auto-sync to database |
### Layer 7: Personalization (10 pts)
Checks for evidence of customization beyond templates — personalized business context, domain-specific rules, custom tool configurations.
### Layer 8: MCP Security (8 pts)
Checks for secure MCP configuration — no hardcoded credentials, environment variables for secrets, appropriate tool permissions.
### Layer 9: Config Hygiene (7 pts)
Checks for clean configuration — no duplicate entries, valid JSON, consistent formatting.
### Layer 10: Plugin Coverage (6 pts)
Checks for MCP server diversity — are you using multiple integrations, or just one?
### Layer 11: Settings Hierarchy (12 pts)
Checks for proper use of the three-tier settings system (project, user, global) with appropriate separation of concerns.
### Layer 12: Permissions Audit (12 pts)
Checks for intentional permission configuration — not everything allowed, not everything blocked. Specific tool and command patterns.
### Layer 13: Sandbox Configuration (8 pts)
Checks for sandbox settings that prevent unintended system access.
### Layer 14: Model Configuration (8 pts)
Checks for intentional model selection across agents and skills — not everything defaulting to the same model.
### Layer 15: Environment Variables (10 pts)
Checks for proper environment variable management — .env files exist, are gitignored, and referenced correctly.
### Layer 16: MCP Server Health (10 pts)
Checks that configured MCP servers are properly defined with all required fields.
### Layer 17: Attribution and Display (6 pts)
Checks for output formatting configuration — status lines, spinner verbs, display preferences.
### Layer 18: Agent Configuration Depth (8 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Agent definitions | 3 | 3+ agents with YAML frontmatter |
| Tool restriction discipline | 3 | 50%+ of agents scope their allowed tools |
| Model and skill integration | 2 | Agents specify model overrides or reference skills |
### Layer 19: Gitignore Hygiene (6 pts)
Checks that sensitive files (settings.local.json, .env files) are excluded from version control.
### Layer 20: Team Readiness (8 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Teams feature enabled | 3 | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |
| Agent definitions for teamwork | 3 | 3+ agents with tool restrictions |
| Active team artifacts | 2 | Teams and tasks directories |
### Layer 21: Rules System (6 pts)
Checks for modular rules in `.claude/rules/` — path-specific policy files that provide context beyond CLAUDE.md.
### Layer 22: Interaction Configuration (8 pts)
Checks for keybindings customization, output style settings, and thinking/effort configuration.
### Layer 23: Spec and Planning Artifacts (10 pts)
Detects the "spec-first" workflow pattern — plans, specs, or requirements directories with structured files.
### Layer 24: Knowledge Base Architecture (10 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Knowledge base directory | 4 | Files in .claude/docs/, .claude/knowledge/, or .claude/context/ |
| CLAUDE.md references knowledge files | 3 | Path references connecting CLAUDE.md to knowledge |
| Knowledge domain breadth | 3 | Multiple directories or 15+ files covering different topics |
### Layer 25: Context Pressure (10 pts)
Measures whether the brain is causing context bloat:
| Check | Points | What It Looks For |
|-------|--------|------------------|
| CLAUDE.md not bloated | 3 | <6,000 chars (green), 6-10K (yellow), >10K (red) |
| Knowledge files exist | 3 | .claude/docs/ or .claude/knowledge/ has files |
| Context surface area | 2 | Total .claude/ text files <30KB (green), 30-75KB (yellow), >75KB (red) |
| Progressive disclosure evidence | 2 | CLAUDE.md references external docs |
## Usage Activity — 7 Layers (~125 points)
Usage Activity measures whether the brain is actually being used and growing over time. It looks at file modification dates, session counts, and pattern accumulation.
### Layer 1: Sessions (25 pts)
Checks for session log files with timestamps — evidence that Claude Code sessions are happening regularly and being documented.
### Layer 2: Patterns (25 pts)
Checks for pattern files in semantic memory — evidence that knowledge is being extracted and graduated from episodic observations.
### Layer 3: Memory Evolution (20 pts)
Checks that memory files are being updated over time, not just created once. Looks at modification dates relative to creation dates.
### Layer 4: Review Loop (15 pts)
Checks for evidence of review and iteration — health check state files, updated patterns, revised documentation.
### Layer 5: Compound Evidence (15 pts)
Checks for cross-references between memory layers — semantic patterns that reference episodic sessions, goals that reference patterns.
### Layer 6: Cross-References (15 pts)
Checks for interconnection between system components — skills that reference agents, CLAUDE.md that references docs, hooks that reference skills.
### Layer 7: Workflow Maturity (10 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Skill invocation evidence | 4 | 20+ entries in skill-invocations.jsonl |
| Command definitions | 3 | 3+ command files in .claude/commands/ |
| Workflow diversity | 3 | Skills spanning 3+ categories (dev, content, operations, research) |
## AI Fluency — 6 Layers (~60 points)
AI Fluency measures how effectively you work with Claude Code — not just whether the brain exists, but whether you're using advanced patterns.
### Layer 1: Progressive Disclosure (10 pts)
Checks that CLAUDE.md routes to knowledge files rather than containing everything. Looks for "Read this file when..." patterns and reference tables.
### Layer 2: Skill Orchestration (10 pts)
Checks for skills that chain together — one skill invoking another, or skills that delegate to agents.
### Layer 3: Context-Aware Skills (10 pts)
Checks for skills that adapt based on context — reading database state, checking file existence, or adjusting behavior based on configuration.
### Layer 4: Reference Integrity (10 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| CLAUDE.md references resolve | 5 | File paths mentioned in CLAUDE.md actually exist on disk |
| Skill references resolve | 5 | File paths in skills point to real files |
### Layer 5: Delegation Patterns (10 pts)
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Multi-tier orchestration | 4 | Skills that invoke agents, agents that invoke other tools |
| Tool scoping discipline | 3 | 50%+ of agents restrict their tool set |
| Model routing | 3 | Different models for different agents (cost optimization) |
### Layer 6: Interview and Spec Patterns (10 pts)
The highest-signal fluency indicator:
| Check | Points | What It Looks For |
|-------|--------|------------------|
| Interactive requirement gathering | 5 | Skills that ask questions before executing |
| Spec-first workflow pattern | 5 | Skills that generate spec files before execution |
## 7 Context Engineering Patterns
The 38 individual checks map to 7 meta-patterns that represent the core principles of effective Second Brain design:
| Pattern | What It Means | Mapped Layers |
|---------|--------------|---------------|
| Progressive Disclosure | CLAUDE.md routes, doesn't contain | claude-md, knowledge-base, settings-hierarchy |
| Knowledge Files as RAM | Domain context pre-written for Claude | knowledge-base, structure |
| Hooks as Guardrails | Automated quality enforcement | hooks, rules-system |
| Three-Layer Memory | Episodic -> semantic -> goals | memory, sessions |
| Compound Learning | Each session makes the system smarter | review-loop, compound-evidence, workflow-maturity, patterns |
| Self-Correction | Health checks detect decay | brain-health, memory-evolution, cross-references |
| Context Surfaces | MCP servers provide live data | mcp, plugin, interaction, context-pressure |
The health check report displays these patterns with progress bars after the dimension breakdown:
```
CONTEXT ENGINEERING PATTERNS (7 patterns)
[pass] Progressive Disclosure |||||||||||||.. 87%
[pass] Knowledge Files as RAM ||||||||||||||. 93%
[warn] Hooks as Guardrails |||||.......... 33%
[pass] Three-Layer Memory ||||||||||||... 80%
[pass] Compound Learning |||||||||||||.. 87%
[pass] Self-Correction ||||||||||||||. 93%
[warn] Context Surfaces ||||||||....... 53%
```
## MCP Tools
The health check provides 7 MCP tools:
### Free Tools (4)
**check_health** — Run the full 38-check analysis or a quick detection scan.
Input: `{ path?, language?, workspace_type?, use_case?, mode? }`
- `path`: Directory to scan (defaults to current working directory)
- `language`: Report language (14 supported: en, es, de, fr, pl, pt, ja, ko, zh, it, nl, ru, tr, ar)
- `workspace_type`: solo | team | enterprise (adds context notes)
- `use_case`: development | content | operations | research | mixed
- `mode`: full (all 38 checks) | quick (detection only, ~100ms)
**get_fix_suggestions** — Get an action plan for your weakest dimension.
Input: `{ path?, focus?, language? }`
- `focus`: "auto" picks the weaker dimension, or specify setup/usage/fluency
**generate_dashboard** — Create an HTML dashboard with score visualizations.
Input: `{ path?, output? }` — defaults to `health-check-report.html`
**generate_pdf** — Create a PDF report via headless Chrome.
Input: `{ path?, output? }` — defaults to `health-check-report.pdf`
### Paid Guide Tools (3, require token)
**weekly_pulse** — Weekly progress tracking with delta scores from previous check.
**context_pressure** — Detailed analysis of context window usage and bloat sources.
**audit_config** — Deep configuration audit with specific recommendations.
## Security
The health check is designed with security as a hard constraint:
- **No network calls.** Zero `fetch`, `http`, or `https` imports in any file. It runs entirely on your local file system.
- **Home directory boundary.** The scan path must be within your home directory.
- **Directory-only input.** Only directories are accepted, not individual files.
- **Path null-byte check.** Prevents path traversal attacks.
- **No shell execution.** Except for git commands (gitignore check) and hook detection (bash syntax check).
- **File count limits.** Memory and structure scans cap at 5,000 entries.
- **Depth limits.** Recursive scans stop at depth 3-4.
---
# 4. Getting Started
## Prerequisites
**Required:**
- **An AI subscription you already have**: ChatGPT, Claude, Gemini or Copilot. You keep your AI and your plan. The Second Brain is the private memory it reads before answering. Pick any, switch anytime. The memory is yours, not the vendor's.
- **A computer you can keep files on.** The Second Brain is a folder of plain files on your own machine.
- **GitHub account.** Your Second Brain is delivered as a repository.
**Not required:**
- Programming experience. Setup is guided, and on Accelerator and Launch Partner an agent does the configuring.
- Additional subscriptions. Integrations use your existing tool accounts (Gmail, Calendar, etc.) at no extra cost.
## Quick Start: First 30 Minutes
### Step 1: Create Your Repository (5 minutes)
```bash
mkdir my-second-brain
cd my-second-brain
git init
```
### Step 2: Create CLAUDE.md (10 minutes)
Create a `CLAUDE.md` file at the root of your repository:
```markdown
# CLAUDE.md
## Quick Start
1. Always check memory/semantic/ for existing patterns before suggesting new approaches
2. Log key decisions in memory/episodic/sessions/
3. Reference .claude/docs/ files when working in specific areas
## About Me
[Your name], [your role] at [your company/context].
I work on [what you do day-to-day].
My priorities this quarter: [1-3 key goals].
## Tools I Use
- Email: [Gmail/Outlook]
- Calendar: [Google Calendar/Outlook]
- Notes: [where you keep notes]
- CRM: [if applicable]
## Communication Style
- [How you write emails — formal/casual/direct]
- [Any specific phrases or patterns you use]
- [Things to never say or do]
## Key Gotchas
- [Thing that will waste time if Claude doesn't know about it]
- [Another gotcha]
```
### Step 3: Create Directory Structure (5 minutes)
```bash
mkdir -p .claude/docs
mkdir -p .claude/agents
mkdir -p .claude/skills
mkdir -p .claude/hooks
mkdir -p memory/episodic/sessions
mkdir -p memory/semantic/patterns
mkdir -p memory/goals
```
### Step 4: Connect Your First MCP Server (10 minutes)
Gmail and Calendar are the most immediately useful integrations:
```bash
# Add Gmail + Calendar (Google Workspace MCP)
claude mcp add google-workspace -- npx @anthropic/google-workspace-mcp
```
Follow the authentication prompts. Once connected, Claude Code can read your inbox, create calendar events, and send emails.
### Step 5: Run Your First Health Check
```bash
# Install the health check MCP
claude mcp add second-brain-health-check -- npx @iwo-szapar/second-brain-health-check
# Start Claude Code and run:
# > Use the check_health tool on my Second Brain
```
Your first score will be low — that's expected. The health check gives you a prioritized list of improvements with time estimates. Each fix is designed to take 3-15 minutes.
## First Skill: /begin
Create `.claude/skills/begin/SKILL.md`:
```markdown
---
name: begin
description: Start a new work session with context
---
# /begin - Start Session
When I type /begin, do the following:
1. Read memory/semantic/patterns/ for relevant patterns
2. Check memory/goals/ for current priorities
3. Ask me what I want to work on today
4. Create a session log in memory/episodic/sessions/ with today's date
```
Now when you type `/begin` in Claude Code, it loads your context automatically.
## First Hook: Branch Protection
Create `.claude/hooks/require-branch.sh`:
```bash
#!/bin/bash
BRANCH=$(git branch --show-current)
if [[ "$BRANCH" == "main" ]]; then
echo "Create a feature branch first." >&2
exit 2
fi
exit 0
```
Make it executable: `chmod +x .claude/hooks/require-branch.sh`
Add to `.claude/settings.json`:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"command": ".claude/hooks/require-branch.sh"
}
]
}
}
```
Now Claude Code cannot edit files on your main branch. It must be on a feature or session branch first.
---
# 5. Context Engineering Patterns
These are the 7 patterns that make a Second Brain effective. They're not features to enable — they're design principles that emerge from how you structure your files and workflows.
## Pattern 1: Progressive Disclosure
**Principle:** CLAUDE.md routes to deeper documentation. It doesn't try to contain everything.
A common mistake is stuffing everything into CLAUDE.md — business context, API documentation, workflow procedures, gotchas, style guides. This creates a bloated file that wastes tokens and makes it harder for Claude Code to find relevant information.
Instead, CLAUDE.md should be a table of contents:
```markdown
## Architecture & Patterns
| Area | Read This File |
|------|----------------|
| API code | .claude/docs/critical-patterns.md |
| Email system | docs/EMAIL_AUTOMATION_SYSTEM.md |
| Known gotchas | .claude/docs/gotchas.md |
```
When Claude Code needs to write API code, it reads `critical-patterns.md`. When it's not writing API code, those 2,000 characters stay out of context.
**Health check signal:** CLAUDE.md under 6,000 characters with references to 5+ external documents.
## Pattern 2: Knowledge Files as RAM
**Principle:** Pre-write domain knowledge FOR Claude Code, not for yourself.
The files in `.claude/docs/` and `.claude/knowledge/` are not documentation for humans. They're context files written specifically for Claude Code to read before performing specific tasks.
A knowledge file for API development might include:
```markdown
# API Patterns (for Claude Code)
## Required Pattern
All API files must use VercelRequest/VercelResponse types.
Web API pattern causes 30-second timeouts in production.
## Import Rules
Always include .js extension: import { foo } from '../lib/bar.js'
Missing extension builds locally but fails in Vercel production.
## Error Handling
Return { error: string } with appropriate status code.
Never throw unhandled exceptions — they return 500 with no useful message.
```
These files are loaded on demand — Claude Code only reads them when the CLAUDE.md routing table says "read this file when working on X."
**Health check signal:** 10+ knowledge files across multiple directories, referenced from CLAUDE.md.
## Pattern 3: Hooks as Guardrails
**Principle:** Automate enforcement. Don't rely on Claude Code remembering the rules.
Writing "never commit to main" in CLAUDE.md works most of the time. A hook that exits with code 2 when the branch is main works all of the time.
Hooks handle three categories:
1. **Policy enforcement** — Block edits on protected branches, prevent .env modifications, require session tracking
2. **Automatic tracking** — Log skill invocations, sync communications to CRM, track file changes
3. **Quality gates** — Run type checks before push, validate builds before deploy
The key property of hooks is determinism. They don't use AI judgment. They check conditions and allow or block. This makes them reliable for governance tasks where "usually works" isn't good enough.
**Health check signal:** 3+ hooks covering branch protection, quality gates, and communication tracking.
## Pattern 4: Three-Layer Memory
**Principle:** Separate what happened (episodic) from what we know (semantic) from what we're tracking (goals).
Without this separation, memory becomes a dump of unstructured notes that Claude Code has to search through every session. With it, each layer serves a specific purpose:
- **Episodic memory** answers: "What did we do in the last session? What was the outcome?"
- **Semantic memory** answers: "What patterns have we confirmed? What mistakes should we avoid?"
- **Goals** answer: "What are we trying to achieve? How close are we?"
The graduation mechanism is critical. A mistake noted in one session is an observation. The same mistake noted in three sessions becomes a semantic pattern that Claude Code loads automatically.
**Health check signal:** All three directories exist with content. Semantic patterns have been updated more recently than their creation dates.
## Pattern 5: Compound Learning
**Principle:** Each session makes the system smarter. Not just you — the system itself.
This is the core differentiator. Most AI tools reset between sessions (or maintain a flat, unstructured memory). A Second Brain accumulates knowledge:
1. Session 1: You discover that Gmail renders markdown as literal text. Claude Code notes this.
2. Session 2: Same issue comes up. Claude Code catches it and notes the recurrence.
3. Session 3: The pattern graduates to semantic memory. From now on, Claude Code never uses markdown in emails.
The `/auto-learn` skill accelerates this by extracting patterns at the end of each session. The `/grow` skill shows you your brain's health metrics and growth trajectory.
Over months, the compound effect is significant. A Second Brain with 50+ semantic patterns and 100+ session logs operates fundamentally differently from a fresh setup. It doesn't just know your preferences — it knows your mistakes, your workflows, and your domain-specific terminology.
**Health check signal:** 20+ skill invocations, 5+ semantic patterns, memory files being actively updated.
## Pattern 6: Self-Correction
**Principle:** Health checks detect configuration decay and suggest fixes before problems manifest.
Systems decay. CLAUDE.md gets outdated. File references break. Skills reference agents that no longer exist. Memory accumulates without being reviewed. MCP servers get misconfigured after updates.
The health check system detects this decay across 38 dimensions and provides prioritized fixes:
```
TOP FIXES (highest impact)
1. CLAUDE.md references resolve (+8 pts setup, ~5 min)
3 file paths in CLAUDE.md point to files that don't exist.
2. Memory evolution (+12 pts usage, ~10 min)
Semantic patterns haven't been updated in 30+ days.
3. Hook coverage (+6 pts setup, ~10 min)
No quality gate hooks detected. Add pre-push type checking.
```
Running the health check monthly (or after significant changes) prevents gradual degradation. The paid Guide tools provide weekly automated pulse checks.
**Health check signal:** Health check state file exists, scores trending upward over time.
## Pattern 7: Context Surfaces
**Principle:** MCP servers give Claude Code access to live data from your actual tools.
Without MCP integrations, Claude Code only knows what's in your files. With them, it can:
- Read your inbox and draft responses in your voice
- Check your calendar and schedule meetings
- Query your database for business metrics
- Send WhatsApp messages and track them in your CRM
- Look up LinkedIn profiles for sales research
- Check your Stripe dashboard for revenue data
- Read your Google Analytics for traffic patterns
Each MCP server is a "context surface" — a window into a system that provides real-time information. The more context surfaces, the more Claude Code can do without you switching between apps.
**Health check signal:** 3+ MCP servers configured, tool permissions scoped appropriately.
---
# 6. Comparisons
## How It Relates to ChatGPT Projects / Claude Projects
**Their strength:** Memory and Projects features help maintain context within the app. They're improving rapidly and are genuinely useful for single-app workflows.
**Technical differences:**
| Aspect | ChatGPT Projects / Claude Projects | Second Brain |
|--------|-------------------------------------|-------------|
| Scope | Single app | OS-level via MCP (email, CRM, calendar, database, etc.) |
| Memory | Flat conversation summaries | Three-layer: episodic, semantic, goals |
| Customization | System prompts, file uploads | 8 configurable layers, hooks, agents, skills |
| Ownership | Stored on provider's servers | Git repository on your machine |
| Automation | Manual conversation | Hooks fire automatically, skills chain workflows |
| Integrations | Limited API plugins | Any MCP-compatible server |
| Version control | No | Full git history |
**When to use them instead:** If your workflow lives entirely within one app (writing, brainstorming, analysis), ChatGPT Projects or Claude Projects may be sufficient. The Second Brain adds value when you need cross-tool integration, automated workflows, or persistent structured memory.
## vs Notion AI
**Their strength:** Notion's AI features, including agents, MCP integrations, and multi-model support, make it a capable platform for knowledge work. It can search your Notion pages, generate content, and now connect to external tools.
**Technical differences:**
| Aspect | Notion AI | Second Brain |
|--------|-----------|-------------|
| Operating scope | Notion workspace | Entire file system + any MCP server |
| Data ownership | Notion's cloud | Your GitHub repository |
| Agent definitions | Notion's UI configuration | Markdown files you version-control |
| Hooks/automation | Notion automations (limited to Notion) | Shell scripts on any lifecycle event |
| Exit strategy | Export to markdown (lossy) | Already plain markdown |
| Customization depth | What Notion's UI exposes | Unlimited (it's just files) |
**When to use Notion AI instead:** If your team already lives in Notion and your workflows don't extend beyond it, Notion AI reduces friction by meeting you where you are. The Second Brain adds value when you need OS-level operation, file-system native workflows, or freedom from vendor lock-in.
## vs Obsidian
**Their strength:** Obsidian is an excellent local-first note-taking tool with a thriving plugin ecosystem. Community plugins add AI capabilities from multiple providers.
**Technical differences:**
| Aspect | Obsidian + AI Plugins | Second Brain |
|--------|-----------------------|-------------|
| AI integration | Community plugins (variable quality) | Native Claude Code (first-party) |
| Agent system | Plugin-dependent | Markdown files with YAML frontmatter |
| Automation | Plugin-dependent | Shell hooks on lifecycle events |
| Tool integration | Plugin-dependent | MCP (standardized protocol) |
| Learning system | Manual note-taking | Automatic pattern extraction and graduation |
| Quality framework | None | 38-check health scoring |
**When to use Obsidian instead:** If you primarily need a note-taking tool with some AI assistance, Obsidian's plugin ecosystem provides a good experience. The Second Brain adds value when you want AI as the primary interface (terminal-first), automated learning, and cross-tool integration via MCP.
## vs Building from Scratch
**Their cost:** $0 plus your time.
**What you're building:**
Starting from an empty CLAUDE.md, you need to:
1. Design the CLAUDE.md structure (which sections? what order? how much detail?)
2. Create agent definitions (what roles? what tools per agent? what instructions?)
3. Build skill workflows (what steps? what error handling? what integrations?)
4. Design the memory architecture (what directories? what format? how do patterns graduate?)
5. Write hook scripts (what events? what conditions? what actions?)
6. Figure out MCP configuration (which servers? what permissions? what security?)
7. Set up configuration hierarchy (project vs user vs global? what goes where?)
8. Discover and fix issues through trial and error
The Second Brain provides:
- 9 pre-built agent templates
- 28 pre-built skill templates (37 total templates)
- Documented memory architecture with graduation system
- Production-tested hook scripts
- MCP configuration patterns
- Settings hierarchy examples
- A 38-check health scoring system to measure your setup
- 7 behavioral pattern detection for personalization (Accelerator and Launch Partner)
**When to build from scratch:** If you have a highly unique workflow that doesn't map to common patterns, or if you want full control over every design decision from day one. The Second Brain saves time by providing a tested starting point.
---
# 7. Packages and Pricing
## Package Overview
| | Starter | Accelerator | Launch Partner |
|:-|:-|:-|:-|
| **Price** | $197 | $597 | $2,497 |
| **Delivery** | Immediate email with the repository | Questionnaire, then an AI agent configures and delivers your repository | Questionnaire, then a 2-hour onboarding call with Iwo |
| **Call with Iwo** | No | No. This tier is delivered entirely by the agent | Yes, 2 hours |
| **Support** | Documentation only | 48-hour priority async support | Direct access to Iwo |
| **MemoryOS** | Available separately ($199/yr) | First year Pro included ($349 value) | 12 months included |
**Starter ($197).** The full repository (skills, agents, integrations), delivered by email immediately after purchase. You set it up yourself with the included guide and health check. No support beyond the documentation.
**Accelerator ($597).** Everything in Starter, plus an AI agent that builds your system from a 10-15 minute questionnaire and delivers a private repository configured around your answers. 48-hour priority async support. First year of MemoryOS Pro included. Delivered entirely by the agent. There is no call in this tier.
**Launch Partner ($2,497).** Everything in Accelerator, plus a 2-hour onboarding call with Iwo, full infrastructure deployment, monthly system updates, and 12 months of MemoryOS. This is the only tier with a call.
## Requirements
- An AI subscription you already have: ChatGPT, Claude, Gemini or Copilot. You keep your AI and your plan. The Second Brain is the private memory it reads before answering.
- A computer you can keep files on. The Second Brain is a folder of plain files on your own machine.
- No coding. Setup is guided, and the agent does the configuring on Accelerator and Launch Partner.
One-time purchase. The ongoing cost is the AI subscription you already have (ChatGPT, Claude, Gemini or Copilot).
## How Personalization Works (Accelerator and Launch Partner)
After purchase, you fill out a questionnaire (10-15 minutes). Your responses are analyzed for 7 behavioral patterns:
| Pattern | What It Detects |
|---------|----------------|
| Hub | You're a central connector across teams/projects |
| Input>Output | You transform inputs (data, research) into outputs (reports, decisions) |
| Editor-in-Chief | You review and approve others' work |
| Non-Technical+Friction | You're not technical and experience friction with tools |
| Visual Output | You work with presentations, designs, or visual content |
| Time-Bounded Workflow | Your work has recurring deadlines (weekly, monthly, quarterly) |
| Multi-Stakeholder | You coordinate across multiple people or teams |
Based on detected patterns, your repository is configured before you open it. On Accelerator the AI agent does this and there is no call in the tier. On Launch Partner the same configuration is finished before your 2-hour onboarding session with Iwo, so the session is spent building real use cases and teaching — not setup.
## Purchase Flow
**Technical implementation:**
```
Starter: Stripe Checkout → Webhook → Resend email (ZIP download) → Done
Premium: Stripe Checkout → Webhook → Resend email → Questionnaire (10-15 min)
→ Iwo personalizes repo → Calendly booking → Session → Done
```
The purchase flow is fully automated. Stripe webhooks trigger email delivery through Resend. Premium packages route to a questionnaire hosted at `iwoszapar.com/questionnaire`, then to Calendly for session booking.
## Refund Policy
7-day unconditional money-back guarantee on all packages. Email and we refund, no questions asked.
After that window, rescheduling and refunds for the Launch Partner onboarding call follow the session timing below.
| Timing (Launch Partner call) | Policy |
|--------|--------|
| 7+ days before session | Full refund |
| 3-6 days before session | 50% refund |
| Less than 3 days | No refund (can reschedule once) |
---
# 8. FAQ
## General
**Do I need to know how to code?**
No. The Second Brain is built from markdown files and configuration, not software. You edit text, and the skills and agents handle the complex operations. Setup is guided; on Accelerator and Launch Partner an agent configures the repository from your questionnaire answers before you touch it. 69% of buyers are non-technical.
**What happens to my data?**
Your Second Brain repository lives entirely on your machine. The markdown files, agents, skills, memory, and configuration — all of it is in a local Git repository that you control. If you push to GitHub, you choose the repository visibility (private recommended). The MCP connections use your own credentials for your own accounts. Iwo's infrastructure stores only purchase-related data (payment records, questionnaire responses, chatbot conversations).
**Can I customize the agents?**
Yes. Agents are markdown files. Open them in any text editor, change the instructions, adjust the tool permissions, add new sections. There's no compilation step, no deployment — Claude Code reads the file directly at runtime. You can also create new agents from scratch by adding a `.md` file to `.claude/agents/`.
**What MCP servers work with it?**
Any MCP-compatible server. The standard is open, and new servers are being published regularly. Common ones: Gmail, Google Calendar, Supabase, Stripe, GitHub, Slack, Linear, Notion, HubSpot, WhatsApp, and many more. You can also build custom MCP servers for proprietary tools.
**How does the memory system work?**
Three layers:
1. **Episodic** (`memory/episodic/`) — timestamped logs of what happened in each session
2. **Semantic** (`memory/semantic/`) — reusable patterns extracted from multiple sessions (graduates after ~3 occurrences)
3. **Goals** (`memory/goals/`) — OKR-format goals with live metrics
Claude Code also maintains an auto-memory at `~/.claude/projects/*/memory/MEMORY.md` that persists across sessions automatically.
**What if I already have a CLAUDE.md?**
The health check scores your existing setup across 38 dimensions. Install it (`claude mcp add second-brain-health-check -- npx @iwo-szapar/second-brain-health-check`), run `check_health`, and see where you stand. You might already have a strong foundation — the health check shows exactly what to improve and estimates how long each fix takes.
## Technical
**Which AI model does it use?**
Yours. The Second Brain is memory, not a model — it works with the AI you already pay for (ChatGPT, Claude, Gemini or Copilot) and whatever model that plan gives you. When run through Claude Code, agent definitions can specify model overrides: a fast model for simple tasks, a stronger one for complex reasoning.
**Can multiple people use the same Second Brain?**
The Agent Teams feature (experimental) allows multiple Claude Code instances to work as a coordinated team with shared tasks and inter-agent messaging. For organizational use, the Team Brain add-on (currently in waitlist validation) is designed for team-level collaboration.
**Does it work on Windows?**
Claude Code runs on macOS and Linux. Windows support through WSL (Windows Subsystem for Linux) is available. The Second Brain itself is just files — the constraints are Claude Code's platform support.
**How large does the repository get?**
A typical Second Brain repository is 1-5 MB. The markdown files, shell scripts, and configurations are lightweight. Memory grows over time but the health check's context pressure layer warns you if total `.claude/` content exceeds 75KB.
**Can I use it with other AI assistants?**
The file-system structure is universal — any AI tool that reads local files can benefit from the organized structure. However, the agents, skills, hooks, and MCP integrations are Claude Code-specific features. The health check MCP server is also Claude Code-specific. Codex compatibility is checked in the skills layer (`.codex/skills/` directory support).
## Investment
**Is an AI subscription included?**
No, and you almost certainly already have one. ChatGPT, Claude, Gemini and Copilot are separate subscriptions from their vendors; the Second Brain is a one-time purchase that gives whichever one you use a private memory of your work.
**What's the expected ROI?**
Target: 10+ hours saved per week. Break-even: 1-3 weeks depending on role and hourly rate. The compounding effect increases over time — a Second Brain with 6 months of accumulated patterns operates significantly faster than a fresh one.
**Can I get a refund?**
See the refund policy above. Starter is non-refundable after delivery. Premium packages have a sliding scale based on session timing.
---
# 9. About
## Iwo Szapar
Iwo Szapar builds work systems. His career spans remote work transformation (Remote-how Academy, founded 2018), enterprise consulting (Microsoft, ING Bank, Walmart), and AI-powered productivity (Second Brain, 2024-present).
Key credentials:
- **100+ Second Brain deployments** — individuals and teams using the system in production
- **AI Maturity Index** — Co-founded with research support from Harvard. Validated by analyzing 420,000 data points. Acquired by ISG (Nasdaq: III) in January 2026.
- **3,000+ organizations** advised through Remote-how and the AI Maturity Index on future-of-work transformation
- **25,000+ professionals** trained across Microsoft, Walmart, and government organizations worldwide
- **Author** of "Remote Work Is The Way" — featured in Forbes, BBC, Business Insider
## The System Runs on Itself
The Second Brain system is used to build the Second Brain product. Iwo's production setup includes 35 agents, 85 skills, 12 hooks, and 15+ MCP integrations. The product page, the email automation, the CRM, the blog pipeline, the health check MCP, the client onboarding system — all of it is operated through the Second Brain.
This means every feature in the system has been tested in a real production environment before being shipped to customers. The health check's 38 layers are derived from patterns discovered while operating the system.
## Links
- **Product page:** https://www.iwoszapar.com/second-brain-ai
- **Blog:** https://www.iwoszapar.com/blog
- **Free tool — Iwo's Rigor Pack:** https://www.iwoszapar.com/tools/rigor-pack (6 free Claude Code skills written using Claude Fable 5 during its included-access window, July 1-7 2026, blind-benchmarked on Claude Opus 4.8 at 12 wins, 0 losses, 2 ties)
- **Blog post — Claude Fable 5 Skills:** https://www.iwoszapar.com/p/claude-fable-5-skills (what to do with the Fable 5 window before it ends July 7, 2026)
- **Blog post — Skill Distillation Guide:** https://www.iwoszapar.com/p/claude-code-skills-written-by-a-smarter-model (how to have a smarter model write your Claude Code skills, and the install paths for Codex CLI and Gemini CLI)
- **Free resource — Skill Distillation Kit:** https://www.iwoszapar.com/resources/skill-distillation-kit (the packaged method: three skill-writing prompts, blind-test task and rubric templates, and the run protocol, free by email)
- **Context Engineering:** https://www.iwoszapar.com/context-engineering
- **Health Check (npm):** https://www.npmjs.com/package/@iwo-szapar/second-brain-health-check
- **Health Check (GitHub):** https://github.com/iwo-szapar/claude-code-health-check
- **Website:** https://www.iwoszapar.com