Ontology Atlas

---

In 30 seconds

AI agents change a codebase faster than a person can review every line. A Git diff records which lines moved; the agent's summary is its own claim. Neither preserves which product capability the code serves, why its boundaries exist, or what the change can affect.

Atlas keeps those answers in an atlas/ folder of Markdown inside the repository, so meaning is cloned, branched, and reviewed with the code. Each file's frontmatter declares what it is — project, domain, capability, element, or a linked document — and what it points at. That folder is the whole database.

Because the kinds and relation types are a small fixed set, the folder is not just readable but computable. Atlas compiles it and answers what a notes tool cannot: what breaks if I change this, what is this capability's blast radius, which paths connect these two things, what is disconnected, what is stale. Your agent asks over MCP; you read the same answers as a map. An agent's write is not accepted meaning — it lands as Markdown and a Git diff a person can correct, reject, or keep, and the answers stay bounded: observed capabilities are never treated as exhaustive and unknown coverage is never shown as green. The five-kind discriminator and the standards boundary live in the vault specification.

Status — read this before installing

The download page is the release authority: a generated record of the published tag, real asset sizes, checksums, platforms, and signing state. This README pins no tag, so it cannot contradict the files you are about to install. GitHub Releases is the second direct source.

• The unsigned Windows beta is a real risk, not a formality. SmartScreen may warn about an unknown publisher, and a managed work PC may refuse the installer outright. Security states what is and is not promised.
• Installing the desktop app installs the agent surface. Both bundles carry the compiled MCP server. There is no npm package; every other platform runs the browser app, the CLI and MCP server from a source checkout, or the MCP server as an .mcpb bundle or a container image (channels).
• A -rc.N build walks the same signing, notarization, installer, and updater checks as a final one — what it lacks is a wide run behind it. The in-app updater reads a fixed Pages manifest staged from the newest non-draft release, release candidates included, and every archive must pass the bundled signature check before installation.
• Screenshots demonstrate the product journey, not release availability.

Where it stands

Not a roadmap. This summarizes behavior documented in the feature inventory, the specification, and the decision ledger.

Working today

• A Markdown folder is the whole database — read and written in place, with no import step, no index to build, and no account.
• The macOS app, Developer ID signed and notarized, with the compiled MCP server inside its bundle, and the hosted web app as a no-install gateway.
• MCP over stdio for Claude Code, Cursor, VS Code, Codex, and any other client, typed and advertised through tools/list. Agent guide.
• One-button agent setup that ends in a real proof — paths shown before writing, then an agent restart and mcp-verify. File presence is never presented as a live connection.
• A CLI with the same authority as the agent — scaffold, validate, dry-run writes, traversal, blast radius, commit preflight, agent handoff. CLI reference.
• Every surface reads that one folder — Map, Architecture, Docs, Library, Insights, Projects, Agents, MCP, and Git History.
• Versioned AI analysis kept as local Markdown, with its evidence and selectable history, and measured violations instead of an invented maintainability score. Analysis records.
• Documents of any format gather in the Library, kept byte for byte, with wiki pages required to cite their source on every fact.
• External MCP servers attach to the in-app chat — one switch per server, off by default, tokens only in the keychain. Atlas never sits in that path.
• JSON-LD and GraphML export off the same deterministic compile artifact, so the vault opens in rdflib, Protégé, Gephi, Cytoscape, NetworkX, or Neo4j.
• init installs the agent's procedures where the agent runs, and prints the one sentence to paste into your own CLAUDE.md or AGENTS.md. Atlas does not edit files you wrote.

Shipping, not settled

• Windows x64 is an intentionally unsigned public beta — same folder and MCP surface as macOS, no signature.
• The vault format is v2.0-rc, an RFC open for comment that documents behavior already enforced by contract tests here and carries its own kill criterion. Specification §0.
• Linux has no packaged build — the browser app or a source checkout, same vault, fewer screens.
• Web and desktop do not promise the same screens, and that is not a backlog. Git history and offline work are desktop capabilities; the web cannot run git or native bridges.

What we decided not to build is What this is not.

The journey

1. Open a folder

Point the app at a directory of Markdown and it reads it in place. Ask it to start from your code instead, and it creates exactly one folder inside the project you picked:

