minutes-graph

# /minutes-graph

Cross-meeting entity graph that lets you query your meeting history as structured data — **people and topics** out of the box, with companies and products as an opt-in deep-extraction path.

Minutes already exposes `minutes people`, `minutes person`, and `minutes insights` for first-class entity queries. **Graph layers on top of those** to answer questions the CLI can't:

- "What's the co-occurrence between Sarah and pricing?"
- "First time the term 'X' appears in my history"
- "Frequency trend for topic Y over the last 6 months"
- "Who's been mentioned in the same meetings as Sarah?"
- "What topics came up when we talked about hiring?"

Defer to the existing CLI when it suffices. Use graph for the queries the CLI can't answer. Anything about companies or products requires opt-in deep extraction (see Phase 1).

## How it works

Graph has two modes: **build** (creates the index) and **query** (uses it).

### Phase 0: Determine the user's intent

If the user explicitly says "build" / "rebuild" / "refresh the graph" → Phase 1 (build mode).

Otherwise → Phase 2 (query mode). Query mode auto-builds the index if it doesn't exist, and incrementally refreshes it if new meetings exist since the last build.

**Detect company/product queries upfront.** If the user's question mentions a specific company name, product, brand, or anything that wouldn't be in standard meeting frontmatter (e.g., "Stripe", "Notion", "the deal with Acme"), tell them upfront — before any building happens — that this needs deep extraction:

> "That query is about a company/product, which isn't in standard meeting frontmatter. I'd need to deep-scan transcripts (~<estimate> seconds for <N> meetings) to answer. Continue, or rephrase to use topics/people that are already indexed?"

This avoids the worst flow: build → discover the data isn't there → ask user → rebuild.

### Phase 1: Build the index via the bundled helper script

The index lives at `~/.minutes/graph/index.json`. **Use the bundled `graph_build.py` script — do not try to walk meeting files or parse YAML frontmatter in-context.** The script is deterministic, fast, atomic, and handles all the edge cases (incremental rebuilds, garbage filtering, name disambiguation, augmentation from `minutes people --json`).

**Always warn before building**, even on the auto-trigger path. Users hate commands that hang silently more than they hate one-line confirmations:

> "Building entity graph from <N> meetings. The frontmatter-only path is fast (a few seconds for hundreds of meetings). Continue? (Ctrl+C to abort)"

To get the meeting count for the warning, use Glob on the meetings dir from `minutes paths`.

**Run the script:**

```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/minutes-graph/scripts/graph_build.py" --incremental
```

Defaults:
- `--meetings-dir` defaults to `output_dir` from `minutes paths`
- `--output` defaults to `~/.minutes/graph/index.json`
- `--incremental` skips the rebuild entirely if no meeting files have been modified since the last build (the common case after the first build)

The script prints a one-line summary JSON to stdout:

```json
{"status": "ok", "meeting_count": 142, "person_count": 12, "topic_count": 38, "output": "/Users/.../index.json"}
```

Or `{"status": "fresh", ...}` if `--incremental` found nothing to rebuild.

**What the script does, in order:**

1. Walks every meeting file in the meetings directory
2. Parses the YAML frontmatter using a small line-based extractor (no PyYAML dep)
3. Extracts: `date`, `attendees` (display names), `people` (wikilink slugs), `tags`, and `decisions[].topic` — all the entity-relevant fields the real meeting schema actually has
4. Filters out `none`/`null`/`~` topic values that show up in some malformed meetings
5. When `attendees` and `people` have the same length, zips them positionally to map each slug to its display name (gives `mat` → `Mat S.`, etc.)
6. Builds people-people, people-topic, and topic-topic co-occurrence within each meeting
7. Runs `minutes people --json` and merges its `top_topics`, `open_commitments`, `score`, `losing_touch` fields into the people entries it already built
8. Filters diarization noise (`unknown-speaker`, `speaker-3`, etc.) out of the final people index
9. Picks a canonical display name for each person using a "looks human" heuristic (capital letter + space wins; lowercase slug-style loses)
10. Atomically writes the index to JSON (temp file + rename)

**What's NOT in the default build**: companies and products. Some real meetings **do** have an `entities:` block in their frontmatter — the current schema looks like:

```yaml
entities:
  people:
    - slug: speaker-0
      label: Speaker 0
      aliases: [speaker 0]
  projects:
    - slug: codex-native-call-attribution
      label: Codex Native Call Attribution
```

But the schema is **inconsistent across the corpus** — many meetings have no `entities:` block, and when it's present its structure varies (some meetings have `people`, some add `projects`, there's no guarantee of `companies` or `products`). `graph_build.py` intentionally uses a narrower set of fields (`attendees`, `people` slugs, `tags`, `decisions[].topic`) that are more consistently populated across the full meeting corpus, so the default build is predictable.

If you want the entities block data in the graph, modify `graph_build.py` to also parse it — but be ready to handle variant schemas across meetings. For on-demand company/product queries that go beyond what frontmatter has, use the opt-in deep extraction path below.

Two paths from here:

1. **Default path (the script above)**: people, topics, dates. Fast, deterministic, runs on every install with zero deps.

2. **Opt-in deep extraction**: only if Phase 0 detected a company/product query and the user confirmed, run a one-time LLM pass over each meeting's transcript section to extract company and product names. Cache results in the index keyed by meeting filename. Every subsequent query reu