Ontology Atlas

Understand your system as AI agents change its code.
_{Give agents task context. Inspect the meaning, evidence, and unknowns yourself.}

Download for macOS · Windows x64 beta _unsigned · Live demo · Guide · Status

The current Ontology Atlas macOS app with the Online Store project selected: the domains it contains named around it, everything unrelated receding, and the right inspector showing the project record, its code-evidence state, and the offer to connect a code folder

_{Every screenshot reads samples/storefront, an online store described by Markdown files in this repository.}

In 30 seconds


What	An `atlas/` folder of Markdown inside your repository. Each file's frontmatter says what it is (`project`, `domain`, `capability`, `element`, `document`) and what it points at. That folder is the whole database.
For your agent	Typed task context over MCP: capabilities, code anchors, declared dependencies, evidence, and unknowns.
For you	The same records on a map, in documents, and as Git diffs, so you decide which meaning changes to keep.
Honest by design	A graph path is a declared relationship, not proof of runtime impact. Missing evidence shows as unknown, never as safe.

text

your-repo/
├── src/
└── atlas/                 ← the whole ontology, cloned, branched and reviewed with the code
    ├── project.md
    ├── domains/  capabilities/  elements/
    ├── sources/           documents kept exactly as they arrived
    └── wiki/              pages written from those sources, every fact cited

See it

Map — select a concept; everything unrelated recedes.	Five views — Flat, Galaxy, Cone, Strata and Neural.
Agents — chat with Claude Code or Codex inside the app.	MCP — one button per agent, then a live connection proof.
Library — gather any document, compile cited wiki pages.	Documents — edit the Markdown that becomes the graph.
Architecture — reviewed roles against the imports in code.	Relation review — see before and after, then confirm.
History — the exact Markdown diff before you save.	Analysis — what to fix next, by measurement, not a score.

How it works

Open a folder — the app reads Markdown in place, or starts atlas/ from your code. The path is shown before anything is written.
Connect your agent — one button writes the MCP config; a restart and mcp-verify prove the connection is live.
Ask for context — query_ontology with operation: "agent_brief" gives the agent a bounded brief for its task.
Review the meaning — proposed changes arrive as Markdown diffs; you keep, correct, or reject them in Git.

Definition previews preserve complete introductory text; the full document retains exclusions and uncertainties. Local code inspections show the connected folder and offer native permission recovery before reading.

console

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

What one node looks like

yaml

---
uid: 71890f3e-7b5d-4c0a-8f14-123456789abc   # permanent identity, kept through renames
slug: capabilities/token-issue
kind: capability
title: Token issue
domain: domains/auth
path: src/auth/token-service.ts          # a path — code evidence
elements:
  - elements/jwt-signer                  # a slug — an implementation-role node
dependencies:
  - capabilities/session-refresh         # a slug — another node
---

Issues access and refresh tokens for authenticated users.

