gbrain-import

Extract structured knowledge from Gmail and ChatGPT archives into GBrain or Obsidian.

Andrej Karpathy's been talking about personal AI and the idea of an AI that knows you — your history, your contacts, your thinking. That requires real data: years of email and conversations, not just what you choose to curate.

gbrain-import turns your archive exports into a structured knowledge graph. It extracts people, companies, projects, ideas, and concepts — with timeline events, confidence scores, and provenance — and writes them as clean markdown pages ready for semantic search.

Install

# Bun only (uses bun:sqlite)
bun add --global gbrain-import

Or run directly without installing:

bunx gbrain-import --input ~/Downloads/Mail.mbox

Quick start

Gmail (.mbox)

# Stage 1: Index your archive (fast, no API calls)
bunx gbrain-import --input ~/Downloads/Mail.mbox

# This prints extraction batches as JSON to stdout.
# An agent stores results via the MCP tool (see below).

# Or use --api to extract directly with Anthropic:
bunx gbrain-import --input ~/Downloads/Mail.mbox --api

ChatGPT export

# Point at the ChatGPT export directory (contains conversations-*.json)
bunx gbrain-import --input ~/Downloads/chatgpt-export --api

Write to Obsidian

bunx gbrain-import --input ~/Downloads/Mail.mbox --api \
  --adapter obsidian --vault ~/Documents/Brain

How it works

Three stages:

1. Index — parse the archive into a local SQLite database. No API calls. Fast.
2. Extract — LLM reads batches of threads/conversations and extracts structured entities.
3. Materialize — resolve entities, apply quality gate, write markdown pages.

Two extraction modes:

• Agent-driven (default) — print batch prompts to stdout. Your agent (Claude Code, OpenClaw, etc.) reads them and stores results via the MCP store_batch_results tool. Resumable: re-run any batch without double-counting.
• --api mode — calls Anthropic directly via SDK. Default 5 concurrent. --model and --concurrency flags.

MCP server

gbrain-import exposes a one-tool MCP server for agent-driven extraction:

# Start the server pointing at an existing workspace
bunx gbrain-import --mcp --workspace ~/.gbrain-import/my-workspace --connector gmail

Tool: store_batch_results

{
  "batchId": "42",
  "result": {
    "people": [...],
    "companies": [...],
    "projects": [...],
    "events": [...]
  }
}

The workspace is created automatically on first --input run. Find it at:

ls ~/.gbrain-import/

Output adapters

GBrain (default)

Writes pages to a running GBrain instance via its engine API. Requires gbrain >= 0.19.0 as a peer dep.

bunx gbrain-import --input ~/Downloads/Mail.mbox --api --adapter gbrain

Obsidian

Writes .md files directly to an Obsidian vault. No GBrain required.

bunx gbrain-import --input ~/Downloads/Mail.mbox --api \
  --adapter obsidian --vault ~/Documents/Brain

Pages land at <vault>/<connector>/<directory>/<slug>.md — e.g. Brain/gmail/people/alice-example.md. The connector-name prefix prevents collisions when importing from multiple sources.

Quality gate

Only entities that appear in 3+ threads and have 2+ extracted events become pages. Everything else is captured in the database for future use but not written. This keeps noise out.

Resumability

Every extraction batch is tracked by batch_id in the workspace database. storeBatchResults is idempotent: re-submitting a batch deletes the prior results before inserting new ones. You can safely re-run failed batches or retry the whole pipeline.

Stranded in_progress batches (older than 30 minutes) are reset to failed automatically on startup.

Options

--input <path>         Archive path (required)
--connector <name>     gmail | chatgpt (auto-detected)
--adapter <name>       gbrain | obsidian (default: gbrain)
--vault <path>         Obsidian vault path (required for obsidian adapter)
--account <name>       Account label for metadata
--workspace <dir>      SQLite workspace directory
--api                  Use Anthropic API directly
--model <model>        Model for --api mode (default: claude-haiku-4-5-20251001)
--concurrency <n>      Concurrent API calls (default: 5)
--dry-run              Preview without writing
--quiet                Suppress progress output
--json                 JSON summary output
--mcp                  Start MCP stdio server

Requirements

• Bun >= 1.1.0
• GBrain >= 0.19.0 (optional, only needed for --adapter gbrain)
• ANTHROPIC_API_KEY in env (only needed for --api mode)