Designing a Second Brain for AI Agents: The Vault-as-Database Pattern

ArchitectureDesign

The Two-Layer Architecture

The dominant second brain architecture in 2026 is a two-layer system: a structured local knowledge base of plain text markdown files, and an AI agent that reads and writes to it. The vault is the foundation, Claude Code is the engine (from obsidian claude code jarvis cyrilxbt). This pattern has emerged independently across dozens of implementations because plain text markdown is the only format that satisfies all the constraints simultaneously: human-readable, AI-readable, version-controllable, portable across tools, and free from vendor lock-in.

The architecture works because of a property that most people overlook: when Claude Code opens a session in a repo, it can read every file in that repo. Your second brain isn't just a knowledge store -- it's the interface between you and AI. The repo IS the context window (from brain as context window). This means every organizational decision you make -- how you name files, how you structure directories, what metadata you include in frontmatter -- directly affects the quality of AI reasoning over your knowledge. A well-organized vault produces executive-level output. A messy one produces generic slop.

This is not a theoretical distinction. The gap between generic and executive-level Claude output is entirely a context/setup problem, not a model capability problem (from claude cowork workspace setup system). Most people start every session from scratch, then wonder why the AI gives them boilerplate. The people getting extraordinary results have pre-loaded their context -- their identity, their projects, their voice, their history -- into a structure the AI can consume before the first prompt.

The pattern is also agent-agnostic. Agentic workflows running on local file-based knowledge stores work across Cursor, Claude Code, OpenCode, and anything else that can read a filesystem (from obsidian agentic workflows). You are not betting on one tool. You are betting on the filesystem, which is the most durable interface in computing.

Why Context Delivery Is the Real Bottleneck

Tiago Forte's PARA system and the broader Building a Second Brain methodology dominated personal knowledge management for the past decade. But the arrival of AI agents has reframed the entire problem. Forte Labs now calls this "Personal Context Management" -- and the reframe is precise: the bottleneck isn't AI capability, it's your ability to give AI the right information at the right time (from brain as context window).

This is the insight that separates people who use AI as a search engine replacement from people who use it as an extension of their own thinking. When Claude has access to your vault, it is not answering from the internet -- it is answering from you. Your frameworks, your research, your perspective, your accumulated knowledge (from obsidian claude code jarvis cyrilxbt). Six months of your own captured research lets you ask meta-questions about your own thinking patterns. That is pattern recognition amplified by a machine that never forgets what you wrote.

The practical implication is that every minute you spend improving your knowledge base's structure is a multiplier on every future AI interaction. Connecting live data sources -- Slack, Gmail, Calendar, Notion -- to your workspace lets Claude pull real data instead of guessing, and that is a bigger lever than better prompting (from claude cowork workspace setup system). Content drafts that used to take three rounds of revision land on the first try once Claude has pre-loaded context about who you are, how you write, and what you're working on (from claude cowork workspace setup system).

The people getting the most leverage are content creators. Your entire content history in the vault lets Claude draft new content that sounds like you because it's built from your own writing. It can identify your strongest performing angles and surface what you haven't covered yet (from obsidian claude code jarvis cyrilxbt). This isn't prompt engineering. This is context engineering -- and the difference is the same as the difference between asking a stranger for advice and asking a partner who's read everything you've written for the past year.

The Maintenance Problem and Its Solution

Every previous note-taking system died the same death: maintenance. Tagging, organizing, linking, updating, archiving -- the overhead eventually exceeds the value, and the system decays into a digital graveyard. Exo Brain identifies this as the fundamental problem and offers the fundamental solution: make Claude do the maintenance (from exo brain obsidian claude second brain).

The architecture is a self-feeding read/write loop. Claude reads your vault before every session, gaining context about your projects, your voice, and your current priorities. After working, it writes back: summaries of decisions, extracted action items, and synthesized notes. The vault gets richer without you lifting a finger (from exo brain obsidian claude second brain). This is the key architectural innovation that makes AI-native knowledge management possible: the system maintains itself.

