maia

---

Maia is named for the midwife-goddess behind Socrates' maieutics — the art of drawing understanding out of someone rather than pouring it in. That is the whole idea: Maia doesn't hand you a pile of nodes, it builds a map and leads you through until the understanding is yours.

Why

You want to understand something — Stoicism, causal inference, the Daodejing, a stack of papers you've been meaning to read. The usual options:

• Search gives you ten tabs and no shape.
• A summary flattens a system into a paragraph and loses every connection.
• A raw knowledge graph gives you a pretty hairball you can't actually learn from.

Maia gives you the thing in between: a map that teaches. Concepts you can see arranged by importance, read in depth, and walk in the right order — from bedrock ideas up to the ones that depend on them.

What makes it different

Most "knowledge graph" tools stop at impressive. Maia is built around three convictions that make it teach:

🧭 Graphs that teach, not impress	Every node is a four-part archive — what it is, why it matters, its place in the system, and a key quotation — not a one-line label. A built-in guided tour orders concepts from foundations upward, like a teacher walking you through.
🌏 Two languages, two worlds	Following Wittgenstein — "the limits of my language are the limits of my world" — the English and Chinese graphs are extracted independently, then aligned. Switching language switches worldview, not just labels.
🎨 Taste, applied per subject	A Daodejing map and a quantum-mechanics map should not look the same. Maia reads a subject's character (classical↔modern, eastern↔western, intuitive↔rational…) and designs a visual identity to fit — ink-wash, blueprint, editorial — within a hard floor of legibility.
📄 Feeds on your own knowledge	Beyond web research, point Maia at your own documents (.md .txt .pdf .docx). Every concept traces back to the exact passage it came from, and ideas that never share a page get connected across your library.
🪶 One file, double-click to open	Export the whole thing as a single self-contained .html — no server, no build, no network. Fullscreen-adaptive for presentation. Share it like a PDF.
📐 An evaluation loop, not vibes	A precision/recall harness scores extraction against a gold set, so you can change a prompt and watch the F1 move — the discipline that turns a demo into a tool.

Quickstart

git clone https://github.com/bitqs/maia && cd maia/maia-plugin/backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-...

Map a subject (Maia researches it):

python build.py --expert "Laozi Daodejing" --domain "core concepts" --lang en
python export_html.py ../output/graph.json ../output/theme.json daodejing.html
open daodejing.html

Map your own documents (Maia reads them):

python build_corpus.py --paths ./notes ./book.pdf --title "My Reading on Stoicism"
python export_html.py ../output/graph.json ../output/theme.json mine.html

Don't specify a depth and Maia decides one from the subject — a single classic text gets a shallow, complete map; a sprawling field gets a deeper, more aggressively filtered one.

How it works

  subject  or  your documents
        │
        ▼
  ┌─────────────────────────────────────────────┐
  │  1  seed / read     find pillar concepts      │
  │  2  expand          per-language worlds,       │
  │                     low-relevance concepts     │
  │                     explored by isolated       │
  │                     sub-agents (kept out of    │
  │                     the main context)          │
  │  3  align + resolve  merge synonyms across      │
  │                     EN/ZH using descriptions   │
  │  4  enrich          hubs, difficulty, tour     │
  │  5  profile         the four-part archive      │
  │  6  theme           a visual identity for the  │
  │                     subject's character        │
  └─────────────────────────────────────────────┘
        │
        ▼
   graph.json  ──►  self-contained .html  ──►  evaluation/

A few design choices worth calling out: