Step 1: Why Traditional Note Systems Die (The “Curator Trap”)
Most note-taking systems (like manual Notion or Obsidian setups) fail after a few weeks for one simple reason: manual maintenance debt. You bookmark articles, copy meeting notes, or clip PDFs intending to organize them later, but tagging, cross-linking, and updating summaries by hand becomes tedious. Eventually, the system becomes a cluttered digital graveyard.
Query-Time RAG vs. The Compounding LLM Wiki
Standard AI chat tools (like ChatGPT uploads or basic RAG search) re-read your uploaded documents from scratch every single time you ask a question[2]. Once the chat window closes, that synthesized understanding disappears[10][11].
In Andrej Karpathy’s LLM Wiki pattern , we flip this relationship
- Instead of you organizing notes for the AI, the AI organizes and maintains the notes for you
- Instead of re-analyzing documents on every question, the AI incrementally compiles raw material into clean, interconnected Markdown files
- Knowledge compounds over time : when you add a new article or meeting transcript, the AI reads it, updates existing concept pages, flags contradictions, and links new ideas together
Traditional Note Systems The AI Second Brain Paradigm
┌───────────────────────────────┐ ┌───────────────────────────────────┐
│ Manual Tagging & Filing │ │ Drop raw files into raw/ folder │
│ (Becomes tedious & dies) │ └─────────────────┬─────────────────┘
└───────────────────────────────┘ │ (AI Agent Ingests)
▼
┌───────────────────────────────┐ ┌───────────────────────────────────┐
│ Standard Ephemeral AI Chat │ │ Compiled Markdown Wiki & Graph │
│ (Resets every session) │ │ (Compounding Knowledge Base) │
└───────────────────────────────┘ └─────────────────┬─────────────────┘
│ (Automated Background Loops)
▼
┌───────────────────────────────────┐
│ Self-Updating, Non-Stale Brain │
└───────────────────────────────────┘
How It Updates Automatically Without Tedious Manual Work
To ensure your second brain stays updated and never becomes stale without you lifting a finger, the system uses Automated Maintenance Loops :
- Frictionless Dump Inbox ( raw/ ): You simply drop web clips, PDFs, voice note transcripts, or meeting notes into a single folder without sorting them.
- Scheduled Ingestion Jobs: You set up a scheduled background task (e.g., in Claude Desktop or via a simple system trigger) that runs daily at 7:00 AM or 9:00 AM. The agent automatically processes everything sitting in raw/, creates or updates topic pages in wiki/, adds backlinks, and archives the processed raw files.
- Automated Health Checks ( /lint ): The AI periodically runs a “health check” over the entire vault. It scans for stale claims that newer documents have superseded, repairs broken links, flags contradictions between old and new notes, and fills data gaps.
Because Large Language Models don’t get bored and can edit 15 files in a single pass, the maintenance cost drops to zero for you
Step 2: The 3-Folder & Two-Layer System Architecture
Now that we understand the core philosophy behind an AI Second Brain, we need to look at how the system is organized on your computer.
To prevent information clutter and keep your AI agent focused, the system uses a 3-Layer Architecture (often organized into 5 primary folders in complete implementations).
The Three Core Layers
┌─────────────────────────────────────────────────────────────────────────┐
│ THE 3-LAYER WIKI ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────┤
│ 1. RAW LAYER (`raw/`) │
│ The immutable junk drawer: PDFs, web clips, transcripts, notes │
├─────────────────────────────────────────────────────────────────────────┤
│ 2. COMPILED WIKI LAYER (`wiki/`) │
│ AI-maintained Markdown files: atomic concepts, entities, sources │
├─────────────────────────────────────────────────────────────────────────┤
│ 3. SCHEMA & SYSTEM CONTEXT (`CLAUDE.md` / `AGENTS.md`) │
│ The root system contract governing styling, rules, and schemas │
└─────────────────────────────────────────────────────────────────────────┘
Layer 1: Raw Sources (raw/) The Immutable Junk Drawer
- What it is: The single entry point where all new information lands.
- What goes inside: Web article clips, PDF research papers, YouTube video transcripts, podcast notes, exported chat histories, and voice recordings.
- The Golden Rule of Raw: Raw sources are immutable. The AI reads from them to compile knowledge, but it never edits or deletes your original files. They serve as your permanent, unalterable source of truth.
Layer 2: The Compiled Wiki (wiki/) The AI's Domain
- What it is: The actual Second Brain a structured, deeply interlinked network of plain Markdown (.md) files that the AI writes, links, and maintains. You rarely write or edit files in this folder manually; it is entirely managed by the AI agent.
- Inside the wiki/ folder:
- wiki/sources/ : Contains concise, structured summaries of every raw file ingested.
- wiki/concepts/ : Atomic idea pages (one core concept per file) that compound in value as new information is linked.
- wiki/entities/ : Dedicated pages for key people, organizations, software tools, and frameworks.
- wiki/synthesis/ : High-level thematic overviews generated when multiple sources connect to form new insights.
- wiki/index.md : A content-oriented catalog listing every page, category, and topic summary. The AI reads this index first during queries to navigate the vault efficiently without overloading its working memory.
- wiki/log.md : A chronological, append-only operations log tracking every ingestion, linting check, and structural update.
Layer 3: System Schema (CLAUDE.md / AGENTS.md) The Rules of Engagement
- What it is: A single configuration file sitting at the root of your folder structure.
- Why it matters: When an AI agent (like Claude Code or Cursor) opens your Second Brain, it reads CLAUDE.md first. This file gives the agent its personality, rules, linking instructions, and metadata formatting rules so it treats your vault consistently every single session.
The Two-Layer Distinction: Knowledge vs. Action
To prevent your long-term research from getting mixed up with daily to-do lists, the Second Brain OS framework divides your system into two distinct operational layers:
┌─────────────────────────────────────────────────────────────────────────┐
│ TWO-LAYER SYSTEM ARCHITECTURE │
├────────────────────────────────────┬────────────────────────────────────┤
│ THE WIKI LAYER │ THE PROJECT LAYER │
│ (What You Know) │ (What You Do) │
├────────────────────────────────────┼────────────────────────────────────┤
│ • Densely linked concept graph │ • Isolated subfolders per project │
│ • Long-term memory & research │ • Structured 4-stage pipeline: │
│ • Maintained automatically by AI │ Inputs -> Process -> Outputs -> │
│ • Non-linear, compounding network │ Feedback │
│ • Scope: Broad & permanent │ • Scope: Scoped & goal-oriented │
└────────────────────────────────────┴────────────────────────────────────┘
- The Wiki Layer (wiki/): **Holds everything you know**. It is non-linear, permanent, and grows denser over time.
- The Project Layer (projects/): **Holds everything you are doing** right now (e.g., launching a podcast, writing a report, or preparing a client presentation). Each project gets its own subfolder containing a standard 4-stage pipeline:
- Inputs/ : Specific raw files needed for this task.
- Process/ : Drafts and working notes where the AI collaborates with you.
- Outputs/ : Finished, deliverable products.
- Feedback/ : Metrics, reviews, and retrospective notes.
When you complete a project, its finished deliverables are filed back into the Wiki so your operational work feeds into your permanent knowledge.
Supplementary Support Folders
In addition to raw/, wiki/, and projects/, two utility folders round out the file structure:
- archive/ : When a raw file from raw/ is processed and compiled into the wiki, the original file is moved into archive/. This keeps your raw/ folder clean as a zero-friction inbox.
- prompts/ (or **.claude/skills/)**: Stores your reusable AI commands and workflows (e.g., translation prompts, summarization skills, and linting scripts).
Standardization: Open Knowledge Format (OKF) & YAML Frontmatter
To ensure your Second Brain is future-proof and readable by any AI model or note app, every page in wiki/ uses YAML Frontmatter at the top of the file. This follows the Open Knowledge Format (OKF) standard published by Google Cloud.
Here is what an atomic concept page inside wiki/concepts/ looks like:
---
type: concept
title: "System 2 Thinking in LLMs"
created: 2026-09-23
tags: [ai/cognition, machine-learning/reasoning]
sources: ["[[Source - Karpathy LLM Deep Dive]]"]
---
# System 2 Thinking in LLMs
System 2 thinking refers to deliberate, multi-step reasoning processes where an AI model spends inference compute to evaluate intermediate steps, backtrack on errors, and verify its logic before generating a final answer.
## Key Mechanisms
- **Chain of Thought (CoT):** Generating explicit internal reasoning tokens prior to the final response.
- **Reinforcement Learning Alignment:** Training models via RL reward signals on verifiable problem domains (e.g., math and programming) to discover optimal reasoning paths.
## Related Concepts
- [[Parametric Memory vs Context Window]]
- [[Tool Use and Code Execution]]
- [[LLM Psychology and Hallucinations]]
Notice how [[double brackets]] are used to link pages together. When the AI writes these links, software like Obsidian automatically draws a visual node graph connecting every concept across your entire vault.
Step 3: Setting Up Your Stack (Obsidian, Claude, and the MCP Connection)
Now that you understand the 3-folder architecture (raw/, wiki/, and projects/), it is time to build your actual working environment.
In traditional note-taking, you are responsible for typing, organizing, tagging, and cross-linking every single file by hand. In an AI Second Brain, we split the labor between two distinct tools:
- Obsidian (The Visual IDE / Viewer): A free, local Markdown editor that displays your notes, backlinks, and visual concept graphs.
- Claude Code / Claude Co-work (The Programmer & Maintainer): The AI agent that reads your raw files, compiles new concept pages, links notes together, and performs health audits.
- Model Context Protocol (MCP): The secure protocol bridge that allows Claude to reach into your local Obsidian vault and read/write files directly.
As Andrej Karpathy famously summarized this setup: “Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.”
┌─────────────────────────────────────────────────────────────────────────┐
│ THE AGENTIC SECOND BRAIN STACK │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────┐ ┌──────────────────────────┐ │
│ │ Obsidian (Frontend) │ │ Claude Code (Agent) │ │
│ │ • Local Markdown Files │ │ • Reads raw/ documents │ │
│ │ • Visual Knowledge Graph│ │ • Generates wiki pages │ │
│ │ • Backlink Navigation │ │ • Runs /ingest and /lint │ │
│ └───────────┬────────────┘ └────────────┬─────────────┘ │
│ │ │ │
│ │ ┌───────────────────────┐ │ │
│ └──────>│ Local REST API Plugin │<──────┘ │
│ │ & MCP Server Bridge │ │
│ └───────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Phase 1: Installing & Setting Up Obsidian (The Storage Base)
Obsidian is a free, local-first note-taking application. Unlike cloud platforms that lock your data into proprietary databases, Obsidian stores every note as a plain Markdown file (.md) directly on your computer's hard drive.
Step-by-Step Installation:
- Download Obsidian: Navigate to obsidian.md in your browser, download the installer for your operating system (macOS, Windows, or Linux), and run the setup wizard.
- Create Your First Vault:
- On the welcome screen, select “Create new vault”.
- Set the vault name to brain (or second-brain).
- Choose a folder location on your computer (such as your user home directory or desktop).
- Click Create.
Understand the Core Linking Mechanic:
- In Obsidian, click the New Note icon.
- Type two square brackets like this: [[My First Concept]].
- Obsidian automatically turns bracketed text into an inter-file link. When you or your AI agent create these links across multiple pages, Obsidian automatically draws an interactive visual knowledge graph connecting your ideas.
Phase 2: Installing & Configuring Claude Code (The Agent Engine)
To give your Second Brain an autonomous worker, you need an AI tool capable of inspecting directories and editing local text files.
Setup Steps:
- Download Claude Desktop: Go to claude.com/download and install the Claude Desktop application.
- Ensure Access to Claude Code / Co-work: Open Claude Desktop and sign in. Make sure you have access to Claude Code (the terminal/developer interface) or Claude Co-work (the desktop workspace interface).
- Verify Local Directory Access: Claude Code operates directly inside your local folder structure, giving it the ability to create, read, update, and organize files in real time.
Phase 3: Bridging Obsidian and Claude via Local REST API & MCP
To allow Claude to access your Obsidian vault safely, we set up a secure bridge using the Local REST API plugin and Model Context Protocol (MCP).
Obsidian Vault ──> Local REST API Plugin (Port 27124) ──> MCP Server Bridge ──> Claude Code
Step 1: Turn on the Local REST API Plugin in Obsidian
- Inside Obsidian, click the Settings gear in the bottom-left corner.
- Navigate to Community Plugins -> click Turn on community plugins.
- Click Browse , search for Local REST API, click Install , and then click Enable.
- Click on Local REST API under your installed plugins list to open its configuration page.
- You will see an API Key (a long string of characters). Copy this key to your clipboard. (Note: Do not copy the word “Bearer”, just the string itself).
- Keep Obsidian open. The connection functions whenever the Obsidian application is running on your machine.
Step 2: Register the Vault Bridge in Claude Code
Open your terminal or the Claude Code command panel, and run the registration command:
claude mcp add-json obsidian-vault '{
"type": "stdio",
"command": "uvx",
"args": ["mcp-obsidian"],
"env": {
"OBSIDIAN_API_KEY": "YOUR_COPIED_API_KEY_HERE",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}'
This command installs mcp-obsidian via uvx and registers your vault as a native Model Context Protocol tool inside Claude.
Phase 4: Testing & Verification
Once configured, verify that your agent can read and write inside your vault.
In your Claude Code command window, type:
“List every file in my Obsidian vault.”
If the integration is successful, Claude will communicate with Obsidian over port 27124, inspect your directory, and print out your folder layout.
Phase 5: Loading Your Profile Generating CLAUDE.md
An empty Second Brain lacks personalized context. Instead of writing system instructions manually, you can have Claude conduct a structured interview to build your root contract file (CLAUDE.md).
Paste this prompt into Claude Code:
You are setting up my second brain. Interview me ONE question at a time to build my profile.
Ask about:
1. Who I am and what I do
2. My goals for this year
3. How I want you to communicate with me
4. My primary domains of knowledge and interest
5. My current active projects
Wait for my answer before asking the next question. When finished, write everything into a file called CLAUDE.md at the root of my vault, structured with clear markdown headers, so you load it automatically every session.
When the interview concludes, Claude writes a comprehensive CLAUDE.md file at your vault root. From that point on, every time Claude opens your Second Brain, it reads CLAUDE.md first—instantly recalling your goals, preferred tone, and working style without you having to re-explain yourself.
Phase 6: Configuring a Project Workspace
To maintain focus during active execution (like writing a report or launching a product), we scope down to a dedicated Project Folder inside projects/:
projects/my-new-project/
├── Inputs/ # Raw files and references specific to this project
├── Process/ # Drafts, working notes, and AI collaboration
├── Outputs/ # Final finished deliverables
├── Feedback/ # Reviews, metrics, and retrospective notes
└── CLAUDE.md # Project-specific goals and rules
You can ask Claude to scaffold this automatically:
“Create a project folder in my vault called research-report. Inside it, create four folders: Inputs, Process, Outputs, and Feedback. Then write a CLAUDE.md inside that project folder describing its single goal."
When working on that specific deliverable, you can open just projects/research-report/ as your active workspace in Obsidian and Claude, keeping the AI's context window 100% focused on that task.
Architectural Safeguards & Security Principles
When setting up your AI agent stack, keep two essential safety principles in mind:
- Keys, Not Prompts: Prompt instructions like “Please do not delete my files” are suggestions that an LLM might occasionally misinterpret. Enforce file security at the permissions level using read-only keys, local file isolation, and strict tool permissions.
- Plain Text Sovereignty: Because your Second Brain consists entirely of standard Markdown text files on your local drive, you are never locked into a single software vendor. If a better AI model comes out next year, you can point it at the exact same folder and continue seamlessly.
Step 3 Summary
- Obsidian provides the local visual interface and graph view.
- Claude Code acts as the automated programmer writing and organizing notes.
- Local REST API + MCP connects them securely on your machine.
- CLAUDE.md serves as the persistent memory and rulebook for every session.
Next we will move to Automated Maintenance & Anti-Stale Loops (Setting Up Scheduled Runs and /lint Checks)!
Need High-Impact Technical Content for Your Team?
I help engineering-focused companies, developer-tooling startups, and SaaS platforms explain complex infrastructure, backend architecture, and developer tooling through publication-grade articles.
Whether you need deep-dive technical essays, developer guides, or architecture counter-narratives, feel free to reach out:
- 📩 Email: abhishekninja2018@gmail.com
- 💼 LinkedIn: linkedin.com/in/abhishekninja
- 🛠️ Capabilities: Long-form Technical Essays | Hands-On Developer Tutorials | System Architecture Breakdowns | Benchmarks & Product Comparisons
Top comments (0)