Brain Graph (GraphRAG)

Use the brain graphrag command tree to query the second brain's entity graph — people and concepts as nodes, co-occurrence as edges, plus detected community clusters. This is a parallel retrieval surface to plain brain search; the underlying hybrid FTS+vector index is untouched.

It's live. GraphRAG is enabled (BRAIN_GRAPH_ENABLED=true), already built, and queryable from any working directory — brain loads its config from a fixed install path, not the cwd, so these commands work from any conversation without setup. Just run them. (If a command does error, see "If a command errors" at the bottom.)

For plain document lookup, voice writing, and per-doc Q&A, use consult-brain. For ingest, see ingest-brain; authoring brain-authoring; TODO/action-items brain-todo; health/maintenance brain-maintenance; daily digests, weekly reviews, timelines and link suggestions brain-proactivity. Boundary with brain-memory: that skill covers what you the agent remember about the user between sessions; this one queries the entity graph built from the user's own documents.

Graph vs. plain search — pick the right tool

Rule of thumb: flat answer about content → plain search; relationships, themes, or clustering → graph. When in doubt and a person is named, themes is the headline move. To answer "what's in the brain" rather than "what does the brain say", reach for entities / stats.

The five retrieval modes

brain graphrag search "<query>" --mode <mode>:

• auto (default) — heuristic router. A thematic query with a resolvable person → themes; a thematic query without a person → global; otherwise → local. Let it pick when intent is fuzzy.
• themes — the headline. "Themes in my conversations with X." Requires --person. Groups the person's co-occurrence subgraph into ranked theme groups (key entities + representative docs).
• global — community-level retrieval: RRF over the detected community clusters (FTS over community summaries ⊕ vector over summary embeddings). Needs communities build first. Best for "overall themes in my brain."
• local — entity-centric: resolve the seed entity, traverse its bounded CO_OCCURS neighbourhood, return the seed + reached entities and their docs.
• fuse — RRF-merge the local-graph doc leg with the vector/FTS hybrid leg into one ranked doc list. Explicit-only (auto never routes here). Note: fuse currently works on the default tenant only — don't pair it with a non-default --tenant.

Querying — CLI

Retrieval (search / themes / entity)

All support --json for clean parsing, plus --limit/-n, --depth, --tenant. Note --limit/-n means different things per command: on search/themes it caps documents returned (default 10); on entity it caps rendered neighbours (default 30, -n 0 = all) while documents stay at the graph default and --json is never capped.

# Themes in conversations with a person (the headline) — synthetic example
brain graphrag themes --person "Jane Doe" --json

# Same thing via search, explicit mode
brain graphrag search "leadership" --mode themes --person "Jane Doe" --json

# Overall themes / clusters across the brain
brain graphrag search "pricing strategy" --mode global --json
brain graphrag communities            # admin view of materialized clusters
brain graphrag communities list --json

# A single entity's neighbourhood ("what connects to X")
brain graphrag entity "Project Atlas" --json
brain graphrag search "Project Atlas" --mode local --depth 2 --json

# Best blended retrieval for one query (default tenant only)
brain graphrag search "team scaling tradeoffs" --mode fuse --json

# Let the router decide
brain graphrag search "how my hiring philosophy changed" --json

search flags:

Exploring the graph (entities / stats)

When the user asks what's in the brain (not what it says), enumerate or size up the graph directly. Both are read-only:

# What entities exist — enumerate orgs / people / projects / topics / tools
brain graphrag entities --json                       # all types, top 50 by doc_count
brain graphrag entities --type project --json        # just projects ("list all projects")
brain graphrag entities --type org --sort name --limit 0 --json   # every org, A–Z

# At-a-glance graph overview — size + composition + top entities
brain graphrag stats --json

entities flags — list the tenant's entities (admin view):

stats flags — at-a-glance overview:

Use stats first to gauge whether the graph is rich enough to answer a thematic question, and entities --type <t> to give the user a concrete inventory ("here are the projects in your brain: …").

Querying — MCP (prefer when calling programmatically)

The MCP tools mirror the CLI 1:1 (same params, same JSON wire shape). Prefer these over shelling out when you're already driving via tools:

