Brain Setup

Optional (brain works without these, but degrades)

If anything is missing:

For REQUIRED tools — show what's missing and ask:

Missing required dependencies: [list]
Install them now? [Y/n]

If yes, detect the package manager and install:

# macOS
brew install git jq

# Ubuntu/Debian
sudo apt-get install -y git jq

# Arch
sudo pacman -S git jq

# Windows (winget)
winget install Git.Git jqlang.jq

# Windows (choco)
choco install git jq

Detect package manager priority: brew → apt-get → pacman → winget → choco → manual instructions.

After installing, re-verify. If still missing after install attempt, stop and tell the user to install manually.

For OPTIONAL tools — show a summary and actively offer to install each missing one:

Optional tools:
  ✅ python3  — found
  ⬜ yq       — not found  → Install now for better YAML parsing? [Y/n]
  ⬜ obsidian — not found  → Install now for 70,000x faster vault search? [Y/n]

Ask about each missing optional tool individually. If the user says yes (or just presses Enter — default is Y), install it.

Install yq:

# macOS
brew install yq

# Ubuntu/Debian
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq

# Arch
sudo pacman -S go-yq

# Windows (winget)
winget install MikeFarah.yq

Install Obsidian:

If yes, install by platform:

macOS — no Homebrew cask; use direct download:

echo "Download Obsidian from: https://obsidian.md/download"
echo "Or direct DMG: https://github.com/obsidianmd/obsidian-releases/releases/latest"
open "https://obsidian.md/download"

Windows — winget (recommended):

winget install Obsidian.Obsidian --accept-package-agreements --accept-source-agreements

Linux — AppImage (official) or Flatpak:

# AppImage (recommended)
OBSIDIAN_VERSION="1.12.7"
wget "https://github.com/obsidianmd/obsidian-releases/releases/download/v${OBSIDIAN_VERSION}/Obsidian-${OBSIDIAN_VERSION}.AppImage" -O ~/Obsidian.AppImage
chmod +x ~/Obsidian.AppImage
~/Obsidian.AppImage &

# OR Flatpak
flatpak install flathub md.obsidian.Obsidian

# OR Snap (community-maintained)
sudo snap install obsidian --classic

Linux AppImage sandbox fix (if you get a SUID sandbox error):

sudo chown root:root /tmp/.mount_obsidi*/chrome-sandbox 2>/dev/null
sudo chmod 4755 /tmp/.mount_obsidi*/chrome-sandbox 2>/dev/null

After triggering the Obsidian install, STOP and wait. Display:

⏸ Obsidian needs a few manual steps before setup can continue.

  1. Finish installing Obsidian from the download above
  2. Open Obsidian and create or open a vault
  3. Go to Settings → General → Advanced → find "Command Line Interface"
  4. Toggle it ON → click "Register CLI"
  5. Open a NEW terminal session
  6. Run: obsidian version  ← confirm this works

  Note: Obsidian must stay running in the background for CLI commands to work.

Type "done" when you've completed these steps, or "skip" to continue without Obsidian CLI.

Do not proceed until the user types "done" or "skip".

• If "done": re-run obsidian version to verify. If it works, show ✅ and continue. If it still fails, show the error and ask them to check the steps again.
• If "skip": note that Obsidian CLI is disabled and continue with raw file reads.

Step 0b: Check for Existing Brain

Check if .brain/ already exists in the current working directory.

If .brain/ exists — auto-detect what's missing and do it silently:

1. Check hub wiring: Does ~/Brain/.brain/ exist? Is there a ## Global Brain section in this project's CLAUDE.md? Is ~/Brain/CLAUDE.md referenced in ~/.claude/CLAUDE.md?

   • If any of these are missing → proceed directly to Hub+Spokes wiring (Step 3h) without asking
   • Show what you're doing: "Detected existing brain — wiring Hub+Spokes..."

2. Check for missing files: Are any of the standard Memory, Rules, or Template files absent?

   • If yes → create missing files only, skip existing ones

3. Check for outdated CLAUDE.md: Does the project CLAUDE.md lack an Obsidian CLI section or Global Brain reference?

   • If yes → append the missing sections