A path points at code; a slug points at a node. dependencies are directed and relates is symmetric, so the map never turns similarity into causality. Only files with kind: join the graph; sources/** and wiki/** pages do not. Full contracts: what becomes a node? · relations · vault specification.

Principles

Local-first	Not a…
Your disk is the database; Git is the history.	general-purpose ontology editor
No Atlas backend, account, or telemetry.	code index or IDE
Model and provider transfers are opt-in and logged in `.ontology-atlas/llm-audit.jsonl`.	automatic acceptance of generated knowledge
MCP and CLI read the folder directly, even with the app closed.	RDF/OWL/SHACL implementation (§5.2)
Extensions are files a `git diff` shows you, never third-party code.	service, and not on npm

Measured, honestly: our first benchmark mostly tested vocabulary only Atlas knew. Re-scored, we have not yet measured a difference in answer quality, and Atlas was slower. The correction · benchmark log.

Status — read this before installing

The download page is the release authority: tag, sizes, checksums, and signing state. GitHub Releases is the second source.
macOS is Developer ID signed and notarized, with the MCP server inside the bundle.
Windows x64 is an unsigned beta — SmartScreen may warn, and a managed PC may refuse it. See Security.
Linux and others run the browser app, or the CLI and MCP server from a source checkout.
Every release is a plain version; the in-app updater verifies each archive's signature before installing.

Documentation

Use it: hosted guide · features · MCP setup · CLI reference
Model a vault: what becomes a node? · relations · specification · quality authority map
Understand it: product direction · architecture · security · decisions

Contributing

Issues and pull requests are welcome; the most useful report points Atlas at a real repository and shows where it falls short. Read CONTRIBUTING.md first (external pull requests come from forks), and AGENTS.md is canonical for people and agents alike. Start with pnpm checks:changed -- --run; land with pnpm pr:land <number>.

Repository commands

Command	What it answers
`pnpm agents:check`	Each harness's instruction integrity; independent Codex and Claude files need not match
`pnpm backlog` · `pnpm backlog:check`	Current task records and concurrent-state conflicts; append a UUID record per worktree observation (guide)
`pnpm bundle:plan` · `pnpm bundle:prune`	Land several branches as one: plan the merge (which carry work, shared files, trial conflicts) and afterwards prune the component branches main provably contains. See `/land-bundle`
`pnpm checks:changed`	Which gates this change actually needs
`pnpm conflicts:scan`	Which open pull requests (and `-- --match=<glob>` local branches) change the same files as this branch, and whether a trial merge with each conflicts; read-only, one `gh` call
`pnpm decisions:find <terms>` · `pnpm decisions:check`	The decision record to cite or overturn, and whether this change owes one
`pnpm doc:new -- --type=<kind> --area=<area> --slug=<slug>`	A new living document from its template in `docs/.templates/`, at the path its kind decides
`pnpm docs:check`	Docs gates, including `pnpm docs:language`, `pnpm source:language`, `pnpm changelog:check`, `pnpm dev-checks:check`, `pnpm docs:meta`
`pnpm docs:meta` · `pnpm doc:history -- <path>`	Whether every living document carries its kind, status and area with pointers that resolve; one document's commits across moves, which is its version
`pnpm docs:move`	Moves the documents listed in `docs/.moved.json` and rewrites every reference; rerun it after merging main into an older branch (`-- --check` only reports)
`pnpm e2e:durations -- <timings dir>`	Rewrites the per-file weights that balance the browser shards from downloaded `playwright-timings-*` reports
`pnpm e2e:sleeps:check`	A change may not add a fixed `waitForTimeout` to an e2e spec unless a `// measurement window:` note says why
`pnpm gates:yield -- --runs=200`	Which CI checks ever failed, per distinct run, from the lane reports `checks.yml` uploads (cached in `~/.cache/atlas-gate-yield`); a row with 50+ runs, no failed run and 60+ days of history reads `no CI failure`, a check to examine rather than delete, since pre-push and `pnpm checks:changed` catches are not in this data. Reports start with the change that added them
`pnpm gateway:capture -- --base-url=<static export>`	Re-shoots the six app screens the download page shows, Korean and English (`public/gateway/<screen>.<locale>.png`), from a served `pnpm build`, against this repository's own ontology
`pnpm knip`	Dead files, exports and types across every scope
`pnpm lessons` · `pnpm lessons:check`	Shared harness lessons that are open or verified but not yet fixed; record and review them with `/harness-retro` (records guide)
`pnpm messages:build` · `pnpm messages:check` · `pnpm messages:adopt`	Compose the ignored `messages/<locale>.json` from one file per namespace (`messages/<locale>/<Namespace>.json`), prove it current, and carry a pre-split branch's catalogue edits onto the parts while merging main
`pnpm perf:mcp:memory` · `pnpm perf:mcp:memory:check`	Whether the MCP server keeps memory it should release: heap after two forced collections across 50 repeated calls per tool and across moved Git HEADs, on a generated vault; about a minute, kept out of pre-push
`pnpm pr:ci <n>`	Fire CI on a draft now, so a green, disjoint change can take the fast path
`pnpm pr:land --plan <n...>` · `pnpm pr:land --conduct`	Dry-run what a landing would do without writing to GitHub, and run trains until the queue is empty
`pnpm pr:land <n>` · `pnpm pr:queue`	Queue a pull request for the landing train (or merge it on the fast path), and show the queue and the train in flight
`pnpm typecheck`	Types across every file, with Next's generated route and page types, so the browser build need not check them again

Rows stay sorted by command, and the reference's entries by area, so two branches that each add one land on different lines; pnpm dev-checks:check names the line to move and -- --fix sorts both. Development checks is the full gate reference, one entry per area; map testability owns canvas performance, readability, contrast, and instrumentation.

License

MIT