Local graphs first - file-backed knowledge before bigger graph infrastructure

The first graph in a public repo should fit in git.

Not because bigger graph systems are bad. Not because Postgres, Neo4j, or hosted graph services lack value. The reason is simpler: the first job is to make the knowledge surface inspectable.

The StoneyTECH Trinity repos start with:

• graph/nodes.json
• graph/edges.json
• graph/README.md

No hidden control plane. No hosted traversal service. No early data gravity. Just the pattern, the relationships, and a diffable source of truth.

What the graph is doing this early

The file-backed graph is not there to impress anyone with graph vocabulary.

Its job is to make a few important things explicit:

• which pattern the repo demonstrates
• which axioms the repo addresses
• which templates the repo relies on
• which standalone and pair scenarios the repo supports
• which other Trinity members the repo composes with

The list is enough for the first public version.

The graph does not need deep traversal to be useful yet. It needs to stop the pattern from becoming vague.

Why files beat graph infrastructure at the start

The first version of a pattern repo has a narrow duty:

1. stay portable
2. stay inspectable
3. stay easy for an agent to read
4. stay easy for a human to review

File-backed graphs do all four.

Readers can clone them with the repo, query them through a repo-local MCP, diff them in a pull request, and understand them without any separate service contract. This is exactly what a cold reader needs from a public pattern kit.

Hosted graph infrastructure solves a later problem:

• multi-user mutation
• high-volume relationship growth
• heavy traversal
• shared remote access
• operational controls around larger state

Those are real needs. They are just not the first needs.

The important public promise

A reader should be able to clone a repo and know where the graph truth lives immediately.

The promise requires:

• one visible graph directory
• one visible schema shape
• one visible upgrade note
• one MCP surface reading from those files

The promise is much stronger than “trust the architecture in the README.”

The graph files make the pattern auditable.

How the Trinity repos use the same move

StoneyTECH-Trinity-Learning-Agent uses the file graph to expose progression, pairing, and doctrine relationships close to the smallest loop in the set.

StoneyTECH-Trinity-Evidence-Agent uses the file graph to expose brief shape, scenario support, and bounded handoff points.

StoneyTECH-Trinity-GVAR-Engine uses the file graph to expose verifier schema, convergence relationships, and Trinity composition paths.

Three jobs. Same early graph discipline.

The file graph does not replace runtime state. It names the stable pattern truth around the runtime.

What should force the upgrade

The graph should grow up only when the file shape stops being enough.

Good upgrade signals:

• relationship count becomes high enough for manual review to feel painful
• graph queries become central to the product, not just supportive
• many writers need controlled concurrent updates
• repo-local MCP reads are no longer enough
• cross-repo or remote graph access becomes a first-order need

This is the point where a local database, Postgres, Neo4j, or a hosted graph service starts to make sense.

The upgrade should answer a real pressure, not a taste preference.

The safe growth path

The clean path is:

1. file-backed graph in repo
2. repo-local MCP reading those files
3. local database when scale or query shape demands it
4. hosted graph only when sharing or traversal pressure makes it necessary

The order keeps the pattern honest.

It also keeps the public lesson reusable. A repo reader can start with the same cheap, legible graph surface, then choose a heavier backend only when the system earns it.

Why this matters for agent-first repos

Agent-first does not mean infrastructure-first.

An agent needs legible structure more than it needs a glamorous datastore.

A file graph gives an outside agent something concrete to inspect:

• node kinds
• edge kinds
• pairings
• scenario coverage
• doctrine links

The surface is enough to help a coding agent, a planning agent, or a cold-reader assistant understand the pattern without reaching into private runtime state.

The first graph earns trust by being small enough to read.

This is the real reason to start local.