Today the Tavern has a link graph, not a knowledge graph. A Reference row joins two articles when one wiki-links the other (BL-055, ADR-0004). It has no relationship type and only records links someone typed by hand. MCP search is a plain substring match on names and content, with no ranking, no aliases, no snippets and no tolerance for misspelling, so “everything that mentions Highpoint” depends on the writer having typed a link.
The good part: ask about an entity and get everything that mentions it, fast, ranked, with the surrounding sentence, even if the name was spelled wrongly. Two things, one pipeline. The index finds text. The graph is the mentions it detects, filled in automatically instead of by hand.
Build first (the mention index)
- Search column. A search_text column per article (name and plain content, with DM notes in a separate column that is DM only), tsvector and a GIN index, refreshed on save. Ranked results with snippets. “Everything mentioning X” is answered at query time, so no mention table is needed at first.
- Aliases. A text array per article, authored on the article and folded into the same query.
- Name changes. A job fires when an article is created, renamed or its aliases change, and rescans the world for the new name. Unlinked mentions come back as suggested links, feeding the same fan-out as /txt-article-build.
- Backfill. One rake task for existing articles. Moments and recaps use the same save callback if they are counted as sources.
- Fuzzy matching. pg_trgm for typos (“Tsass Zam” finds “Szass Tam”), unaccent for “Faerun” and “Faerûn”, dmetaphone for speech-to-text garbles. It runs on the query against names and aliases only, which is cheap. Low-confidence matches return as “did you mean”, never as a silent merge. A confirmed misspelling is added to the article’s aliases so it is exact next time. Short names (Danny, Orla) need the threshold tuned against real articles before it is trusted.
Add when it earns it
- Mention edges and two-hop walks. Store “A mentions B” in an article_mentions table, filled by the same job, then walk it with a depth-capped recursive query: what is within two steps of Szass Tam, ranked by distance, with the path shown (recap, Azir, Szass Tam). Needed once counts or multi-hop questions are asked often, or at thousands of articles per world.
- Relationship labels on a Reference (rules, lives in, allied with), only when relationship questions are being asked.
- A world-level graph page, reusing the dagre layout work (ADR-0072, ADR-0076, ADR-0079).
Rules for everything. Privacy first: private articles, DM notes and anything hidden from a campaign never appear in a player’s results, counts, snippets, edges, suggested links or as a stepping stone in a multi-hop path (same rule as BL-123). MCP parity: search gains ranking, snippets and fuzzy, plus list mentions and get neighbourhood, with docs. Seeds need linked and unlinked mentions, a misspelling, a short name and a private article. Handbook entry for the search behaviour. Needs an ADR for the index design before building.
Before building, verify how article text is stored. If it is rich text in a separate table, a generated column cannot span it, so the search_text column is refreshed by callback or trigger. Then run a read-only spike: fuzzy thresholds against the real Hightaeria and Thornwick articles.
Open: whether Moments and recaps count as sources, and how aliases are authored.