Second Brain

The Problem

Your work is scattered across a dozen tools, and none of them talk to each other.

Tasks live in Jira. Notes live in Notion (or scattered .md files). Meeting action items are in your email. Time tracking is in a spreadsheet. The code is in GitHub. And your actual knowledge — the decisions you made, the patterns you noticed, the context behind why you built something a certain way — lives nowhere. It’s in your head, slowly decaying.

Then performance review season arrives and you can’t remember what you shipped in Q2. Or you switch laptops and lose six months of context. Or you onboard an AI coding agent and it has zero visibility into your work history, your priorities, or what you’ve already tried.

The real problem isn’t any single tool — it’s that your professional knowledge has no home.

Three things make this worse:

1. Work fragments across projects — You juggle 3-5 repos at any time. Task tracking is per-repo, but your brain isn’t. You need a unified view.
2. Context doesn’t survive machine switches — Your laptop dies, you spin up a cloud dev environment, or you just move to the couch. Your work context stays behind.
3. AI agents are blind — Claude Code, Cursor, Copilot — they can see your current repo, but they have no idea what you worked on yesterday, what’s blocked, or what decisions you’ve already made.

Second Brain solves all three.

How It Works

Second Brain is a global, persistent knowledge base that lives at ~/.second-brain/ and follows you everywhere. It’s a Git-backed data directory with a CLI, an MCP server, and 27 slash commands — all pointing at the same SQLite index over human-readable Markdown files.

The Data Model

Everything is a first-class entity with relationships:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Projects   │────▶│    Tasks    │────▶│  Work Logs  │
│              │     │             │     │  (daily)    │
│  • status    │     │  • priority │     │  • entries  │
│  • tags      │     │  • time    │     │  • minutes  │
│  • jira key  │     │  • issue   │     │  • per-task │
└──────┬───────┘     └──────┬──────┘     └─────────────┘
       │                    │
       ▼                    ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    Notes     │     │   Journal   │     │ Transcripts │
│              │     │             │     │             │
│  • markdown  │     │  • freeform │     │  • raw text │
│  • linked    │     │  • daily    │     │  • summary  │
│  • encrypted │     │  • tagged   │     │  • actions  │
└─────────────┘     └─────────────┘     └─────────────┘

Every entity links back to projects and tasks. Notes reference the decision they document. Work log entries track time against specific tasks. Transcripts extract action items that become tasks. Nothing exists in isolation.

The Hybrid Storage Engine

This is the core architectural insight. You need two things that are normally in tension:

1. Fast queries — “Show me all blocked tasks across all projects, sorted by priority”
2. Human-readable files — Markdown that works in any editor, diffs cleanly in Git, and survives any tool

Second Brain does both with a bi-directional sync between SQLite and Markdown:

class StorageIndexer:
    """Sync between markdown files and SQLite database."""

    def sync_project_to_db(self, slug: str) -> Optional[Project]:
        """Read project markdown → update SQLite index."""
        project_data = self.storage.read_project_file(slug)
        metadata = project_data["metadata"]  # YAML frontmatter
        # Upsert into SQLite...

    def sync_project_to_markdown(self, project: Project) -> bool:
        """Read SQLite record → update markdown file."""
        # Write frontmatter + body back to .md file...

SQLite handles the fast stuff: FTS5 full-text search, relational queries across entities, index lookups. Markdown handles the human stuff: reading in VS Code, diffing in GitHub, editing by hand. The StorageIndexer keeps them in sync — write to either side and the other updates.

If the database gets corrupted? Rebuild it from the Markdown files. They’re the source of truth.

AI Agent Integration

This is where it gets interesting. Second Brain exposes 30+ MCP tools that let AI agents read and write to your knowledge base:

# MCP server with FastMCP
mcp = FastMCP("second-brain")