your-repo/
├── src/
├── package.json
└── atlas/                 ← the whole ontology, and nothing else
    ├── project.md         one project document
    ├── domains/           what the product is made of
    ├── capabilities/      what each area can do
    ├── elements/          the implementation pieces they work with
    ├── architecture/      reviewed role and dependency profiles, when you have one
    ├── sources/           the documents around the code, kept exactly as they arrived
    ├── wiki/              one page written from those sources, each fact cited
    └── .ontology-atlas/   gitignored, local only: bindings, audit log, activity

That location is a decision, not a default. A map kept outside the repository travels on one laptop, and the change to the code lands in a pull request while the change to its meaning does not. Inside, the two move together in one diff — so commit atlas/, push it, or copy it to another machine, and the map goes with it. The exact path is shown before anything is written, and an existing atlas/ is reused and reported rather than overwritten.

Every screenshot below reads samples/storefront, an example folder in this repository; node cli/src/index.mjs overview samples/storefront prints its current census.

Docs is the same folder without the canvas: preview or edit Markdown, inspect the frontmatter that becomes the graph, follow backlinks, and jump back to the map. There is no imported copy to synchronize.

2. Connect your agent

Agents finds the coding tools already installed on this computer and opens a conversation beside the map. MCP holds the folder's own connection, the setup for each client, and the Connectors that attach external servers to that conversation.

• Connect once, with visible scope. The flow names the folder and config it will change, and writes plain text you can inspect. Claude Code, Codex, Cursor and Antigravity get one button each; any other client uses the snippet.
• Then prove it from the agent's folder. mcp-verify starts the bundled server, reads the active vault, and reports the real result or failure.
• The conversation does not stop at the first map. Up to three next steps derived from the current vault appear under a completed answer; choosing one fills the composer for review and never sends or writes on its own.
• Nothing stays running. The server speaks stdio, opens no port, and makes no network request (Security).

3. Read the map

Selecting a node dims everything unrelated and opens its record without hiding the node behind the inspector — a visual hierarchy for a person and typed parents, evidence and actions for an agent, from the same fact. Recent changes can narrow the map while keeping project and domain context, and Footprints record the order in which you opened concepts.

Three spatial readings stay explicit rather than mixed: Flat is the normal 2D map, Cone hangs each parent's children on a cone with height as the containment tier, and Cloud lets relations determine all three axes. Changing the view never changes the graph.

4. Gather the documents in the Library

A codebase's meaning is rarely only in the codebase. The plan, the spreadsheet, the handover note, the page somebody wrote on a wiki — the Library keeps those exactly as they arrived, under sources/, and nothing is parsed on arrival. Each row carries only what a folder listing can say: format, byte size, and whether it has been written up. Open one and Atlas says so in as many words — it has never read the file, and the hash it shows exists because a page claimed the source.

What is written from them is the other half, and the counts stay honest about it: two of these three are not written up yet, and the folder says so rather than presenting one page as coverage. A wiki page cites its source on every fact, from the same template whether a person or the in-app agent writes it, and wiki-validate names the lines that do not carry a citation rather than grading the page. Compile starts one conversation that reads the sources and writes the page; the traffic goes from your coding agent straight to its own provider, which the screen states instead of implying that Atlas sits in the middle.

Library also works without code or ontology nodes. Keep a question and its cited answer, inspect source changes, request an updated draft through Claude Code or Codex ACP, and compare before saving a new revision. Earlier answers remain available. Local Compile has its own read and approval path. See retained answers.

5. Plan against reviewed architecture

Architecture stays separate from the map. It sets what a person reviewed beside what an agent observed in the code, one role per row, with the difference in the middle; every stroke states its own sentence, and the same profile always draws the same picture. Findings & history keeps every inspection receipt. Pattern names such as Feature-Sliced Design, Hexagonal or Clean Architecture are reviewed declarations: conformance is derived from source evidence, never inferred from folder names.

6. Review a relation beside its node

Atlas shows a directional preview on the map, then a compact review of the source, type, target, reason, and exact frontmatter fields. Confirm and write is the only point that changes the file.

7. Review the change, then record it

Whatever wrote — you, the map editor, the CLI, or an agent over MCP — lands here first as a diff you read before it becomes history. Above is the change confirmed in step 6: two frontmatter lines, still unsaved. Git is scoped to the vault, and files outside the folder you picked are never touched.

The CLI writes the same two lines, says what it would do before touching a file, and refuses a dependency nobody explained ($ATLAS is the entrypoint set in Running from source):