But there's a critical design constraint that separates good implementations from dangerous ones: agents read, humans write. Vault content should stay purely human-authored. AI-generated text in the vault contaminates pattern detection -- when you ask Claude to find patterns in your notes, you want it finding your patterns, not patterns it planted (from exo brain obsidian claude second brain). The Exo Brain system enforces this by having thinking tools (like /emerge for pattern detection and /connect for bridging domains) analyze notes and respond in-session, but never write into the vault's knowledge files.

This principle has implications for any AI-augmented knowledge system you build. There should be a clear separation between:

  1. Human-authored knowledge -- your notes, insights, research, captured thoughts. These are the ground truth.
  2. Agent-generated metadata -- summaries, indexes, cross-references, session logs. These are derived artifacts.
  3. Agent working memory -- scratchpads, logs, intermediate reasoning. These are ephemeral.

The first category is sacred. The second is useful but replaceable. The third is disposable. When your system respects these boundaries, you get honest pattern detection. When it doesn't, you get an AI echo chamber that tells you what it already told you.

The CLAUDE.md File: Your System Prompt for Life

The most important file in any vault-as-database system is the one that gets read first. In the Claude Code ecosystem, that file is CLAUDE.md -- and the correct way to think about it is as the system prompt for your life (from exo brain obsidian claude second brain).

CLAUDE.md loads automatically at the start of every Claude Code session. It teaches the agent who you are, what you're working on, how you want things done, and what your preferences are. The most effective implementations keep it under 200 lines and use it to establish context, not to micromanage behavior. It should answer three questions:

  1. Who am I working with? -- Your name, role, projects, communication style
  2. What's the repo structure? -- Where things live, what the conventions are, how files relate
  3. What are the rules? -- Execution expectations, quality standards, boundary conditions

The Exo Brain system extends this with a companion memory.md file -- a simple append-only session log that Claude updates after each conversation. No indexing infrastructure, no database, no maintenance. Just a running record that compounds over time (from exo brain obsidian claude second brain). The compounding effect is real: Session 1 Claude knows your folder layout. Session 5 it knows your projects, preferences, and voice. Session 20 it has better recall of your work than you do (from exo brain obsidian claude second brain).

The Interface Design skill by @Dammyjay93 applies the same pattern to a specific domain: it stores design specs -- spacing grids, color palettes, depth strategies, component patterns -- in a persistent system.md file that loads automatically (from design without designing neethanwu). The problem it solves is agents forgetting design decisions between sessions. The solution is a file that carries those decisions forward. This pattern generalizes to any domain where decisions need persistence: writing style, code conventions, business rules, research methodology.

A fuller approach structures this context into phases. An 8-phase bootstrap prompt can systematically build an entire workspace: Plugins and Connections, About Me, Brand Voice, Working Preferences, Content Strategy, Team and Contacts, Active Projects, and Memory System (from claude cowork workspace setup system). You don't need to build all eight at once. Start with "About Me" and "Active Projects" and add layers as you discover what context produces the biggest quality jumps.

File System as Database: The Structural Decisions

The vault-as-database pattern replaces traditional databases with a directory structure that serves as both storage and schema. Here's why this works and how to structure it.

Why Files Beat Databases for Agent Knowledge

Traditional databases require APIs, query languages, and connection management. Files require nothing. Point an agent at a directory and it reads. This zero-setup property is why the file-system-as-database approach has won: it's agent-agnostic and portable (from obsidian agentic workflows). Any AI tool that can read a filesystem -- Cursor, Claude Code, OpenCode, Codex -- can reason over your knowledge with zero integration work.

The filesystem also gives you version control for free. Every file is a Git object. Every change has a timestamp, an author, and a diff. You get branching, merging, history, and rollback without building anything. When your knowledge base is a repo, you get all the collaboration and audit trail machinery that software engineering has refined over decades.

Directory Structure as Schema

Your directory structure IS your database schema. Each top-level directory represents a collection, each file represents a record, and YAML frontmatter represents columns. Here's a production structure:

vault/
  sources/          # Raw inputs from the world
    tweets/         # Captured tweets with extracted insights
    meetings/       # Meeting transcripts and summaries
    slack/          # Slack thread captures
    dictation/      # Voice-to-text captures
    captures/       # Freeform notes and ideas
    github/         # README-as-article content
  topics/           # Synthesized knowledge, one file per topic
    topic-name.md   # Simple topic
    topic-name/     # Hierarchical sub-topics when a topic grows
  plans/            # Structured action plans
  guides/           # Polished, curated answers
  asks/             # Saved Q&A with citations
  CLAUDE.md         # System prompt -- loaded every session
  memory.md         # Append-only session log

The separation between sources/ and topics/ is the most important structural decision. Sources are raw inputs -- timestamped, attributed, immutable after creation. Topics are living documents that get continuously enriched as new sources arrive. This mirrors the distinction between a data lake (sources) and a data warehouse (topics). Sources accumulate. Topics compound.

Frontmatter as Metadata Layer

Every file begins with YAML frontmatter that serves as the metadata layer. For sources:


type: tweet
date: "2026-03-22"
source_url: "https://x.com/..."
author: "@handle"
topics: ["topic-slug-1", "topic-slug-2"]
synthesized: false
tags: ["tag1", "tag2"]

For topics:


topic: slug
created: "2026-03-22"
last_synthesized: "2026-03-27"
source_count: 14

The synthesized field on sources is a state machine: false means unprocessed, true means its insights have been extracted into topic files. This lets the system know what work remains. The topics array on sources links to topic files via slugs, creating a bidirectional graph between raw inputs and synthesized knowledge.

File Naming Convention

Use YY-MM-DD-<slug>.md for everything. The date prefix gives you chronological sorting for free and prevents name collisions. Slugs are lowercase with hyphens: 26-03-22-obsidian-claude-code-jarvis.md. Derive the slug from the content's core subject, not from the source title. When an agent needs to find a file, it can grep by date range, by slug keyword, or by frontmatter field.

Wikilinks as the Graph Layer

Use [Filename Without Extension](/topics/filename-without-extension) to link between files. Sources link to topics: [Claude](/topics/claude), [Maven Agi](/topics/maven-agi). Topics link to other topics. Plans link to both. This creates a navigable knowledge graph that agents can traverse to find related context. In Obsidian, these are clickable links. In Claude Code, they're searchable references. The same syntax serves both human browsing and agent reasoning.

Progressive Disclosure: Managing What the Agent Sees

Context windows are finite. Even with million-token context, you can't dump your entire vault into every session and expect good results. The solution is progressive disclosure -- a layered context strategy where each layer loads only when needed.

Layer 0: Always Loaded

CLAUDE.md loads automatically at session start. Keep it under 200 lines. It should contain the minimum context needed for the agent to orient itself: who you are, what the repo structure is, and what the active conventions are. Think of it as the agent's working memory bootstrap.

Layer 1: Session Context

When you start a specific task, load the relevant files for that task. If you're writing about a topic, load the topic file and its key source files. If you're planning, load the relevant plan and the topics it references. The agent can discover these through frontmatter links and wikilinks -- you don't need to manually specify every file.

Layer 2: Deep Retrieval

For questions that span many sources or topics, the agent needs a retrieval step. Skills like /ask or /synthesize can scan the full vault, pull relevant files, and assemble a focused context package. This is where the frontmatter metadata pays off -- the agent can filter by date, topic, type, and synthesized status without reading every file.

Layer 3: External Context

Live data sources -- Slack, email, calendar, project management tools -- provide real-time context that the vault doesn't capture. Connecting these via MCPs lets the agent pull fresh data on demand. The cf-crawl skill demonstrates this pattern: a daily crawl job keeps a local markdown knowledge base in sync with upstream documentation, so Claude always has fresh docs without manual curation (from cf crawl scheduled knowledge base). The pattern of crawl-to-markdown plus agent access creates a self-updating context layer (from cf crawl scheduled knowledge base).