4. Enrich the knowledge graph (Step 3j): Always run the graph seeding step on re-run, even if the brain already exists. The seeder is idempotent — it skips existing notes and only creates missing ones. On re-run it should:

   • Re-scan the project for new entities, tools, data sources, or concepts that appeared since last setup (new dependencies in package.json, new files, new git history)
   • Check for unfilled wikilink stubs in the hub vault (notes referenced via [[link]] but empty or non-existent) and fill them
   • Verify link density — if any existing note has fewer than 3 outgoing wikilinks, add more cross-links
   • Report what was added vs what was already present

Do NOT ask the user if they want to update or abort. Just fix what's missing and report what was done. Show a concise summary: "✅ Updated — added [list of what changed]"

If .brain/ does not exist: Proceed with fresh setup below.

Step 1: Context Intelligence (Run silently, no output)

Before asking the user anything, scan for existing context clues. Collect everything you can infer:

Scan these sources silently:

• README.md or README → infer project domain, tech stack, purpose
• CLAUDE.md → read owner name, role, any existing rules
• .git/config + git log --oneline -10 → infer domain from commit messages
• package.json / pyproject.toml / Cargo.toml → infer tech stack and role
• Existing folders at root → infer work type (src/, docs/, clients/, content/)
• Any .md files at root → scan for personal context

Build a confidence score:

• Found name → +20pts
• Found role/domain → +25pts
• Found tech stack or work type → +20pts
• Found existing notes or personal files → +15pts
• Directory name is descriptive (not "tmp", "test") → +10pts
• git history with 5+ commits → +10pts

If total ≥ 60pts → go to Step 2A (auto-infer mode) If total < 60pts → go to Step 2B (interview mode)

Step 2A: Auto-Infer Mode (high context)

Silently infer the full profile without asking anything. Then show the preview:

I found enough context to build your vault. Here's what I inferred:

👤 Owner:    [name or "you"]
💼 Role:     [inferred role]
🎯 Domain:   [inferred domain/stack]
📦 Scope:    [work only / work + personal]

Here's your vault:

📁 [current directory name]/
├── Human/
│   ├── Daily/          Daily notes and quick captures
│   ├── Projects/       [role-specific: e.g. "client work" or "features"]
│   └── Archive/        Completed items — never deleted
├── Machine/
│   ├── Memory/         AI-managed: entities, decisions, corrections
│   ├── Rules/          Self-updating behavioral rules
│   ├── Session-Logs/   Session continuity logs
│   └── Templates/      Note templates
└── .brain/             Brain engine metadata + hooks

Slash commands you'll have:
  /brain-today    — morning startup, loads all context
  /brain-new      — brain-dump anything, routes it automatically
  /brain-tldr     — summarize and save any session
  /brain-debrief  — end-of-day ritual

Type "build it" to create this, or tell me what to change.

Wait for confirmation before building anything.

Step 2B: Interview Mode (low context)

Display this exactly, then wait:

Tell me about yourself in a few sentences so I can build your vault.

Answer these in whatever order feels natural:
- What do you do for work?
- What falls through the cracks most — what do you wish you tracked better?
- Work only, or personal life too?
- Do you have existing files to import? (PDFs, docs, slides)

No need to be formal. A few sentences is enough.

After they respond, infer silently (do NOT ask follow-up questions) and show the same vault preview as Step 2A, but personalized to what they described.

Role → folder mapping:

• Business owner → Human/Projects/ + Human/People/ + Human/Decisions/
• Developer → Human/Projects/ + Human/Research/
• Consultant → Human/Clients/ + Human/Research/
• Creator → Human/Content/ + Human/Research/
• Student → Human/Notes/ + Human/Research/
• If personal scope → also add Human/Personal/

Step 2C: Sub-Agent Profile Mode (optional, advanced)

If the user says something like "figure it out yourself", "you already know me", or "check the context":

Spawn a focused sub-agent with this prompt:

You are a vault profiler. Your job is to infer a user profile for an AI Brain vault setup.