$ node $ATLAS relate capabilities/order-cancel capabilities/refund dependencies ./storefront --dry-run \
    --why "Cancelling a paid order has to give the money back, so cancellation cannot finish without refund processing."

capabilities/order-cancel --dependencies--> capabilities/refund
  verdict matches_existing_schema · exists no
  schema  capability --dependencies--> capability
  pattern count 53 · resolved 53 · external 0 · unresolved 0
  recommendation safe_to_add · No exact or inverse edge found; capability --dependencies--> capability is an existing schema pattern.

dry-run would write dependencies on capabilities/order-cancel → capabilities/refund (no file changed)

Drop the --why and it stops rather than guessing one. An edge in a shape the vault has never used comes back as new_schema_pattern · review_new_schema, so a drifting agent is visible before it writes.

8. Keep it healthy

Insights opens on four measurements: concepts by kind, relations by type, the folder's health in words rather than a score, and the last four weeks of change. Do next is one row per kind of finding, and the counts add up to the title, always. Where a missing back-link can be repaired from two facts already on disk, one sheet names each file it would touch and nothing is written until you apply.

Growth replays the folder's own Git history week by week and stores nothing — the numbers are recomputed from commits each time the tab opens. A folder with no commits is told there is no history to show rather than drawn as a row of zeroes, because a zero would claim the folder was empty.

9. See the shape of the whole project

Nothing here is maintained by hand. Frontmatter has no project: key — the runtime walks the containment graph from each project root and derives coverage from how the documents link to each other.

What your agent gets

Ask what breaks if I change this? and Atlas follows only approved dependency declarations. It does not turn folder structure into causal confidence:

$ node $ATLAS blast-radius capabilities/mcp-server docs/ontology --depth 2
capabilities/mcp-server — blast radius (depth 2, incoming)
  risk unknown · 1 node · 1 relation · 0 cross-domain

impact certainty unknown · declared 1 · rationale 0 · source-backed 0
Counts below follow declared depends_on only. Use reachability/subgraph for structure;
do not read unknown as low risk.

• Focused context, not a repository dump. A brief carries the project, domain, evidence, impact boundary, first tools, and stop conditions; for a task that only reads, OATLAS_READ_ONLY=1 returns one compact batch.
• Typed answers. Paths and reachability explain structure, blast radius follows declared dependencies only. No graph database, no hosted memory.
• Writes that survive review. Analysis is side-effect free by default, destructive operations dry-run first, renames repair backlinks, and mtime guards protect concurrent human edits.

The CLI carries the same authority for sessions that cannot attach a connector: MCP guide · CLI reference.

What we measured, and the mistake we found in it

A paired benchmark gives two sides the same source and question — one with a prepared vault, one with nothing. The first run looked like a large win, 0.25 against 0.875, until re-scoring showed most of that gap was not a comparison: the answer key mostly required Atlas's own concept names, which exist only inside the vault. We had published, in part, a vocabulary test that only one side could sit.

Subject	The part both sides could earn	The part only Atlas could earn	What we published before
Greenfield fixture	0.75 → 1.00	0 → 0.83	0.25 → 0.875
Brownfield fixture	0.75 → 1.00	0 → 0.57	0.28 → 0.74

Each cell reads without Atlas → with Atlas. The control side named 100% of the source files it should have named in every run, and the gap left over rests on one word: the key wanted excludes, and an answer saying "explicitly outside it" scored zero.

So the honest status is that we have not yet measured a difference in answer quality, and Atlas was slower — a median of 17 and 33 seconds here, 28.2 and 51.1 in a separate run that carried one change through code, tests, commit, merge and cleanup on both sides. What it does show is narrower: only the Atlas side returned names you can look something up by. capabilities/checkout is an address a person or an agent can resolve next session, in another tool, months from now; "the checkout feature" is not. The re-scoring found a bug on our side too — the Atlas run dropped its own concept names in a third of the harder cases. Blind human grading is next; a stronger claim waits on unfamiliar repositories, that grading, and the measured cost of maintaining a vault. Method and every raw answer: paired findings · the correction · change-flow run · benchmark log.

Why not just use a notes tool

Local Markdown, git diffs, and MCP are table stakes; notes tools such as Basic Memory already provide them. Atlas adds a product ontology and a workbench where people and agents judge the same facts. If you only need an agent to remember conversations, a notes tool is lighter.