The key principle is that each layer is progressively more expensive (in tokens and latency) and should only be invoked when the cheaper layers can't satisfy the request. CLAUDE.md is free -- it loads every time. Scanning the full vault costs real tokens. Hitting external APIs costs time and money. Design your system so the common case is cheap and the rare case is thorough.

The Scratchpad Pattern: Agent Memory That Compounds

Beyond the vault itself, agents need a distinct form of working memory -- not session history (which is lossy), not todos or plans (which are static), but a live scratchpad that the agent writes to as it works (from agent scratchpad napkin pattern).

The scratchpad (or "napkin") pattern was articulated by Siqi Chen and is a form of baby continual learning: a markdown file where the agent records its mistakes, corrections, and what worked becomes a lightweight memory system that bridges the gap between stateless sessions and true learning. Agents that log their own errors and lessons exhibit compounding improvement -- by session five, the tool behaves fundamentally differently (from agent scratchpad napkin pattern).

This pattern generalizes beyond coding to any domain where an AI can benefit from tracking its own failure modes over time: writing, research, legal analysis, design critique (from agent scratchpad napkin pattern). The key insight is that the scratchpad is neither knowledge (which belongs in topics) nor configuration (which belongs in CLAUDE.md) -- it's operational context, and it needs its own home.

In a vault-as-database system, the scratchpad sits alongside CLAUDE.md and memory.md:

vault/
  CLAUDE.md         # Identity and conventions (static)
  memory.md         # Session log (append-only)
  scratchpad.md     # Agent working notes (read/write)

The Claude Subconscious project pushes this further. It runs a background Letta agent that processes full session transcripts silently, maintaining 8 persistent memory blocks: coding preferences and style choices, project architecture decisions and known gotchas, session patterns including recurring struggles and common mistakes, pending items and unfinished work, and active guidance surfaced before each prompt (from claude subconscious ai memory agent). One agent brain connects across all projects simultaneously, so context built in one repo carries into the next (from claude subconscious ai memory agent).

The practical architecture for scratchpad memory is:

  1. After each session: The agent appends to memory.md what it learned, what went wrong, and what decisions were made.
  2. During each session: The agent reads scratchpad.md for operational notes and updates it with new observations.
  3. Across sessions: A background process (or hook) synthesizes memory.md entries into durable scratchpad patterns.

This gives you three timescales of memory: within-session (scratchpad writes), across-sessions (memory.md log), and long-term (synthesized patterns). Each feeds the next.

The Ingestion Pipeline: How Knowledge Enters the System

A second brain is only as good as what goes into it. The ingestion pipeline determines both the breadth of your knowledge base and the quality of what agents can reason over. Here's how to build one that runs without manual intervention.

Source Types and Their Capture Methods

Different source types need different capture pipelines:

Source Capture Method Automation Level
Tweets/posts CLI tool + Claude API enrichment Fully automated (nightly)
Meetings Granola MCP or transcript API Semi-automated
Slack threads Slack MCP On-demand
GitHub repos gh CLI, README extraction On-demand
Voice notes Wispr Flow or dictation app On-demand, human-triggered
Freeform Manual /capture command Human-initiated
Documentation Crawl-to-markdown pipeline Fully automated (daily)

The highest-leverage automation is the nightly batch. A scheduled task runs at a fixed time, pulls new content from your bookmarks or feeds, enriches each item through Claude API (extracting insights, matching to existing topics, generating metadata), and writes structured source files into the vault. By morning, your knowledge base is updated with everything you encountered the previous day, organized and ready for reasoning.

The Enrichment Step

Raw captures are low-value without enrichment. The enrichment step transforms a raw source (a tweet, a transcript, a bookmark) into a structured record with:

  1. Extracted insights -- atomic, actionable observations pulled from the source
  2. Topic matching -- links to existing topic files in your vault
  3. Metadata -- author, date, engagement metrics, source URL
  4. Wikilinks -- inline references that connect this source to the knowledge graph

This enrichment step is where Claude API adds the most value. The model reads the raw content, identifies the key insights (typically 3-8 per source), matches them to your existing topic taxonomy, and formats everything into the standard source file template. The insight format matters: each insight should be a specific, actionable observation with an inline citation back to its source, not a vague summary.

