Live Context Graph
What is in the graph, how it is stored on Lakebase, how agents search it when picking up a spec — and what is still missing before that journey is real end-to-end.
00 Verdict
The graph is a thin, typed index over work + code + docs + infra + occupancy, hosted in the same Lakebase database as Ticketron tickets, queried through the same MCP token. It returns keys and one-line facts; bodies stay in Git behind uri.
scripts/seed_graph.py --via-mcp):
ticketron 260 files / 113 edges · automaton 228 files · dmx-marketer 454 files.
find_nodes returns real file/spec hits. Ticket→file get_slice neighborhoods still need implements/documents edges from judgment or ship (E1) — the inventory exists; the “one hop from ticket” walk is incomplete until those edges land.
01 What it is (and is not)
Primary win: fewer tokens and tool calls for planner / lead-engineer / orchestrator. Secondary: lineage (“what did this feature touch?”).
It is
- Index-only MCP surface on Path B-hybrid (DB is system of record)
- Closed ontology from migration
0005— adding a kind means deleting one - Fact layer (deterministic indexer + pipeline) + judgment layer (summaries / legacy maps)
- Same tenant RLS boundary as tickets
It is not
- A dump of file or spec bodies
- Markdown
codebase-graph.mdas the queryable SoR (seed corpus only) - Neo4j / BM25 / vector RAG (BM25 may enrich
find_nodeslater) - A second ticketing system — tickets stay in
ticketron.ticket; graph holds a shadow
02 Physical structure
Same DB · same MCP · same tenant token · migrations 0005/0006 · query db/queries/slice.sql
Default read plane: valid_to IS NULL AND lifecycle IN ('active','reference'). Archived material costs zero tokens by construction. RLS keys on app.current_tenant — the client never supplies tenant_id.
03 Nodes & edges (closed ontology)
Node kinds
| Kind | Natural key | Primary writer |
|---|---|---|
| ticket / release | UUID | DB shadow triggers only |
| file | repo-relative path | E0 inventory; E2 fills attrs.key_symbols |
| spec / doc / runbook | path | E0 frontmatter + path heuristics |
| asset / identity / datastore / … | name | dictionaries · postapply (names/IDs only) |
| worktree / agent_session | path / session id | session seams |
| symbol | Deferred as nodes — store on file.attrs.key_symbols until blast-radius demands E3 | |
Edge rels
| Rel | Meaning | Typical provenance |
|---|---|---|
| depends_on | import / build dep (file→file) | fact · indexer E2 |
| tested_by | tests that gate a file | fact · E2 / gate |
| implements | ticket|spec → file | orchestrator ship · judgment for legacy |
| touches | ticket|worktree changed file | orchestrator (git diff) |
| documents | doc|spec explains file|spec | judgment / seed |
| deployed_in / works_on / waits_on / … | release & occupancy | release-engineer · session |
seed / resync / human) may annotate facts, never create
file/symbol nodes or depends_on/tested_by/touches edges.
Fact stamps in practice: ticketron · orchestrator · postapply
(there is no extractor enum value in 0005).
04 How search works today
Not a free-form graph query language. Three thin verbs, token-budgeted:
| Verb | Job |
|---|---|
| get_slice | Depth-limited (≤2) undirected neighborhood from a ticket id or anchor_key. Wraps db/queries/slice.sql. Returns id/kind/key/name/summary/uri/depth — never bodies, never attrs in the default projection. |
| find_nodes | Name / natural_key ILIKE match, optional kind, default lifecycle filter. BM25 later, same signature. |
| get_events | Poll bigserial since cursor — ship signals, worktree open/close, dependency_cleared. |
Contract (G3): call get_slice first; on miss / outage / staleness, grep. Then Read(uri) only for the shopping list.
get_slice(ticket_id) → { nodes: thin facts, uris }
↓
agent Read(uri) for selected bodies only
↓
optional: emit_event / ship writes touches+implements for lineage
05 Intended agent journey
| # | Question | Graph answer |
|---|---|---|
| 1 | What am I building? | Ticketron get_ticket + shadow kind=ticket |
| 2 | Where is the spec? | ticket.spec_uri / spec node uri |
| 3 | Which files implement it? | implements / documents (needs E1 or judgment edges) |
| 4 | What do those files depend on? | depends_on depth 1–2 (E2 — seeded for ticketron) |
| 5 | What tests gate them? | tested_by |
| 6 | Anyone else touching them? | worktree / touches / works_on |
| 7 | Deploy / assets? | deployed_in, dictionary nodes, postapply harvest |
06 Seed & refresh
Order: ticketron → automaton → dmx-marketer; stop before TAP.
# PowerShell — Lakebase through hosted MCP (no local APP_DATABASE_URL required)
$env:TICKETRON_TOKEN = [Environment]::GetEnvironmentVariable('TICKETRON_TOKEN','User')
$env:TICKETRON_MCP_URL = 'https://ticketron-mcp.livelypond-7bd06177.eastus2.azurecontainerapps.io/mcp'
uv run python scripts/seed_graph.py --via-mcp --dry-run
uv run python scripts/seed_graph.py --via-mcp
Direct-DB mode still works when APP_DATABASE_URL points at the Lakebase app role. Idempotent on (tenant, project, kind, natural_key). DQ heal: python -m graph_audit --project ticketron --repo ..
/ticketron:init-graph (alias /ticketron:graph-seed) for
first-time / rebuild seed. Use /ticketron:update-graph for path-scoped
keepalive after commits. Optional Class-B Azure/tf harvest on init:
--with-azure / --with-terraform plus
automaton/docs/runbooks/init-graph-azure-tf-harvest.md.
07 Gap to the intended use
| Capability | State |
|---|---|
| Schema + verbs on hosted MCP | Shipped (G0–G1, G5) |
| Writer / reader seams in automaton | Shipped (G2–G3) — activate on live ships |
| Lakebase dogfood inventory | Seeded 2026-08-21 — find_nodes works |
| Ticket → files in one hop | Incomplete — need implements/documents edges |
| init-graph front door | Shipped — /ticketron:init-graph (alias /ticketron:graph-seed) |
| update-graph keepalive | Shipped (V1) — /ticketron:update-graph / python -m graph_update |
| With/without-graph benchmark | Not run |
| Web Graph Inventory page | Not built (V0.2 second surface) |
| G4 TAP pilot | Deferred (won't fix now) |
Binding ontology: ../datamind-automaton/automaton/docs/knowledge/07-graph-ontology-and-substrate-decision.md.
Plan: solution-architecture-live-context-graph.md.