Read the following sources in this directory: README.md, CLAUDE.md, any .md files, package.json, git log.
Then answer these questions with your best inference:
1. Owner name (or "unknown")
2. Role (business owner / developer / consultant / creator / student / other)
3. Primary domain or stack
4. Scope: work-only or work+personal
5. Top 2 pain points (what falls through the cracks)
6. Any existing files to import? (yes/no, what types)

Return a JSON object with these fields. Confidence 0-100 for each field.

Use the sub-agent's JSON output to populate the vault preview. Present it to the user as: "Here's what I figured out from context..."

Step 2D: Architecture Choice

After the vault preview (Step 2A or 2B), and before the user confirms, show this:

One more thing — how do you want to structure your brain?

1. Hub + Spokes ← default, press Enter to accept
   ~/Brain/ holds your identity, global rules, and cross-project memory.
   Each project gets its own .brain/ for local context.
   Both are always in context — you get the best of both worlds.

2. Per-Project only
   Each project is isolated. No shared memory between projects.
   Good if projects are completely unrelated.

3. Centralized only
   Everything in one vault. One CLAUDE.md, one memory, one graph.
   Good if you want a single Obsidian vault for everything.

If the user just presses Enter or says nothing, use Hub+Spokes.

Store the choice as ARCH_MODE = hub-spokes | per-project | centralized.

If hub+spokes:

• Also ask: "Where should the hub live?" (default: ~/Brain)
• Check if ~/Brain/.brain/ already exists
  • If yes: "Hub found at ~/Brain — will register this project in it"
  • If no: "Will create a new hub at ~/Brain after this project is set up"
• Store hub path as HUB_PATH

Step 3: Build After Confirmation

Once the user says "build it", "yes", "go", "looks good", or similar — proceed.

3a. Create Directory Structure

Create all directories (skip any that already exist):

Human/Daily/
Human/Projects/     (or role-specific folders from Step 2)
Human/Archive/
Machine/Session-Logs/
Machine/Memory/
Machine/Rules/
Machine/Templates/
Machine/Canvases/
.brain/hooks/
.brain/agent-configs/

If personal scope: also create Human/Personal/

3b. Create Memory Files

Create in Machine/Memory/ (skip if exists):

entities.md — People, Projects, Tools, Preferences sections decisions.md — Decisions log with rationale corrections.md — AI behavior corrections log context-cache.md — Active context, current focus, quick reference

3c. Create Rules

Machine/Rules/active-rules.md with 7 default rules:

1. Startup: read this file + context-cache + latest session log before work
2. Human/ protection: read freely, write ONLY when explicitly asked
3. Machine/ access: read and write freely
4. Formatting: use [[wikilinks]] + YAML frontmatter (if Obsidian mode)
5. Memory: log entities, decisions, corrections to Machine/Memory/
6. Session end: write session log to Machine/Session-Logs/ before ending
7. Self-improve: when corrected, log it and propose a rule update

3d. Create Templates

Create in Machine/Templates/:

• daily.md — frontmatter + Priorities + Tasks + Notes + Carryover sections
• project.md — frontmatter + Overview + Goals + Tasks + Decisions + Notes
• session-log.md — frontmatter + Summary + Decisions + Files Modified + Next Steps + Corrections

3e. Write Brain State

.brain/state.json:

{
  "brain_version": "1.0.0",
  "installed_at": "[ISO timestamp]",
  "last_session": null,
  "sessions_count": 0,
  "obsidian_cli": false
}

.brain/brain.yaml — write full config with inferred profile values.

3f. Detect Obsidian CLI

Run: obsidian version 2>/dev/null

If it returns output: set obsidian_cli: true in brain.yaml and state.json. Tell the user "Obsidian CLI detected — enhanced vault integration enabled."

If not found: note in summary that CLI is optional and how to enable it.

3g. Generate Agent Configs

Generate CLAUDE.md at vault root. Include:

• Owner name and role (from inferred/provided profile)
• Vault structure map with purpose of each directory
• Startup protocol (read rules → context-cache → last session log → today's note)
• Obsidian CLI command table (if CLI detected)
• Directory permissions (Human=read-only, Machine=read-write)
• Formatting conventions
• Memory, session end, and self-improvement protocols

Ask which other agents to configure (Cursor, Gemini CLI, Codex) — or skip this question if they already told you in Step 2.

3h. Hub+Spokes Wiring (if ARCH_MODE = hub-spokes)

Step A — Register this project in the hub:

Append to {HUB_PATH}/Machine/Memory/projects.md (create if missing):

- [[{project-name}]] — path: {absolute project path} | domain: {inferred domain} | added: {today}

Step B — Add hub reference to this project's CLAUDE.md:

Append this section to the project's CLAUDE.md:

## Global Brain
At startup, also read `{HUB_PATH}/CLAUDE.md` for:
- Who I am (identity, role, global preferences)
- Global rules that apply to all projects
- Cross-project entities (people, tools, recurring clients)
- Long-term decisions and career context

Step C — If hub doesn't exist yet, scaffold it:

Run /the-ai-brain:brain-setup in {HUB_PATH} in hub mode:

• Same vault structure (Human/ + Machine/)
• CLAUDE.md focused on identity, not project specifics
• Machine/Memory/projects.md — registry of all known projects
• No project-specific rules (those stay per-project)
• Scope: personal OS (work + life if user wants)

Step D — Wire ~/.claude/CLAUDE.md to the hub:

Append to ~/.claude/CLAUDE.md (create if missing):

## My Brain Hub
At the start of every session, read {HUB_PATH}/CLAUDE.md for global context:
who I am, cross-project memory, and universal rules.

This fires in every Claude Code session on this machine — even outside any project.

Step E — Update hub's active-rules.md to include project awareness:

Append to {HUB_PATH}/Machine/Rules/active-rules.md:

{N+1}. **Projects**: Known projects are in Machine/Memory/projects.md. When a project is mentioned, offer to read its .brain/ for full context.

3i. Install Hooks (Claude Code)

Create in .brain/hooks/:

• session-start.sh — reads state + session logs + context-cache + active-rules + today's note → outputs userPromptPrefix JSON
• post-session.sh — outputs userPromptSuffix reminder to write session log, updates state.json
• post-edit-check.sh — detects changes to active-rules.md, suggests /brain-vault-align

Make all scripts executable: chmod +x .brain/hooks/*.sh

Create/merge .claude/settings.json with hook configuration.

3j. Seed the Knowledge Graph

After the vault structure and hooks are in place, seed the hub vault with MOC hub notes and entity notes so the Obsidian graph view is immediately rich and navigable. This step runs on the hub vault (not the project vault).

Only runs if ARCH_MODE = hub-spokes and a hub vault exists.

What seeding creates:

1. MOC (Map of Content) hub notes — these become the high-degree backbone nodes in graph view. Create one MOC per domain the user works in, inferred from Step 1 context scanning.

   Format for each MOC:

   ---
   tags: [type/MOC, domain/{domain}]
   created: {today}
   ---
   # MOC — {Domain Name}
   
   {One-line description connecting to [[owner-name]]'s work.}
   
   ## Projects
   - [[{project-name}]] — {brief description}
   
   ## Tools & Platforms
   - [[{tool}]] — {role in this domain}
   
   ## Concepts
   - [[{concept}]] — {brief description}
   

   Typical MOCs to consider (create only those relevant to the user):

   • MOC — Trading (if financial/trading domain)
   • MOC — AI Tooling (if AI/ML/agent work)
   • MOC — Web Development (if web stack)
   • MOC — Projects (always create — indexes all projects)
   • MOC — DevOps (if infrastructure work)

2. Entity hub notes — one note per recurring tool, platform, data source, or concept that appears across multiple projects or contexts. These become bridge nodes connecting different graph clusters.

   Format for each entity:

   ---
   tags: [type/{tool|language|data-source|concept|platform}, domain/{domain}]
   created: {today}
   ---
   # {Entity Name}
   
   {One-line description.}
   
   ## How [[{owner}]] Uses It
   - {Usage in project 1}
   - {Usage in project 2}
   
   ## Related
   - [[{MOC}]]
   - [[{related-entity}]]
   

   Entity discovery sources:

   • Tech stack from package.json, pyproject.toml, etc.
   • Tools mentioned in CLAUDE.md or README.md
   • Data sources referenced in code
   • Platforms (deployment targets, APIs, databases)

3. Fill existing stub notes — if any .md files in the hub vault are empty (created as wikilink targets but never filled), populate them with frontmatter + content + cross-links.

4. Enrich the owner note — the {owner-name}.md note should link to all MOCs, all projects, and key tools. This makes it the central hub of the entire graph.

Seeding rules:

• Target 4-8 outgoing [[wikilinks]] per note — this creates visible graph density
• Every entity note must link to at least one MOC and one project
• Every MOC must link to the owner note and at least 3 entities
• Use bidirectional linking — if A links to B, B should link back to A
• Never create notes for things that don't exist — only seed from what was actually discovered in Step 1
• Skip notes that already exist in the hub vault — never overwrite
• Count total notes created and total wikilinks generated for the summary

After seeding, report:

🌐 Graph seeded:
   {N} MOC hub notes created
   {M} entity notes created
   {K} stub notes filled
   {T} total [[wikilinks]] across all new notes
   Estimated graph density: {average links per note}

Step 4: Context Injection

Skip this step if ARCH_MODE = hub-spokes — Step 3h already wired ~/.claude/CLAUDE.md to the hub. The project CLAUDE.md also already references the hub. Nothing more needed.

For per-project or centralized mode, ask:

One last thing — how do you want your vault context loaded into Claude Code?

1. Global (recommended) — loads your vault context automatically in every Claude Code
   session on this machine (adds one line to ~/.claude/CLAUDE.md)
2. Vault-scoped — works automatically when you run 'claude' from inside this folder
3. Manual — I'll give you the line to paste where you need it

If Global selected: append to ~/.claude/CLAUDE.md (create if needed):

## My Brain
At the start of every session, read [absolute vault path]/CLAUDE.md for context about who I am, my work, and my conventions.

If Manual: show the line to paste.

Step 5: Final Summary

✅ Your AI Brain is live.

📁 Vault:      [project path]
🏛 Hub:        [hub path — if hub+spokes, else "none"]
🧠 Memory:     4 files initialized
📋 Rules:      7+ default rules active
🔗 Hooks:      session continuity installed
⚡ Obsidian CLI: [detected / not detected]
🌐 Architecture: [Hub+Spokes / Per-Project / Centralized]

[If Hub+Spokes:]
  Hub wired:   ~/.claude/CLAUDE.md → [hub path]/CLAUDE.md
  Project registered in [hub path]/Machine/Memory/projects.md
  Every session on this machine now loads your global identity.

[If graph was seeded (Hub+Spokes):]
  🌐 Graph seeded:
     {N} MOC hub notes — domain clusters for graph view
     {M} entity notes  — bridge nodes (tools, platforms, concepts)
     {K} stub notes filled
     {T} total [[wikilinks]] across all new notes
     Open Obsidian graph view to see your knowledge graph.

Your slash commands:
  /brain-today    — run this tomorrow morning
  /brain-new      — drop any thought, it gets routed automatically
  /brain-tldr     — summarize and save this session
  /brain-debrief  — end-of-day ritual

[If files to import:]
  Drop files into Human/Projects/ then run:
  /brain-ingest [path] — extracts signal, creates clean notes

[If Obsidian not detected:]
  Optional: Install Obsidian 1.12+ → Settings → General → Advanced → Enable CLI
  Re-run /brain-setup to activate enhanced vault integration.

<success_criteria>

• Brain detects context automatically when available (no unnecessary questions)
• User sees a personalized vault preview before anything is created
• Nothing is built until user confirms
• .brain/ exists with state.json and brain.yaml
• Human/ and Machine/ hemisphere structure exists
• All 4 memory files created in Machine/Memory/
• active-rules.md exists with 7 default rules
• CLAUDE.md generated at vault root
• Hook scripts are executable
• Context injection configured per user's choice
• If Hub+Spokes: knowledge graph seeded with MOC hubs, entity notes, and cross-links (4+ wikilinks per note, zero orphan notes)
• User sees clear final summary with next steps including graph seeding stats </success_criteria>