Topic Matching and Creation

When a new source arrives, the system scans topics/ for existing topic files and checks whether the source content matches any topic keywords. Matched topic slugs go into the source's frontmatter topics field, and wikilinks to those topics appear in the Extracted Insights section.

The important rule: if a source doesn't match any existing topic, create one. If you bookmarked it, it mattered. A single source is enough to seed a new topic. The synthesis step later enriches that topic as more sources accumulate. Being too conservative about topic creation starves your system of structure. Being too aggressive just means you have some thin topics that fill out over time.

Self-Updating Knowledge Bases

The crawl-to-markdown pattern extends the ingestion pipeline to external documentation. Combining Claude Code skills with Scheduled Tasks creates autonomous pipelines that keep a local markdown knowledge base in sync with upstream docs (from cf crawl scheduled knowledge base). A daily crawl job pulls documentation from the sites you care about, converts each page to markdown, and drops it into a /docs directory. Claude always has fresh documentation without manual curation.

This is the pattern you should apply to any external knowledge source you regularly consult: API docs, competitor blogs, industry newsletters, regulatory updates. Set up the crawl, schedule the task, and your vault grows richer every day while you sleep.

Synthesis: Turning Sources into Compound Knowledge

Ingestion fills your vault with raw material. Synthesis turns that material into compounding knowledge. The synthesis pipeline reads unprocessed sources (where synthesized: false), extracts their insights, and weaves them into existing topic files -- or creates new topics when the source covers ground your system hasn't mapped.

Organizing by Theme, Not by Source

The most critical synthesis principle: organize insights by theme, not by source. Related ideas from different sources should be adjacent. When you open a topic file, you should see a coherent picture of a domain, with insights from various sources interwoven into a narrative -- not a chronological list of "insights from source A, insights from source B."

Bad topic structure:

### From [Source A](/topics/source-a)
- Insight 1
- Insight 2

### From [Source B](/topics/source-b)
- Insight 3
- Insight 4

Good topic structure:

## Insights

- [Theme A insight from source-a] (from [Source A](/topics/source-a))
- [Theme A insight from source-b] (from [Source B](/topics/source-b))
- [Theme B insight from source-a] (from [Source A](/topics/source-a))
- [Theme B insight from source-c] (from [Source C](/topics/source-c))

Each insight is a bullet with an inline citation. This lets you trace any claim back to its source while keeping the topic file readable as a coherent document. The topic file is the thing you want the agent to read when it needs to understand a domain. It should read like a briefing document, not a bibliography.

Hierarchical Topics

When a topic grows large (30+ insights), split it into sub-topics. The parent file becomes a summary with a sub-topics index, and each sub-topic gets its own focused file:

topics/claude.md              # Parent: summary + index
topics/claude/
  workflow.md                 # Sub-topic: research-plan-build loop
  settings.md                 # Sub-topic: configuration mechanisms
  architecture.md             # Sub-topic: vault-as-database patterns
  design.md                   # Sub-topic: design tools and workflows

The parent file links to sub-topics: [Workflow](/topics/claude/workflow), [Design](/topics/claude/design). Sub-topic files have parent: claude in frontmatter. This hierarchy lets agents navigate efficiently: read the parent for a broad overview, drill into sub-topics for depth. It's progressive disclosure applied to knowledge itself.

Cross-Cutting Pattern Detection

Beyond individual topic synthesis, the highest-value operation is finding patterns that span topics. The Exo Brain system calls this /emerge -- scanning for patterns implied by notes but never explicitly written (from exo brain obsidian claude second brain). The /connect command bridges two domains by walking notes for unexpected links (from exo brain obsidian claude second brain).

In a vault-as-database system, cross-cutting pattern detection works like this:

  1. Read all topic summaries (the cheap layer -- just the top of each topic file)
  2. Identify themes that appear across multiple topics
  3. Check whether these cross-cutting themes are already documented
  4. Surface the ones that aren't as new insights

