Support local graph.json file for instant context injection

[jonathanpopham]

Summary

Add ability to generate and read from a local graph.json (or .supermodel/graph.json) file so agents start sessions with codebase context already available, rather than generating on the fly.

Problem

Currently, explore_codebase generates graphs on-demand, taking 5-15 minutes. This has several issues:

1. Not realistic for evals - Each benchmark task requires waiting for graph generation
2. Burns iteration budget - Agent spends iterations waiting instead of working
3. Cold start every session - No persistent "memory" of codebase structure across sessions

Proposed Solution

1. CLI command to generate graph file

# Generate graph and save locally
npx @supermodeltools/mcp-server generate --output .supermodel/graph.json

# Or in a specific format
npx @supermodeltools/mcp-server generate --output graph.json --format sir

2. MCP server reads from local file if present

On startup, MCP server checks for:

• .supermodel/graph.json in working directory
• graph.json in working directory
• Path specified via --graph-file flag or env var

If found, graph is loaded into cache immediately. Agent queries resolve instantly.

3. Freshness indicator

Include metadata in the file:

{
  "generatedAt": "2026-01-27T...",
  "gitCommit": "abc123",
  "gitBranch": "main",
  "summary": { ... },
  "graph": { ... }
}

MCP server can warn if graph is stale (e.g., git HEAD has moved).

Use Cases

Context injection for AI agents

Developer workflow:
1. npm run generate-graph  (in CI or pre-commit hook)
2. graph.json committed or gitignored but present locally
3. Agent session starts → graph already loaded → agent works immediately

Benchmark/eval runs

Eval workflow:
1. Pre-generate graphs for all benchmark repos
2. Place graph.json in each repo's working directory
3. Run eval → no API latency during benchmark

Team sharing

Team workflow:
1. CI generates graph.json on main branch
2. Stored in artifact storage or committed
3. Team members pull latest graph with code
4. Everyone's agents have same structural context

Relation to Idempotency Keys

This complements (not replaces) idempotency-based API caching. Local file is for:

• Instant cold-start (no API call at all)
• Offline usage
• Controlled versioning with code

API caching is for:

• Dynamic generation when no local file exists
• Shared cache across different machines/agents