mega-brain

---

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.

metric	no context	Obsidian+MCP	CLAUDE.md (raw files)	claude-mega-brain
accuracy (no tools)	50%	13%	100%	100%
accuracy (agentic)	100%†	100%†	100%	100%
tool calls avg	1.1	0.9	0.1	0
tokens avg	61,521	49,186	20,624	16,547
latency avg ms	10,267	10,986	5,494	4,384

† 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

tool	auto-inject	schema enforcement	tool calls to answer	accuracy (no tools)
claude-mega-brain	✓ SessionStart hook	required (type:)	0	100%
CLAUDE.md + additionalDirectories	manual setup	none	0	100%*
Obsidian + MCP	✗ manual	none	1–3	13%
Notion	✗ manual	proprietary	N/A	—
Logseq	✗ plugin-based	none	N/A	—
mem.ai	✗ none	none	N/A	—

* 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/2cffe5f6e1a22ccb7f3fb545b2cbff7ed82b0a05/customers.md) on `customer_id`.

Reserved files

File	Purpose
index.md (with type: Index)	Knowledge map — Claude reads this first
log.md (with type: Log)	Append-only changelog — last 3 entries injected at session start

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"]
}

Field	Default	Description
dir	(none)	Limit scanning to this subdirectory (relative to project root). When unset, the entire project is scanned.
maxConcepts	60	Max concepts in injected index
priorityTypes	[]	Types shown at top of index
exclude	[]	Additional dirs to skip when scanning

---

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

[

](https://www.star-history.com/?type=date&repos=guhcostan%2Fclaude-mega-brain)

---

License

MIT — The shortest license that works.