This is the consolidation step, and it's where a knowledge system starts exhibiting emergent intelligence. Individual sources are data. Topics are information. Cross-cutting patterns are knowledge. The system compounds because each new source can shift the pattern detection across every topic it touches.

The Skills Layer: Making the Vault Operational

A vault full of knowledge is inert without operations that act on it. Skills -- instruction files that Claude Code reads and follows -- are what turn a knowledge base into an operating system.

Skills as Transferable Expertise

The most valuable skills don't just automate tasks -- they encode judgment. The Impeccable skill by @pbakaus catches 20+ AI design anti-patterns: overused fonts, gray-on-color text, pure blacks, nested cards. It transfers the taste of a seasoned designer into every developer's workflow (from design without designing neethanwu). Emil Kowalski's skill encodes how a design engineer at Linear thinks about animations and UI polish (from design without designing neethanwu). These skills work because they're stored as files in the vault -- part of the same filesystem the agent already reads.

The pattern generalizes to any domain. A writing skill can encode your editorial standards. A research skill can encode your evaluation criteria. A synthesis skill can encode how you want insights organized and cited. Each skill is a markdown file that transfers expertise from the human who wrote it to every agent that reads it.

Skills That Control Output Format

A new category of agent customization has emerged: skills that shape how the agent communicates, not just what it does (from visual explainer agent skill). The Visual Explainer skill transforms dense terminal output into rich HTML pages with consistent design via reference templates and a CSS pattern library (from visual explainer agent skill). The concept of "cognitive debt" from agent interactions is real -- agents can do more, but if their output is hard to parse, the productivity gain is eroded by comprehension overhead (from visual explainer agent skill).

In a vault-as-database system, output format skills serve two purposes:

  1. Human consumption: Making agent output easier to read and act on
  2. Vault ingestion: Formatting agent output so it can be cleanly written back to the vault

When a skill produces output that matches your vault's file format, the boundary between "agent response" and "vault content" disappears. The agent's output IS the knowledge base update.

The Component Library Analogy

Component libraries are building explicit support for agent workflows. shadcn/cli v4 introduced "shadcn/skills" as a first-class concept (from shadcn cli v4 skills), signaling that the ecosystem is building for agents, not just humans. Skills are installable via package managers (from cf crawl scheduled knowledge base), shareable across teams, and composable like software components.

This mirrors the evolution of web development: first you wrote everything from scratch, then you used libraries, then you used framework conventions. Agent workflows are on the same trajectory. First you wrote prompts from scratch. Now you install skills. Soon the skill ecosystem will be as rich as npm.

Cost Architecture: Running a Knowledge System at Scale

Running AI agents against a knowledge base isn't free. Understanding the cost structure lets you design a system that's sustainable at scale.

The 80/15/5 Distribution

Eighty percent of agent tasks are janitorial -- file reads, status checks, formatting, metadata updates. They don't require frontier model intelligence. Fifteen percent require moderate reasoning -- synthesis, summarization, insight extraction. Only five percent require frontier intelligence -- cross-cutting pattern detection, novel connections, strategic analysis (from hierarchical model routing cost).

Hierarchical model routing by task complexity achieves roughly 10x cost reduction. Route routine tasks to cheaper models, moderate tasks to mid-tier models, and only the hardest tasks to frontier models (from hierarchical model routing cost). For a knowledge system, this means:

The practical impact is dramatic. An all-frontier approach might cost $225/month. A hierarchical approach costs around $19/month for the same volume of work (from hierarchical model routing cost). At scale, this is the difference between a hobby project and a sustainable system.

Terminal Simplicity Reduces Overhead

Claude Code was born from a belief that the terminal is the right interface for AI-assisted work (from claude code origin story yc lightcone). The terminal is fast, keyboard-driven, scriptable, and composable with other tools. It has no rendering overhead, no JavaScript framework, no build step. For a knowledge system that runs multiple times per day, this simplicity translates directly into lower latency and lower cost.

