Ontology Atlas

ontology-atlas

> A repo-native memory layer for Claude Code, Cursor, and Codex. > > Your AI coding agent forgets your codebase between sessions. Give it a > local, git-backed mental model it can read, query, and maintain through MCP.

[](LICENSE) [](https://nextjs.org) [](mcp/README.md)

| Open it | Link | |---|---| | App brand | Ontology Atlas (repo, CLI, MCP package, and release assets stay ontology-atlas) | | Website / downloads | https://ontology-atlas.web.app | | GitHub repository | https://github.com/wlsdks/ontology-atlas | | MCP docs | [mcp/README.md](mcp/README.md) |

Ontology Atlas is the installable macOS app and public product name for the ontology-atlas project. ontology-atlas remains the repository, CLI, MCP, and release-artifact identity.

ontology-atlas is a local-first workbench for the shared memory between a developer and their AI coding agent. The graph is not stored in a hosted database. It is plain markdown frontmatter inside your repo, so every change is reviewable as a normal git diff.

npx ontology-atlas init ./ontology
ontology-atlas analyze . --vault ./ontology
ontology-atlas workspace-brief ./ontology
ontology-atlas health ./ontology

No backend. No login. No cloud account. Your repo is the source of truth.

---

Why It Exists

AI coding agents are useful, but they usually rebuild project context from scratch every session. They remember the current prompt better than the long term shape of the codebase: domains, capabilities, dependencies, ownership, and design decisions.

ontology-atlas gives agents a durable local memory they can query before touching code and update after real changes.

The minimum useful setup is just Atlas plus a normal agent. If Claude Code, Codex, Cursor, or another MCP-capable agent can connect to the Atlas MCP server or run the Atlas CLI, the product must already work. CodeGraph, Serena, language servers, grep, and other source tools can make investigation faster, but none of them are required for Atlas to deliver the first graph brief, handoff packet, health check, or memory update diff.

It helps coding agents by giving them the right starting point, product meaning, and verification path before they inspect code. It is not trying to replace CodeGraph, Serena, grep, AST indexes, language servers, or source search. Those tools answer structural questions such as where a symbol lives and what calls it. Atlas answers meaning questions: which domain or capability the code proves, why the change matters, what impact to check, and which validation path should run before the memory is trusted.

The product is not "please maintain an ontology." The useful loop is:

1. Open a repo.
2. Draft the first graph automatically from source layout, README headings,

package.json, and TS/JS imports.

1. Let the AI agent answer through MCP using the maintained graph.
2. After code work, let the agent propose memory updates.
3. Review the markdown diff.
4. The next agent session starts with better context.

How It Helps A Coding Agent

Atlas helps before, during, and after a coding task. It does not replace the agent's source-code tools; it gives the agent a smaller, better starting packet so those tools are aimed at the right problem.

flowchart LR
  A["User asks: improve or add something"] --> B["Atlas finds the related domain and capability"]
  B --> C["Atlas returns implementation evidence: files, commands, tests, MCP tools"]
  C --> D["Agent uses available source tools on that narrow code area"]
  D --> E["Agent changes code and runs the named verification path"]
  E --> F["Agent proposes ontology updates as a markdown diff"]
  F --> G["Next session starts from the updated meaning model"]

For a request like "improve the topology relation labels," the useful memory is not every symbol in the graph renderer. The useful memory is a compact handoff:

Relevant capability: topology ontology inspection
Meaning: relation labels must expose typed ontology facts without covering the
graph or hiding the next action.
Implementation evidence:
- src/widgets/topology-map-sigma/ui/SigmaSkeletonCards.tsx
- src/widgets/topology-map-sigma/ui/SigmaSkeletonCards.test.tsx
- scripts/verify-macos-app-launch.mjs
Recommended code lookup:
- Use the available source tool: built-in search, grep, language server,
  Serena, CodeGraph, or another local code index.
- If no source tool is available beyond the agent's normal file access, start
  from the Atlas MCP/CLI packet and inspect only the implementation evidence it
  names.
Verification path:
- focused unit test for the topology label contract
- macOS app verification when desktop topology behavior changes
Memory update rule:
- update the ontology only if the change adds, renames, or clarifies a domain,
  capability, element, relation, or verification contract.

That packet saves tokens because the agent no longer has to rebuild the whole product story from source files and chat history. More importantly, it reduces wrong edits: the agent knows what the code is for, which proof matters, and when the durable repo memory should change.

What It Does

| Surface | What you use it for | |---|---| | macOS app | Install once, pick a local vault folder, and use the visual tree, topology, docs, projects, and ERD builder without returning to the website. | | CLI | Init a vault, bootstrap from a repo, validate frontmatter, compile graphs, inspect paths, find backlinks, rename/merge/delete nodes safely. | | MCP server | Give Claude Code, Cursor, Codex, and other agents 24 local read/write tools over stdio JSON-RPC. | | Website | Explain the product, show a read-only demo, and route users to the signed macOS release download. | | Compiler + query engine | Turn markdown files into a deterministic graph artifact with graphHash, issues, indexes, health checks, impact, lineage, cycles, and maintenance actions. |

How The Memory Works

In this project, an ontology is the executable meaning model of a product and the codebase that realizes it: projects, domains, capabilities, elements, and the relations that explain why they belong together or depend on each other. It is useful only when planners, marketers, decision-makers, developers, and AI agents can read the same graph before work, update it after work, and verify it as a git diff.

The ontology is not a generic slide-deck taxonomy and it is not a raw source-code index. Business concepts belong when they explain product intent, operating model, ownership, capability boundaries, decisions, or impact. Source files belong as element nodes when they prove or realize a higher-level domain or capability. The daily target is the layer that connects those two worlds: a durable map of what the business/system means, why it matters, and which implementation carries it.

That means Atlas stores meaningful implementation evidence, not every code fact. A class, route, command, test, or file path is useful when it helps an AI agent start a task with the right capability, trace the change impact, or run the right proof. Exhaustive symbol graphs remain the job of code-intelligence tools; Atlas keeps the repo-native meaning layer those tools cannot infer on their own.

Every markdown file is one graph node. Frontmatter is the machine-readable record; the body is the human-readable explanation.

---
slug: capabilities/token-issue
kind: capability
title: Token issue
domain: domains/auth
elements:
  - elements/src/auth/token-service
dependencies:
  - capabilities/session-refresh
---

Issues access and refresh tokens for authenticated users.

compile_ontology reads the vault and produces a deterministic graph artifact: canonical nodes, canonical edges, aliases, issues, graphHash, maxMtime, and optional query indexes. query_ontology then answers graph-style questions over that artifact: neighbors, paths, centrality, communities, impact, blast radius, project scope, lineage, cycles, health, agent brief, workspace brief, and maintenance plan.

That means this is not a server-side graph database. It is a markdown-backed ontology vault with graph database behavior at runtime.

Quick Start

1. Create a local vault

npx ontology-atlas init ./ontology

The command scaffolds a git-friendly markdown vault and writes repo-local MCP configs for your agent. Claude Code and Cursor can read the generated .mcp.json; Codex can read the generated .codex/config.toml. A global codex mcp add ... fallback is printed too.

Already have a vault? Run ontology-atlas agent-setup ./ontology --write to repair only the agent config files without adding starter markdown.

2. Draft the first graph

ontology-atlas analyze . --vault ./ontology      # preview only
ontology-atlas bootstrap . --vault ./ontology    # write accepted candidates
ontology-atlas workspace-brief ./ontology

analyze is side-effect-free. It proposes domains, capabilities, elements, and relations from real repo structure. infer-imports can add TS/JS import evidence for dependency edges.

3. Use the visual app

The hosted site is the product introduction and download entry point. Daily visual editing starts in the installed macOS app: download the signed DMG from the GitHub Releases page after the release gate publishes it, launch the app, and pick your local vault folder.

Maintainers can run the desktop shell from source while developing:

git clone https://github.com/wlsdks/ontology-atlas
cd ontology-atlas
pnpm install
pnpm desktop:dev

Three views plus MCP, one vault

The same frontmatter graph is rendered three ways and exposed to agents through MCP:

• Topology (/topology) - Sigma WebGL spatial network of projects and relations.
• Tree (/, /ontology) - project to domain to capability to element drill-down.
• ERD builder (/ontology/edit) - xyflow canvas for adding nodes and relations visually.
• MCP (mcp/) - JSON-RPC stdio server with 24 tools for AI agents: 16 read + 8 write.

All four read and write the same .md files. Pick the interface that matches the task; the vault stays the source of truth.

Agent Workflow

Use the graph before code work:

ontology-atlas workspace-brief ./ontology
ontology-atlas agent-brief ./ontology
ontology-atlas agent-brief ./ontology --graph-db-pack
ontology-atlas overview ./ontology
ontology-atlas backlinks capabilities/token-issue ./ontology
ontology-atlas blast-radius capabilities/token-issue ./ontology

agent-brief is the Claude Code/Codex handoff: readiness score, graph entrypoints, first MCP calls, investigation playbooks, write guardrails, relation_check decision guide, health coverage, and the read-first write policy. agent-brief --graph-db-pack prints a shell-pasteable graph scan pack for connector-less sessions, with the selected vault path already inserted. workspace-brief is the cheap first-contact dashboard: it shows hotspots, PROJECT별 포함 노드 수 (project_scope), health-check coverage as id:status:count, and growth counts before the agent chooses where to read deeper.

Then let the agent sync memory after non-trivial changes:

• New code capability: add a kind: capability node.
• New concrete file/module worth tracking: add a kind: element node.
• New dependency: add a relation.
• Rename or merge: use the safe dry-run commands first, then confirm.

Manual editing is allowed, but the product bet is automation: bootstrap first, agent-maintained memory after that.

Web Routes

| Route | Purpose | |---|---| | / | Hosted landing page, or local ontology hub inside the installed app after a vault is selected | | /download | macOS release download and install guide | | /docs | Desktop local vault picker, markdown editor, command palette | | /ontology | Tree and ego graph hub | | /ontology/edit | ERD canvas builder | | /ontology/insights | Kind census, hubs, relation breakdown | | /topology | Spatial graph view | | /projects | Project list from kind: project docs | | /project/[slug] | Project detail (inline edit when a local vault is loaded) | | /project/[slug]/edit | Full project editor | | /project/new | New project form | | /project/fallback | Static-export fallback for unknown project slugs |

The public website is a static promo/download site with a read-only demo. Real vault editing happens in the installed macOS app after it receives permission to access a local folder on your machine.

Verifiable promises

| Promise | How this repo checks it | |---|---| | No backend | pnpm bundle:check keeps Firebase/server chunks out of landing, download, and local-first app routes. | | Static deploy | pnpm build exports to out/; Firebase Hosting serves only static files. | | Static dogfood manifest | pnpm docs-vault:check keeps committed src/entities/docs-vault/data/manifest.json and public/docs-vault/ in sync with docs/. | | Vault integrity | pnpm vault:validate, test:vault:validate, vault:audit, and test:vault:audit remain explicit local/release-preflight gates. | | MCP/CLI contracts | pnpm test:cli:args, pnpm test:mcp:docs, pnpm package:check, pnpm test:contracts, and focused test:mcp:* scripts cover the agent surface. | | Graph hot paths | pnpm perf:graph:check is part of pnpm package:check, so compile/query latency budgets run before release. | | Dogfooding | This repo's own vault has 106 nodes: capabilities 36, document 3, domains 6, elements 59, project 1, vault-readme 1. |

For the detailed maintainer command matrix, see [docs/DEVELOPMENT-CHECKS.md](docs/DEVELOPMENT-CHECKS.md).

Local Development

pnpm install
pnpm dev
pnpm exec tsc --noEmit
pnpm lint
pnpm test:run
pnpm build
pnpm docs-vault:check
pnpm bundle:check

Helpful vault commands:

pnpm vault:validate
pnpm vault:audit
pnpm dogfood:compile
pnpm dogfood:compile-fix
pnpm dogfood:compile-fix -- --help
pnpm test:dogfood:args
pnpm test:dogfood:script-refs
pnpm test:dogfood:compile-fix
pnpm dogfood:health
pnpm dogfood:agent
pnpm dogfood:agent-graph-db-pack
pnpm dogfood:agent-setup-gate
pnpm dogfood:agent-fallbacks
pnpm dogfood:brief
pnpm dogfood:status
pnpm dogfood:status -- --help
pnpm test:dogfood:status
pnpm dogfood:verify

Vault tooling

The vault tooling is intentionally local and scriptable:

pnpm vault:validate              # frontmatter integrity audit
pnpm vault:validate /your/vault  # validate any folder
pnpm vault:validate -- --help    # print validator usage without scanning
pnpm test:vault:validate         # focused validator CLI argument contract
pnpm docs-vault:check            # committed docs-vault output freshness
pnpm vault:audit                 # dogfood ontology paths match real repo files
pnpm test:vault:audit            # focused vault audit CLI argument contract

CI runs pnpm docs-vault:check, pnpm vault:validate, pnpm test:vault:validate, pnpm vault:audit, pnpm test:vault:audit, and pnpm package:check on every PR.

Architecture

| Area | Stack | |---|---| | App | Next.js 16, React 19, TypeScript 5, App Router, static export, Tauri macOS shell | | UI | Tailwind CSS 4, Radix primitives, lucide icons | | Graph | Sigma.js, Graphology, ForceAtlas2, xyflow | | Local-first | Tauri native vault bridge, source-browser File System Access fallback, IndexedDB handle/path persistence | | Agent interface | @modelcontextprotocol/sdk, stdio JSON-RPC | | Tests | Vitest, Testing Library, jsdom, Playwright, Node test runner |

Feature-Sliced Design import direction is enforced by ESLint:

app -> views -> widgets -> features -> entities -> shared

Documentation

| Document | Use it for | |---|---| | [docs/PRODUCT-DIRECTION.md](docs/PRODUCT-DIRECTION.md) | Product strategy and launch framing | | [docs/AGENT-MEMORY-POSITIONING.md](docs/AGE

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wlsdks
• Source: wlsdks/ontology-atlas
• License: MIT

Install and usage instructions live in the source repository linked above.