A method for turning a code base into a typed graph that developers and coding agents query
instead of reading — context engineering for code. An agent asks where something lives, gets back
a handful of pointers, and opens only those files. Built on a production system and measured in the
open: the results that went against it are on the .
Graph-theoretic system modeling: living documentation as a typed knowledge graph, with the AI tooling built on it — prompt contracts, embedding and reranking MCP servers, and a 4B local model that navigates the graph and abstains when the answer is not in it. Proven on the checkItOut platform (MIT).
A method, not a product — a three-level map (one hub, a navigator per subsystem, the files),
typed relationships, and navigation clues written for an agent. The same method has been used to
generate documentation on demand,
to place a new feature,
to keep a debugging agent's knowledge of past bugs, and to index an Angular frontend beside a
Spring Boot backend (more examples).
Queryable context instead of a full window — the agent holds a map and asks for pointers; it
never receives file contents from the graph. A query touches a few nodes however large the system
is; reading grows with every file, on every question. What an agent pays end to end is a separate
question, and it is measured.
Subsystems found by mathematics, accepted by a test declared in advance — two independent
partitions, one from what files say and one from how they change, combined on the partition
lattice. Accepted because it beat both inputs on unseen history in 18 of 20 splits
(the mathematics).
A small model trained to navigate, and to abstain — a 4-billion-parameter model on a plain CPU
walks the graph through thirteen verbs, and says "not in this graph" instead of inventing a file.
Served to coding agents over MCP — seven tools; pointers, not file dumps.
Evaluated in the open, losses included — an audit of its own mathematics, a campaign in which
agents with the graph cost more than agents with grep, and a gate that fails the build when a
published number drifts from its artifact (the evidence).
Prompts treated as code under test — a team's conventions prompt measured on real tasks,
rewritten by GEPA, and refused certification because the gain was not certain
(below).
The story
In 2025 I was building a production system with coding agents inside a 200,000-token window. That
is enough to tempt you to read everything and not enough for the system, so every session began by
re-reading the same files and forgot them at the end. The fix was not a bigger window; it was to
stop sending code and send a map.
The map began as notes in the MCP memory server's knowledge graph, moved to Neo4j with one hub node
and six behavioural roles, gained embeddings and reranking as MCP servers, and then a typed algebra
for its edges. The early papers explained it with more mathematics than it had earned. A later audit
and a set of experiments withdrew most of that and kept what survived a test: an unsupervised way to
find subsystems, shipped as an application, served over MCP, and measured — including the night it
lost to grep. The window is five times larger now. The reasons for a map have not gone away: a
model still attends worse to a long context, and every token is paid for on every question.
The whole account, step by step with dates: docs/STORY.md.
How an agent uses it
One question, as the served graph answered it on 2026-09-16
(recorded run):
sequenceDiagram
autonumber
participant A as Coding agent
participant C as CodeMap (MCP)
participant G as Graph engine
A->>C: Where is the Stripe webhook handled, and which service does it call?
C->>G: find("webhook")
G-->>C: StripeWebhookController, StripeWebhookHandler ...
C->>G: flow(StripeWebhookController)
C->>G: impact(StripeWebhookController)
C->>G: flow(StripeWebhookHandler)
G-->>C: typed edges: who calls whom, who injects what
C-->>A: Controller → Handler → SubscriptionService, with 5 pointers
Note over A: opens those files, and only those
Four graph steps, five pointers — each a path, a role, a subsystem and a line count — and no file
content. This run used codemap_ask: a hosted model inside the server (Claude Sonnet) walked the
graph and wrote the answer, at about 190,000 tokens of mostly cached context. That convenience is
the mode that lost to grep on cost; the cheap paths are
codemap_step, where the agent runs the verbs itself with no model in between, and the local 4B
navigator. The same run, step by step, with the part of the graph it touched:
One question, four hops (its source is
docs/walkthrough/). Asked about something the graph does not hold ("the Kubernetes operator that scales the
recommendation engine"), the same server answered that it has no pointer to offer.
The shape
One NavigationMaster → subsystem navigators → one node per file. In the current pack: 1,594 files, 5,573 edges, 92 hyperedges, 34 navigators
Six roles
Every file is an Actor, a Process, a Rule, an Event, a Context or a Resource
Thirteen verbs
mapenterfindimpactflowseamcohortspinehealthreadcache, and the two endings answer and pass (the language)
Seven MCP tools
codemap_askcodemap_stepcodemap_opencodemap_searchcodemap_feedbackcodemap_misscodemap_status (the server)
The mathematics
The part of this repository I care most about getting right, and the part it got wrong first.
What runs: subsystems as a meet on the partition lattice; a type algebra that says which edges
may exist; typed hyperedges; trophic height for "what stands on what"; the statistics that decide
what may be claimed.
What is only described: graph colouring for dependency conflicts, the Ramsey argument for six
roles, the Friendship Theorem for the hub. Papers, not programs; one theorem is false as stated.
What was withdrawn: the magnetic Laplacian as a partitioner, rotations and Berry phase as the
model of an edge, a published anti-correlation, three ways of fusing embeddings. Each was run and
retired by a number.
All three lists, with the formulas and the measurements: docs/MATHEMATICS.md.
Does it help?
Yes for finding things, not yet proven for cost.
A trained 4B model reaches 0.975 execution accuracy on held-out questions and abstains on
questions the graph cannot answer.
At equal content similarity, two files joined by a typed edge are 4 to 9 times likelier to change
together (14 times pooled over all pairs).
On 35 paired tasks, agents with the served graph used 1.6 times the tokens of agents with grep.
They asked a navigator for prose instead of walking the graph, and the comparison that matters
has not been run yet.
Every result, for and against, with its source: docs/EVIDENCE.md. When this
started the window was 200k tokens and a map was the only way to fit a system in it. It is not
perfect, and the open questions are listed there too.
Similar ideas, and when
This was not first. aider built a repository map in 2023; GraphRAG, Graphiti, LangGraph and the
Model Context Protocol all appeared in 2024; one code graph over MCP was published a month before
this repository's first commit on 2025-09-16. What this repository adds to that line: subsystems
found by mathematics, a navigator that abstains, and an evaluation gate.
LangGraph is the closest famous name and a different thing — a graph of the agent's steps, where
this is a graph of the system the agent works on.
Every team with coding agents writes a conventions file and hopes. The alternative is to test it.
What GEPA is.GEPA (Genetic-Pareto, 2025) is an optimiser
for text. It keeps a pool of candidate prompts; each round it runs one on a few tasks, hands the
failures — which rule broke, which test failed, what the judge said — to a reflection model that
rewrites the prompt, and keeps the rewrite only if it does better. Selection is Pareto per task, so
a candidate that is best on one hard task survives beside the one with the best average.
What was done with it here. The conventions of a real Spring Boot code base became a manual of
17 checkable rules. A coding agent implemented ten small features under it; each change was built,
run against hidden acceptance tests, checked rule by rule on the diff, and graded by a judge that
never saw the prompt. GEPA rewrote the manual until the gains fell below the noise floor.
The result. The rewritten prompt scored higher on tasks the optimiser never saw, and the
interval of that gain still included zero. The rule declared before the run said no, so the original
prompt stayed. The pipeline, the statistics, the judge's calibration and every figure:
docs/PROMPT-UNDER-TEST.md.
The served instance is the owner's; a team runs the same server locally with the graph pack from the
latest Release (how). Security is sized for a small team:
one shared token and a user name in a header. Per-person accounts are out of scope.
On your own code base. The agents that index, organise and annotate a code base are in
.agents/; the from-scratch path is the
regeneration runbook. The 2025 route on Neo4j
Community Edition is Paper 3.
Testing
What
How it is tested
The evaluation itself
198 checks on every push, in 0.2 s, with no GPU and no model: the prompt's contract with the parser, the scorer's arithmetic, the grammar's verdicts, and every published figure against its artifact — by replaying nine frozen model runs, 4,936 recorded DSL steps (eval/ci)
The two MCP servers
26 pytest tests between them, 22 of which run in CI; the four that load the real model are marked slow and stay out (embeddings, reranking)
The navigator model
Answers are compared with what the engine executes, never with an opinion about the text (harness)
The served system
Six synthetic users, a calibrated judge, one artifact per night (quality page)
@misc{marchewka2025living,
title = {Living Documentation Through Graph Theory and HoTT},
author = {Marchewka, Norbert},
year = {2025},
url = {https://github.com/Check-It-Out-Dev/graph-theory-system-modeling}
}
Norbert Marchewka · LinkedIn ·
[email protected]. Questions go to public GitHub issues, where the answer helps
everyone; the author does not offer paid consulting on this method. Contributions are welcome and
stay under MIT — language analysers beyond Java, embedding models, query patterns, other graph
databases.
G
Graph Theory System Modeling
Check-It-Out-Dev·5 estrelas·
Graph-theoretic system modeling: living documentation as a typed knowledge graph, with the AI tooling built on it — prompt contracts, embedding and reranking MCP servers, and a 4B local model that nav
Graph-theoretic system modeling: living documentation as a typed knowledge graph, with the AI tooling built on it — prompt contracts, embedding and reranking MCP servers, and a 4B local model that navigates the graph and abstains when the answer is not in it. Proven on the checkItOut platform (MIT).
Ferramentas
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Graph Theory System Modeling?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Graph Theory System Modeling precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Graph Theory System Modeling usa?
Graph Theory System Modeling roda localmente via stdio.
Quando Graph Theory System Modeling foi verificado pela última vez?
Última verificação: 2026-10-28. Graph-theoretic system modeling: living documentation as a typed knowledge graph, with the AI tooling built on it — prompt contracts, embedding and reranking MCP servers, and a 4B local model that navigates the graph and abstains when the answer is not in it. Proven on the checkItOut platform (MIT).