The creator of Claude Code sees a tension between hyper-specialist and hyper-generalist AI tools, and opts for the generalist that adapts to user context (from claude code origin story yc lightcone). In a vault-as-database system, that context IS the vault. The terminal agent reads your CLAUDE.md, understands your conventions, and adapts. You don't need separate specialist tools for writing, research, planning, and coding -- you need one generalist with the right context.

Design Surfaces: Where Agents Meet the Vault

The vault-as-database pattern doesn't just apply to text-based knowledge work. The same architectural principles extend to visual work through agent canvases -- design surfaces that use your agents rather than embedding their own.

The Three-Layer Design Harness

Neethan Wu articulates a framework that applies the vault pattern to design: three layers that give engineering teams real design capability without becoming designers (from design without designing neethanwu).

Layer 1: Skills (the expertise) -- Instruction files that transfer someone else's design expertise. Impeccable catches anti-patterns. Emil Kowalski transfers animation thinking. Interface Design persists specs across sessions. These are vault files that encode judgment, exactly like knowledge skills.

Layer 2: Agent Canvases (the surface) -- Paper is a canvas built on real HTML and CSS, not a proprietary format. What you design is actual code. No translation layer, no handoff (from design without designing neethanwu). Pencil uses a Git-diffable JSON format and has swarm mode where up to six agents work on one canvas simultaneously (from design without designing neethanwu). These canvases sit in your repo, versioned like code, accessible to the same agents that read your knowledge base.

Layer 3: Inspiration (the eye) -- Variant's Style Dropper absorbs the visual DNA of any design and transfers it, exporting as React code or prompts for coding agents (from design without designing neethanwu). This bridges the gap between seeing a design you like and getting an agent to reproduce it.

The architectural insight: design files in your repo are just another type of vault content. When they're code-native (HTML/CSS, JSON) rather than proprietary (Figma, Sketch), agents can read and write them the same way they read and write markdown knowledge files.

Multimodal Input Closes the Loop

The design-to-code gap is closing from both sides. A Figma-like visual editor lets users select front-end elements visually and apply edits through Claude Code (from figma for claude code). Multimodal input -- recording video of a target UI and feeding it through Claude -- produces better results than text prompts because it captures interaction patterns, spacing, animation, and component relationships that are hard to articulate in words (from video to ui claude workflow).

For a vault-as-database system, multimodal input means the ingestion pipeline isn't limited to text. Video recordings of UI patterns, screenshots of design references, and audio recordings of brainstorming sessions can all flow through Claude's multimodal capabilities and land as structured markdown in your sources directory.

Building the System: A Prescriptive Playbook

Here is the exact sequence of steps to build a vault-as-database second brain that AI agents can reason over.

Phase 1: Foundation (Day 1)

Create the vault structure:

mkdir -p vault/{sources/{tweets,meetings,slack,captures},topics,plans,guides}
cd vault && git init

Write your CLAUDE.md. Start with three sections:

Keep it under 100 lines. You'll iterate on this as you discover what context matters most.

Create your first topic files. Pick 3-5 domains you actively think about. Create a topic file for each with just a title, an empty summary, and an empty insights section. These are the seeds your system will grow from.

Phase 2: Capture (Week 1)

Start capturing manually. Every time you encounter something worth remembering -- a tweet, an article, a conversation -- create a source file. Follow the standard format: YAML frontmatter, original content blockquoted, extracted insights as bullets with wikilinks.

Don't worry about automation yet. The manual capture phase teaches you what your source file format should look like. You'll notice patterns in what you capture, which tells you what your topic taxonomy should be.

Run your first synthesis. After capturing 10-15 sources, run through them and pull their insights into the matching topic files. Group by theme, not by source. Add inline citations: (from [Source Slug](/topics/source-slug)). This is the moment the system starts feeling alive -- topic files that read like briefing documents, not bookmarks.

Phase 3: Automation (Week 2-3)

Automate your highest-volume source. If you capture a lot of tweets, build a nightly ingestion pipeline. If you have a lot of meetings, connect Granola MCP. If you read a lot of documentation, set up a crawl-to-markdown scheduled task.