# Tools for every entity type
create_work_log_entry_tool    # Log what you're working on
get_tasks_tool                # Query tasks by status/project/priority
create_note_tool              # Capture decisions and context
search_all_content_tool       # Full-text search across everything
generate_report_tool          # Summarize work for any date range
get_ready_work_tool           # Find unblocked issues to work on next

When you add Second Brain to Claude Code’s MCP config, your AI agent suddenly has full context on your work:

• “What was I working on Friday?” → Queries work logs
• “What’s blocking the auth refactor?” → Checks dependencies via Beads
• “Write my weekly status update” → Generates a report from the last 7 days of logs, completed tasks, and project status changes
• “What did we decide about the caching strategy?” → Full-text search across notes

It also ships with 27 slash commands for common workflows:

Dependency Tracking

For complex work that spans multiple tasks and has ordering constraints, Second Brain integrates with Beads — a Git-backed issue tracker with a real dependency graph:

# Create an epic with child issues
sb epic create "Auth Refactor" --project auth-service

# Add issues with dependencies
sb issue create "Migrate to JWT" --epic auth-refactor
sb issue create "Update middleware" --blocks-on migrate-to-jwt
sb issue create "Write integration tests" --blocks-on update-middleware

# Ask: what can I work on right now?
sb ready
# → "Migrate to JWT" (no blockers, high priority)

The dependency graph supports four relationship types:

• blocks — Sequential ordering (A must finish before B starts)
• related — Loose coupling (changes to A might affect B)
• parent-child — Hierarchical (epic → issues)
• discovered-from — Ad-hoc discovery (found while working on something else)

The ready command walks the graph and finds issues with zero open blockers, sorted by priority. No more manually scanning a board to figure out what you can actually start.

Architecture

┌───────────────────────────────────────────────────────────────────────┐
│                          USER INTERFACES                              │
│                                                                       │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌───────────────┐  │
│  │  CLI (sb)  │  │ MCP Server │  │   Slash    │  │ Future Web UI │  │
│  │   Click    │  │  FastMCP   │  │  Commands  │  │               │  │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └───────┬───────┘  │
│        └───────────────┴───────────────┴──────────────────┘          │
└────────────────────────────────┬──────────────────────────────────────┘
                                 │
                                 ▼
┌───────────────────────────────────────────────────────────────────────┐
│                       APPLICATION LAYER                               │
│                                                                       │
│  ProjectOps · TaskOps · WorkLogOps · NoteOps · ReportGenerator       │
│  TranscriptOps · JournalOps · FTSOps · EpicOps                      │
│                                                                       │
└────────────────────────────────┬──────────────────────────────────────┘
                                 │
                                 ▼
┌───────────────────────────────────────────────────────────────────────┐
│                         STORAGE LAYER                                 │
│                                                                       │
│  ┌─────────────────────────────┐  ┌────────────────────────────────┐ │
│  │    Hybrid Storage Indexer   │  │     Beads Integration          │ │
│  │                             │  │                                │ │
│  │  SQLite + FTS5 ◄──► Markdown│  │  Epics · Issues · Dependencies│ │
│  │  (fast queries)  (Git-friendly) │  │  Ready Work · Graph Queries  │ │
│  └─────────────────────────────┘  └────────────────────────────────┘ │
│                                                                       │
└────────────────────────────────┬──────────────────────────────────────┘
                                 │
                                 ▼
┌───────────────────────────────────────────────────────────────────────┐
│                    PERSISTENCE & SYNC                                 │
│                                                                       │
│            ~/.second-brain/ (private Git repository)                  │
│     Versioned · Syncs via GitHub · Available on all machines         │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

Why These Technologies

SQLite + FTS5 for the Index

The database needs to be zero-config, portable, and fast. SQLite checks all three:

• No server to run — it’s a single file (index.db) inside your data directory
• Travels with the Git repo — clone on a new machine and the index is there
• FTS5 virtual tables give you full-text search without Elasticsearch:

CREATE VIRTUAL TABLE content_fts USING fts5(
    content_type,   -- 'note', 'task', 'work_log', etc.
    content_id,
    content,        -- The actual text
    tags
);

-- Find everything mentioning "caching strategy"
SELECT * FROM content_fts WHERE content MATCH 'caching strategy';

Markdown for Storage

Every other “knowledge base” tool locks your data into a proprietary format. When the tool dies (or you switch), you lose everything.

Second Brain stores everything as Markdown with YAML frontmatter:

---
name: Auth Service Refactor
status: active
tags: [security, backend, q1-priority]
jira_project_key: AUTH
created: 2026-01-15
---

# Auth Service Refactor

Migrating from session-based auth to JWT tokens...

This means:

• Read it in any editor — VS Code, Obsidian, vim, GitHub’s web UI
• Git diffs make sense — Reviewing changes to your knowledge base is just reading Markdown diffs
• Survives any tool — Second Brain could disappear tomorrow and your data is fine

FastMCP for Agent Access

The MCP (Model Context Protocol) server uses FastMCP to expose tools with proper schemas that AI agents understand natively. No API wrappers, no prompt engineering — the agent calls create_work_log_entry like any other function:

@mcp.tool()
def create_work_log_entry(
    entry_text: str,
    project_slug: Optional[str] = None,
    task_id: Optional[int] = None,
    time_spent_minutes: Optional[int] = None,
) -> str:
    """Log a work entry. Optionally link to a project and/or task."""

Git for Sync

No cloud service, no account, no subscription. Your data syncs through a private GitHub repo:

cd ~/.second-brain
git add -A && git commit -m "daily sync" && git push

On a new machine: git clone and you’re back. Full history, full recovery, full ownership.

What Makes This Different

The fundamental difference: other tools are designed for teams organizing one project. Second Brain is designed for one person navigating all their projects — and making that knowledge available to AI.

Project Structure

second-brain/
├── src/second_brain/
│   ├── cli.py                 # Click CLI (sb command)
│   ├── mcp_server.py          # FastMCP server (30+ tools)
│   ├── config.py              # Global config management
│   ├── db/
│   │   ├── models.py          # SQLAlchemy 2.0 models
│   │   └── operations.py      # CRUD operations (~600 LOC)
│   ├── storage/
│   │   ├── indexer.py         # Bi-directional SQLite ↔ Markdown sync
│   │   └── markdown.py        # Frontmatter + Markdown I/O
│   ├── tools/                 # MCP tool implementations
│   │   ├── work_log.py        # Daily logging
│   │   ├── projects.py        # Project + task CRUD
│   │   ├── epics.py           # Beads integration
│   │   ├── notes.py           # Note management + search
│   │   ├── reports.py         # Report generation
│   │   ├── transcripts.py     # Meeting transcript processing
│   │   └── journal.py         # Freeform daily journal
│   ├── integrations/
│   │   ├── beads_integration.py   # Dependency graph client
│   │   └── jira_client.py         # Optional Jira sync
│   ├── crypto/                # Encryption for sensitive notes
│   └── validation/            # Data validation layer
│
├── examples/commands/         # 27 slash commands
├── docs/                      # Architecture, workflows, API reference
└── pyproject.toml             # Python 3.10+, uv

Tech Stack

Try It

# Install
pip install second-brain
# or
uv pip install second-brain

# Initialize (global, recommended)
sb init --global

# Log some work
sb log "Implemented JWT auth for the API gateway" --project auth-service --minutes 90

# Check what you've done today
sb today

# Generate a weekly report
sb report --last 7d

# Start the MCP server (for AI agents)
sb mcp serve

Add to Claude Code’s MCP config:

{
  "mcpServers": {
    "second-brain": {
      "command": "sb",
      "args": ["mcp", "serve"]
    }
  }
}

Now your AI agent knows everything you’ve been working on.

Links

• Repository: github.com/Sean-Koval/second-brain