claude-mega-brain

Loads the knowledge. Skips the search.

100% accuracy · 0 tool calls · −66% tokens vs Obsidian+MCP

Real agentic sessions. Benchmark →

Install

/plugin marketplace add guhcostan/claude-mega-brain
/plugin install mega-brain@mega-brain

Then in any project:

/mega-brain:init

Start a new session — the knowledge base loads automatically.

The problem

Without claude-mega-brain, Claude guesses from training data:

User: What column stores the order total?

Claude (no context): Typically total_amount (DECIMAL) or amount (FLOAT)...
# Wrong — this project uses total_cents (INT64)

With claude-mega-brain, the exact schema is injected at SessionStart:

<mega-brain>
Knowledge: 4 documented concepts found in project

  docs/orders.md     [BigQuery Table] — total_cents INT64, status STRING(pending/confirmed/shipped/done)
  docs/customers.md  [BigQuery Table] — customer_id STRING, email STRING, country STRING
  docs/wau.md        [Metric]         — COUNT(DISTINCT user_id) WHERE session_date >= CURRENT_DATE-7
  docs/net_revenue.md [Metric]        — SUM(total_cents - refund_cents)/100 WHERE status='done'
</mega-brain>

User: What column stores the order total?

Claude: total_cents (INT64) — from docs/orders.md
# Correct. 0 tool calls. First turn.

Benchmark

10 questions with project-specific values unknowable from training data. Real agentic sessions — not simulated.

† raw and Obsidian+MCP reach 100% agentic accuracy by using tool calls to explore the project — spending 3–4× more tokens and time. Without tools, they drop to 50% and 13%.

CLAUDE.md (raw files) matches mega-brain on accuracy but uses 25% more tokens and is 25% slower. mega-brain's compressed OKF index is smaller and faster — the gap widens as knowledge bases grow.

Full results · Reproduce

How it works

At SessionStart, a hook scans the entire project for any .md file with type: in its YAML frontmatter and injects a compact index:

<mega-brain>
Knowledge: 8 documented concepts found in project

Recent (log.md):
  2026-06-29 — added customers table

  index.md            [Index]         — Central reference for all sales data
  docs/orders.md      [BigQuery Table] — One row per completed order
  docs/customers.md   [BigQuery Table] — Customer profiles
  docs/wau.md         [Metric]         — Weekly active users
  ...
</mega-brain>

No dedicated folder needed — documents can live anywhere in the project. When Claude reads an OKF file, linked concepts surface automatically via PostToolUse.

Zero overhead when not in use — if no documented concepts are found, the hook exits in <5ms.

How it compares

* CLAUDE.md matches mega-brain accuracy but uses 25% more tokens and is 25% slower — raw file dump vs compressed structured index.

OKF Format

Any .md file in the project with type: in its YAML frontmatter is automatically picked up. No dedicated folder needed.

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-06-29T00:00:00Z
---

# Schema
| Column      | Type      | Description              |
|-------------|-----------|--------------------------|
| order_id    | STRING    | Globally unique order ID |
| customer_id | STRING    | FK → customers           |
| total_cents | INT64     | Order total in cents     |
| status      | STRING    | pending/confirmed/shipped/done |

# Joins
Joined with [customers](https://github.com/guhcostan/claude-mega-brain/blob/main/customers.md) on `customer_id`.

Reserved files

Common types

BigQuery Table · BigQuery Dataset · Table · Metric · API · Runbook · Concept · Service · Pipeline

Types are freeform — add your own.

Usage

Start from scratch

/mega-brain:init

Creates index.md and log.md anywhere you want. Start a new session — context injects automatically.

Migrate existing docs

/mega-brain:migrate

Scans openapi.yaml, schema.prisma, schema.sql, docs/, README sections and adds type: frontmatter to generate OKF concepts.

Add a single concept

/mega-brain:ingest

Document a specific table, metric, API, or service. Saves the file wherever makes sense for your project structure.

Installation

Claude Code

/plugin marketplace add guhcostan/claude-mega-brain
/plugin install mega-brain@mega-brain

Local development

claude plugin install /path/to/claude-mega-brain

Config (.mega-brain.json)

Optional per-project overrides:

{
  "dir": "knowledge",
  "maxConcepts": 100,
  "priorityTypes": ["Metric", "BigQuery Table"]
}

FAQ

Does it slow down every session? No. If no OKF directory exists, the hook exits in <5ms with no context injected.

Can I use it with an existing wiki or docs folder? Add type: YAML frontmatter to any Markdown file and drop it in your OKF dir. Done.

What if I have 500 concepts? Set maxConcepts in .mega-brain.json. The index stays compact; index.md holds the full map.

References

• Open Knowledge Format — Google Cloud
• LLM Wiki pattern — Andrej Karpathy
• Mega Brain — Thiago Finch — the meme this plugin is named after

Star History

License

MIT — The shortest license that works.