The automation should follow the enrichment pattern: raw content in, structured source files out, with Claude API doing the insight extraction and topic matching in between.

Add a memory layer. Create memory.md as an append-only session log. Add a line to CLAUDE.md: "When you complete work, log decisions and key observations to memory.md." After a week, review the log -- you'll find patterns that should become permanent vault entries.

Phase 4: Skills (Week 3-4)

Build your first operational skill. This should be the task you perform most often against your vault. Common first skills:

Each skill is a markdown file in .claude/skills/ that describes the task, the inputs, the expected output format, and any constraints. The skill file IS the instruction set. Building AI systems with Claude Code requires systems thinking, not software engineering -- you write detailed Markdown files describing desired behavior and Claude implements them (from jimprosser chief of staff claude).

Phase 5: Compounding (Month 2+)

Run regular consolidation. Weekly or monthly, scan all topic summaries and surface cross-cutting patterns. New cross-topic insights go into a consolidated patterns section on parent topic files or into a dedicated cross-cutting patterns file.

Expand your source types. Add Slack, meetings, dictation, GitHub repos. Each new source type enriches the vault from a different angle, increasing the chance of cross-pollination between domains.

Add the scratchpad. Create scratchpad.md for agent working notes. Agents read it at session start and update it as they work. Review it periodically to promote durable observations into CLAUDE.md or topic files.

Track growth. The Exo Brain compounding metric is useful: measure how many sessions before the agent knows your projects, your preferences, your voice. Watch for the inflection point where the agent's recommendations start anticipating your needs rather than just responding to them.

Architectural Principles: The Rules That Make It Work

After examining every implementation -- from CyrilXBT's JARVIS walkthrough to Exo Brain's self-maintaining vault to Knowledge Engine's skill-based operations -- a set of architectural principles emerges. These aren't suggestions. They're the rules that separate systems that compound from systems that decay.

1. The filesystem is the database. No external databases, no cloud APIs for storage, no proprietary formats. Everything is a markdown file in a Git repo. This ensures portability, version control, and agent access without integration overhead.

2. Context delivery beats model capability. A well-organized vault with a mid-tier model outperforms a messy vault with a frontier model. Invest in structure, not in bigger context windows.

3. Agents maintain, humans author. AI handles the grunt work -- indexing, linking, summarizing, formatting. Humans provide the judgment -- what's worth capturing, what the insights mean, what to do about them. The vault's knowledge layer stays human-authored.

4. Progressive disclosure manages token cost. CLAUDE.md loads every time (free). Topic summaries load on demand (cheap). Full source files load for deep retrieval (expensive). External API calls happen only when the vault can't answer (most expensive). Design your access patterns around this cost hierarchy.

5. Frontmatter is the query layer. YAML frontmatter fields -- type, date, topics, synthesized, tags -- are what make the vault queryable. An agent can filter sources by date range, find unsynthesized records, or pull all sources for a topic without reading full file contents.

6. Organize by theme, not by source. Topic files are briefing documents, not bibliographies. Related insights from different sources sit next to each other, with inline citations tracing each claim back to its origin.

7. Skills encode judgment, not just tasks. The most valuable skills transfer expertise -- how a designer thinks about spacing, how a researcher evaluates sources, how a writer structures arguments. Skills are taste, packaged as files.

8. Automation runs overnight. Ingestion pipelines, crawl jobs, synthesis passes -- all scheduled for off-hours. You wake up to a vault that's richer than when you went to sleep. The mental model for async AI work is not "grind during gaps" but "design your day differently because the work runs without you."

9. Everything is a file, and files are composable. A skill is a file. A topic is a file. A source is a file. A plan is a file. Because they're all the same primitive, they can reference each other, be processed by the same tools, and evolve with the same version control workflow.

10. Start small, compound daily. You don't need the full system on day one. CLAUDE.md and three topic files is a starting point. Add one source a day. Run synthesis weekly. In a month, you have a knowledge base that makes every AI interaction better. In six months, you have a competitive advantage that no one can copy because it's built from your accumulated thinking.

Sources Cited