← Selected projects
Knowledge engine for codebasesPrototype · 2026

Project Wiki

A knowledge engine for projects spread across several repositories and a Notion workspace. It distils them into a graph of concepts, keeps a link from every concept back to the exact code it came from, and updates itself as the sources change. Coding agents read it over MCP. I read it in a browser or just ask it.

01 / The problem

Everyone relearns the same project by reading the same files again. Including the agents.

When a project is spread across several repos and a Notion workspace, the understanding of how it all fits together doesn't live anywhere. A person rebuilds it by reading source. A coding agent rebuilds it from scratch every session, pulling the same files into its context window and paying for the same reading again. Generated API docs just mirror the folder tree and rot along with it, and full text search hands you text rather than understanding. Some things aren't written down in any single file at all, like a wire contract two repositories both quietly depend on. So I wanted a knowledge base organised by concept instead of by file, where every concept points back to the exact symbol it came from, that keeps up as the code moves, and that a person and an agent can both read without going back to the raw material.

68 / 69requirements verified by a requirement-tagged test

02 / Architecture

A strict hexagonal core with thin entry points, so every surface and the maintenance loop are adapters over one read model instead of three separate implementations.

Four rings with dependencies pointing inward only, enforced by two import-linter contracts: an ordinary layer contract, and a forbidden-imports contract that names every framework, database driver, and model SDK the domain and application rings may not touch. Sources enter through pluggable connectors as stable coordinates in Postgres. A retrieval index and a batched distillation engine turn them into a provenance-linked concept graph, while an organisation pass and a review queue add domains, cross-source edges, and human adjudication of anything contested. A Typer CLI, a FastAPI read API, and an MCP server are transport-agnostic drivers over the same application use cases. Maintenance re-runs a narrow slice of that pipeline whenever a source moves.

03 / Engineering

The decisions behind the system.

01

Batched, resumable, self-correcting distillation pipeline

Init is long, expensive, and likely to break somewhere. One model call over a whole repository hits the output cap, loses everything the moment it fails, and spreads the model's attention too thin to be useful. The pipeline turns it into small pieces of work that survive failing halfway.

Implementation details
  • File-aware packing groups a file's units together up to a token budget and sub-splits a single oversized unit, so the model always distils a symbol alongside its local context
  • Each batch commits in its own transaction, so partial progress survives a later failure and re-running init skips batches already done; a failed batch is isolated, recorded with its failure kind, and the run finishes the rest
  • Retry depends on why the batch failed: a truncated reply is re-planned into smaller sub-batches with the budget halved per attempt, a transient error backs off, invalid JSON retries once and then stays visibly failed, capped at three attempts
  • A batch is identified by its packing ordinal, not by the set of coordinates it covers, because sub-split pieces share one parent coordinate and keying by coordinate re-distilled a whole oversized file once per piece
Distillation pipeline / Three-part walkthrough01 / 03
01Packing — a file's units travel together up to a token budget, and an oversized unit is sub-split.
02

Provenance and incremental maintenance from git

Keeping the wiki current without rebuilding it is the harder half of the problem. Maintenance runs off git itself, only looks at what a change actually touched, and can never throw away knowledge it can't prove is gone.

Implementation details
  • What changed is computed from git directly, never from a webhook payload, because a pull-request payload carries no file list and a push payload truncates past 20 commits
  • Only the touched documents are re-ingested, and only the concepts whose provenance points at those coordinates are re-examined, through the same batch path init uses, so the two cannot drift
  • Evidence is retired only when its content is provably gone, asked of the coordinate's identity rather than a line range; a concept left with no live evidence is proposed for deprecation, never deleted
  • A concept that its own changed source now contradicts is corrected, quoting the document's new sentence, rather than retired; a source that merely stops mentioning a concept is never treated as a verdict
Maintenance / A merged pull request through the loop01 / 01
01Maintenance flow — a git diff selects documents, provenance selects concepts, each is corrected, deprecation-proposed, or queued.
03

Architecture and verification discipline as a system

I made the project's own correctness and honesty into things you can test, after a green build lied to me for months.

Implementation details
  • Strict hexagonal, four rings, enforced by two import-linter contracts, one of them a forbidden-imports list naming every framework, driver, and model SDK the domain and application rings may not import
  • A test that stubs the seam it is testing proves nothing: browser-driven init passed its gate for months while never working, because the endpoint flushed instead of committing and the fake background task never touched the database; every scheduling site now commits before scheduling and a test drives real scheduled work against Postgres
  • A requirement counts as verified only through a passing test tagged with its ID: a pytest plugin writes a verification map and a generator rolls it into the status page, which is never hand-edited
  • Four documentation-honesty gates run inside the single build command: the migration head must match the ORM metadata, .env.example must document every settings field, the generated agent context must match its source, and every internal doc link and repository path must resolve
Verification / The build gate01 / 01
01make check — six stages, with the four documentation-honesty guards running inside the test stage.

04 / Product walkthrough

PROJECT WIKI / RUNNING APP03 VIEWS
01Browse — a concept reads as a short chapter, with its provenance and relationships beside it.

05 / Evaluation

Checked by a requirement-tagged test suite, plus two full runs against real models scored against a key I wrote before starting.

The gate is the single build command: roughly 775 backend tests and 127 frontend tests, plus ruff, strict pyright, and the import-linter dependency rule, all green. 68 of 69 registered requirements are verified by a requirement-tagged test. The 69th, engine-proposed reading paths, is deliberately unbuilt and named as such on the generated status page, so the denominator is every requirement the project knows about.

The proof runs drove guided init and the full maintenance loop end to end against a two-repository fixture pair with real Anthropic and OpenAI models, on 1 and 14 August 2026. Each run was scored against an assessment key written beforehand. In the maintenance run, 8 of 9 checks passed, 1 was unevaluable, and 1 surfaced a real defect: a concept left asserting what its source no longer said, because the reconciliation judge was scoped by source reference rather than by document. That was fixed. Measured cost for both fixtures was about $1.10.

What I haven't tested is how it behaves at the size of a real project: how big the review queue gets, whether coverage skews toward prose, and where the single process maintenance loop gives out. That's next, by actually running it on my own platform and fixing what shows up, rather than something I want to claim now.

68 / 69requirements verified by a requirement-tagged test, on the generated status page
8 / 9maintenance checks passing in the 14 August 2026 proof run, scored against a key written beforehand
~775 + 127backend tests and frontend tests in the green build gate

06 / Outcome

An unfinished knowledge engine that proves its own claims, now going into real use on my own projects.

The interesting engineering is in place and tested: a resumable, self correcting pipeline over a paid model, incremental maintenance that tracks provenance and refuses to drop anything it can't prove is gone, and a build that fails when its own documentation drifts away from the code. It isn't finished. The next phase is pointing it at my own platform, seeing how what I built holds up against real work, and improving it from that instead of in the abstract.

Delivered

The full engine (ingest, index, distil, merge, organise, review, light divergence) and all four v1 surfaces (guided init and review queue, visual browser, MCP server, in-product chat with server-side history), plus self-maintenance from merged pull requests.

Validated

68 of 69 requirements green by requirement-tagged tests, plus two end-to-end proof runs against real Anthropic and OpenAI models scored against assessment keys written before each run; one run caught and led to the fix of a real reconciliation-scope defect.

Next

Project Wiki is not a finished product. I am putting it to work on my own multi-repo platform, using that to evaluate what exists today and to improve it over time as real use shows what matters (review-queue volume, prose-skewed coverage, single-process maintenance). The one unbuilt requirement, engine-proposed reading paths, comes first.

Next projectContextual Outreach