• brain_graphrag_search(query, mode="auto", person=None, depth=None, limit=None, tenant=None, synthesize=False) — the five-mode retrieval surface
• brain_graphrag_themes(person, depth=None, limit=None, tenant=None, synthesize=False) — "themes with X"; person required
• brain_graphrag_entity(name, depth=None, limit=None, tenant=None) — one entity's neighbourhood. Here limit caps documents (unlike the CLI's -n, which caps rendered neighbours); the JSON is never neighbour-capped
• brain_graphrag_entities(entity_type=None, sort="docs", limit=50, tenant=None) — enumerate the graph's entities (what orgs/people/projects/topics/tools exist; "list all projects" → entity_type="project"); returns {tenant_id, count, entities:[…]}
• brain_graphrag_stats(tenant=None) — graph overview (how big / what's in it); returns {tenant_id, counts_by_type, total_entities, total_relationships, total_communities, top_entities:[…]}
• brain_graphrag_communities(tenant=None, limit=None) — list materialized clusters

Note: the MCP param is entity_type (not type) — type is a Python builtin. Everything else maps to the CLI flag names.

Admin (setup, not everyday querying):

• brain_graphrag_build(tenant=None, concepts=False, backfill=False, force=False, limit=None) — pass backfill=true (or force=true)
• brain_graphrag_refresh(tenant=None) — recompute a tenant's aggregate edges (no re-resolve)
• brain_graphrag_remove(document_ids, tenant=None) — remove DELETED documents' leftover graph state (the repair a vault-watcher shutdown message names); full UUIDs only, a live id refuses the batch, idempotent
• brain_graphrag_communities_build(...) — detect + summarize clusters
• brain_graphrag_communities_refresh(tenant=None, limit=None) — force re-detect + re-summarize past the dirty gate

Results come back in the graph_context_json shape: a session_id, mode, tenant_id, the ranked themes (themes mode) / entities (local mode) / communities (global mode), the document hits (docs), and an explanation. Raw Cypher is never accepted or returned — the backend injects the tenant and caps automatically. Never hand-write Cypher; always go through these commands/tools.

After retrieval — synthesize, grounded

• Use the graph result to organize the answer by theme / cluster / entity, not as a flat list — that's the whole point of the graph leg.
• For each theme, name the key entities and cite the representative docs by title (id-prefix when useful). To read the supporting material, prefer brain recall "<theme>" --budget 2000 --json — it packs passages to a hard token ceiling. Reserve brain show <id> --json for the 1–2 documents you need verbatim; a graph result can name a dozen docs, and showing each is unbounded — the whole body every time. For what that costs, and the cheapest command for each intent, see the cost-ordered table in consult-brain.
• For entities / stats, present an actual inventory — group by type, lead with the highest doc_count entities, and report the totals plainly.
• Stay grounded. Don't invent relationships the graph didn't surface. If the graph is thin for the topic, say so and offer a plain brain search --brief instead.
• Graph retrieval surfaces deliberately do not auto-log feedback the way brain search does — if the user reacts to a specific doc, you can still brain rate <id-prefix> useful|irrelevant.

Admin / setup (not everyday querying)

The graph is already built, so you rarely need these. Reach for them only when brain doctor shows drift/missing graph, or the user explicitly asks to (re)build. These are slow write operations:

brain graphrag build --backfill        # build the people graph from existing docs
brain graphrag build --backfill --concepts   # also extract topic/project/org concepts
brain graphrag build --force           # authoritative rebuild of the AGE mirror
brain graphrag refresh                 # recompute a tenant's aggregate edges
brain graphrag remove <doc-uuid>...    # repair: drop DELETED docs' leftover graph state (full UUIDs)
brain graphrag communities build       # detect + summarize clusters (needed for --mode global)
brain graphrag communities refresh     # force re-detect regardless of dirty gate

For everyday questions, stick to search / themes / entity / entities / stats / communities.

Owner configuration — brain owner

BRAIN_OWNER_PARTICIPANTS is the list of identifiers that mean the corpus owner — the user themself. Those identifiers are stripped from the derived-edge participant rules (R2 shared_participant, R3 same_day_participant) and filtered out of the People Hub roster. Without it the user is a participant in nearly every document they own, so they become a hub node connected to everything and the participant edges stop carrying signal.

Reach for this when the user asks why they show up in their own people list, why everything appears connected to everything, or asks to exclude themself (or an alias / old address of theirs) from the graph.

brain owner show                                  # active list, one entry per line
brain owner add jane.doe@example.com              # append one identifier
brain owner add "Jane Doe"                        # display names work too
brain owner remove jane.doe@example.com           # drop one identifier
brain owner set "Jane Doe,jane.doe@example.com"   # replace the whole list

Gotchas worth knowing before you run one:

• The subcommand is remove, not rm. brain owner rm is a usage error.
• There is no brain owner list — show is the read command.
• A real change only prints a hint; it does not rebuild anything. Existing derived_links rows and People Hub pages were computed under the old list. To make the change take effect, run brain vault relink-derived — a full-corpus rebuild, so hand off to brain-maintenance and confirm with the user rather than firing it off mid-conversation.
• brain owner set / add / remove edit .env. Treat them as configuration changes: state what you are about to write and confirm first. brain owner show is read-only and always safe.

If a command errors

The graph is enabled and built, so these are fallbacks, not preconditions — only relevant if a brain graphrag command actually fails:

• "Apache AGE is not available" — the running Postgres isn't the custom Apache AGE image. The graph commands need it; plain brain search (consult-brain) still works regardless.
• Empty/thin results or "graph not built" — the tenant's graph may be missing or stale. Run brain doctor (it reports an age line, a graph drift line for relational ↔ AGE parity, and a communities line — all soft checks). Rebuild with brain graphrag build --backfill (and communities build for --mode global) only if the user wants it.
• --mode global returns nothing — communities haven't been built; run brain graphrag communities build first, or use another mode.

When the graph can't answer, fall back to consult-brain for a plain-search answer rather than guessing — and tell the user the graph leg was unavailable.

When NOT to use the graph

• Plain "find docs about X", a quote, a single fact, or voice writing → consult-brain.
• The graph errors and the user doesn't want to rebuild → use consult-brain for a plain-search answer and mention the graph leg was unavailable.
• Generic technical/coding/news questions → not what the brain is for at all.