Skip to main content
Glama

English | 한국어 | 日本語 | 简体中文

The Ontology Atlas map of this repository's own ontology with the Ontology Atlas project selected: its domains and capabilities laid out around it, a concept list on the left, and the project record with its code-evidence state on the right

Why

Coding agents now change code faster than a team can keep a picture of it in their heads. Atlas keeps that picture beside the code: what each part is for, which files implement it, what depends on what, and what nobody knows yet. Your agent reads it before a task and proposes updates after; you keep, correct or reject each change as a Markdown diff.

  • Your agent starts with context. Claude Code, Codex, Cursor and Antigravity read the concepts, code paths, dependencies and open questions a task touches, over MCP.

  • You own the record. One Markdown file per concept in an atlas/ folder, versioned and reviewed in Git like the code.

  • You decide what is true. Agent proposals stay proposals until you accept them.

  • It says what it does not know. A line on the map is a declared relationship, not proof of runtime impact; missing evidence shows as unknown, never as safe.

Related MCP server: obsidian-local-mcp

See it

New in v2.0: Neural, a view of the map drawn as a volume you can turn, beside a 3D tree; Harness Setup, which lists what an agent reads, what stops it and what checks its work; a digest of merged work at the top of Changes; and the run history of every schedule in Automations. Analysis is no longer a separate destination. See the releases.

A few things worth knowing before you start:

  • The map shows declared relationships, not proof of runtime impact. It has five views: Flat, Hex, Domain structure, a 3D tree and Neural. Map

  • An empty folder offers its start actions, and a failed start can be retried without overwriting files. Popup tours are retired. First run

  • Library setup and checks need the app; a browser offers the app or adding files. Library

  • Planning is read-only and works in the macOS app on a folder you choose; it shows Markdown and PNG/JPEG images. Planning

  • Git's send-only action does not commit new file changes; it asks you to review a stale folder or branch again. Pull can change files across the repository. Git

  • Changes opens a Git repository you choose in the app, with or without an ontology. Reading public GitHub pull requests is a separate, explicit step and its list may be incomplete; private pull requests are not read. Change briefing

  • A project document edited since its last meaning review asks for review and explicit re-finalization; saving a change or matching a code path does not accept its meaning. MCP server

  • In the app's chat, each agent write waits for your permission. Codex starts read-only, and its locally configured permission profiles are not offered because their approval behaviour is not disclosed. Agents · Features

  • Before a folder is connected, the app keeps Library, Planning, Agents and Changes reachable. Features

Quick start

  1. Install the app from the download page, or open the browser version.

  2. Open a folder. Atlas reads its Markdown in place, or starts an atlas/ folder in your repository, and shows the path before it writes anything.

  3. Connect your agent. In Agents › MCP, press Connect for your tool, restart the agent, and ask about your next task.

macOS (Apple Silicon) is signed and notarized and carries the MCP server inside the app. Windows x64 is an unsigned beta. On Linux, use the browser version or run the CLI and MCP server from a source checkout. Releases list each version's files and checksums.

How it works

your-repo/
├── src/
└── atlas/                 ← 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

A Markdown file whose frontmatter has kind: is one concept. Its uid never changes, its slug is its current address, and its path names the code it describes. The map, documents, Library and Git screens all read these files.

Your agent reaches the folder two ways:

  • MCP: the agent starts the Atlas MCP server, which reads and writes the folder on disk, even with the app closed. Connect an agent · MCP reference

  • ACP: Claude Agent and Codex also run in the app's own chat; each write waits until you allow it. Agents

Local-first

  • No backend, account or telemetry. The folder stays plain Markdown on your disk.

  • Model calls with your API key or a local model are opt-in, and each records its destination in .ontology-atlas/llm-audit.jsonl.

  • A connected coding agent may send your prompt and what it reads to its own provider; Atlas's log does not cover those transfers.

Trust · Security

Status

Atlas is early. Our benchmark has not yet shown better answers with Atlas, and Atlas was slower (the correction). Construction trials, their failures and limits are in the construction measurements.

Documentation

What is Atlas? · First five minutes · What becomes a node? · Relations · Specification · Features · CLI · Architecture

Contributing

Read CONTRIBUTING.md; external pull requests come from forks. AGENTS.md is the contract for people and agents alike.

pnpm install
pnpm dev
pnpm checks:changed -- --run

pnpm pr:land <number> merges a reviewed pull request and keeps its original commits. Development checks covers choosing checks, CI internals and lane budgets.

Pre-push checks the commit being pushed and runs affected lint, unit and Node tests in parallel with the relevant cheap checks. CI owns browser, full contract and dependency-graph verification. Test-only edits to CI tooling run their regressions without starting unrelated product suites; changes to the planner implementation still require exhaustive CI.

Command

What it answers

node scripts/ci/run-playwright-ci.mjs --help

Browser shard options, without discovering or running tests; unknown options fail before execution

pnpm agents:check

Each harness's instruction files are valid; Codex and Claude files need not match

pnpm brand:sprites

Rebuild Moru sprites, 74 animation exports, 16 poses and compass sizes from retained project sources; inspect assets/brand/moru/preview.html

pnpm brief:new -- --slug=<slug> --owns=<path,...>

A delegation brief with the port, scratch, checks and merge lines filled in

pnpm build:static

Reuse out/ only for matching build inputs; fail without a reuse stamp if inputs change during the build

pnpm bundle:plan · pnpm bundle:prune

Plan merging several branches as one, then prune the branches main contains (/merge)

pnpm checks:changed

Which gates this change needs

pnpm conflicts:scan

Which open pull requests change the same files as this branch, and whether a trial merge conflicts

pnpm decisions:find <terms> · pnpm decisions:check

The decision to cite or overturn, and whether this change owes one

pnpm design:tokens -- [--prefix=<name>]

The current token ramps, resolved from app/styles

pnpm doc:new -- --type=<kind> --area=<area> --slug=<slug>

A new living document from its template in docs/.templates/

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>

Every living document's kind, status and area; one document's commits across moves

pnpm docs:move

Moves the documents in docs/.moved.json and rewrites references (-- --check only reports)

pnpm download:repo-facts

Records this repository's star and fork counts, with the day read, for the download page's open-source section

pnpm e2e:durations -- <timings dir>

Rebalances the browser shards from downloaded playwright-timings-* reports

pnpm e2e:sleeps:check

Refuses a new fixed waitForTimeout without a // measurement window: note

pnpm gates:yield -- --runs=200

Which CI checks ever failed, per run, from the lane reports CI uploads

pnpm gateway:capture -- --base-url=<static export>

Re-shoots the app screens in public/gateway/, in Korean and English; --only=map,neural re-shoots this README's two map pictures

pnpm harness:tokens -- --since=<date>

Where Claude Code tokens went per agent type, from local transcripts, and which runs broke the compaction window or turn caps (budget)

pnpm knip

Dead files, exports and types

pnpm licenses:check · pnpm notice:build · pnpm notice:check

Shipped packages are on the license allow-list, and NOTICE.md is current (rules)

pnpm messages:build · pnpm messages:check · pnpm messages:adopt

Compose messages/<locale>.json from one file per namespace, prove it current, and carry an old branch's edits

pnpm messages:coverage -- --locale <code>

Checks one locale's strings against en: arguments, plurals, script, keep-terms and typography

pnpm perf:mcp:memory · pnpm perf:mcp:memory:check

Whether the MCP server releases memory across repeated calls; about a minute

pnpm pr:ci <n>

Fire CI on a draft now

pnpm pr:land --plan <n...> · pnpm pr:land --conduct

Dry-run a merge, or merge queued pull requests until the queue is empty

pnpm pr:land <n> · pnpm pr:queue

Queue a pull request to merge (green ones merge together behind one CI run), and show the queue

pnpm review:facts -- --base=<ref>

The mechanical facts a reviewer would otherwise count by hand: line growth, 800-line files, export and dependency changes, untouched sibling tests, security paths

pnpm seo:check

After pnpm build: every sitemap URL in out/ canonicalizes to itself, / and each locale root point at /{locale}/download/, and titles and descriptions are unique per locale

pnpm typecheck

Types across every file, with Next's generated route and page types

pnpm ui:audit -- --url=<base> --route=<path> [--setup=<module.mjs>]

Prepare an interactive state with an optional local module, then measure rendered facts per width: horizontal overflow, occluded or unreachable controls, small touch targets, off-ramp type/radius/shadow values, low contrast, unequal repeated sets, scroll-end reserve

pnpm ui:look -- --route=<path> [--vault=fixture|sample|<dir>] [--widths=1440] [--audit]

Builds and serves the static export on a free port (or uses --url), opens each route with a vault attached, and prints one screenshot path per route and width

Use --scope=<selector> to audit one visible modal or region. The selector must match exactly one visible element; the report includes its measured element count.

Moru

Moru is Atlas's pixel seal companion; the compass is the app identity. The repository includes 74 motions, 16 poses and their sources: 58 drawn motions and 16 scenes composed from them. Open the local motion studio to play, pause and inspect every frame.

Where Moru appears. At folder entry Moru greets you, holds out a small folder and waits; once a folder starts opening, play gives way to the waiting view. The download page has its own welcome. Reading a source, waiting for your permission and celebrating a finished check appear only when the app has observed that state, so Moru never shows progress nobody confirmed.

Petting. Press Moru for one short response. The first is gentle, the second reveals a playful one, and after that Moru works through everything it knows while avoiding the last two: 14 responses at folder entry, 18 on the download welcome. A small wordless bubble sometimes answers with a heart, a note or a sparkle, and a pup peeks out once in a long idle.

Staying out of the way. Moru moves only while airborne, and lands before it waits under your pointer. While work is pending it stays quiet and in place. Pause and resume live in Moru's menu (right-click or Shift+F10), with no playback button beside the character, and reduced motion answers with a still expression.

License

MIT. Third-party notices are in NOTICE.md, and the full license texts in public/third-party-licenses.txt. The pixel mascot and its sources are described in Brand.

Available Tools

40 tools
absorb_documentA
Destructive

Slice 0 (PRODUCT-PLAN-2026-07.md §4/§9) — the "absorption tool". Converts a CLAUDE.md/AGENTS.md-style markdown file into typed vault nodes so a tech lead's existing agent-instruction file stops needing dual maintenance. Splits the file by ## sections and classifies each:

  • rule/policy/decision sections → kind: document nodes with a role: policy frontmatter extra.

  • architecture/component sections → element/capability SUGGESTIONS only — never auto-written; review and land with add_concept if useful.

  • sections matching an injection-suspect pattern (Tier 1 — imperative instruction-hijack phrasing, shell/SQL fragments) are excluded from absorption regardless of category and reported for human review. The file body is always treated as untrusted data; parsing never executes or evaluates its content. Two-stage safety, same shape as delete_concept:

  1. Without confirm: true the call is a dry-run — returns the classification plan per section, no writes.

  2. With confirm: true, absorbed sections are written as document nodes, the source file is backed up to <file>.pre-absorb.bak, then rewritten into a "slim pointer" that reproduces every non-absorbed section (suggested, unclassified, or injection-suspect) verbatim — content is never destroyed. Throws instead of overwriting an existing backup file. The canonical source path must be inside repoRoot; outside paths (including symlink escapes) require an reviewed dry-run plus explicit allowOutsideRepo:true.

Inputs: filePath (required), confirm, allowOutsideRepo. Returns: ok, title, dryRun, changed, +13 more

add_conceptA

Create a new ontology node (.md file). Call when an AI agent finds a new capability / element / project from code analysis. Throws if the slug already exists — use patch_concept in that case. The frontmatter is normalized per kind (project gets domains/capabilities/elements empty arrays; capability gets elements: []; capability/element should also set domain: so the tree has a parent — missing extras come back as warnings in the response, not as an error. If another node already has the same title, a near-duplicate warning is included too — prefer patch_concept on the existing node over forking a duplicate. Successful writes return compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers so agents can immediately see graph cleanup / relation suggestions after the new node lands. For bulk creation (e.g. bootstrap flow with 5+ nodes) use add_concepts({concepts: [...]}) (batch, max 50, partial result) — saves K-1 round-trips. When kind is element: an element names a CONCEPT a capability uses (e.g. "jwt-token"), not a file. If your title is a bare path or ends in a source extension, you are describing evidence, not the concept — rename title to the role and put the path in path:, or if 3+ siblings under the same parent already look like this, call get_concept on the parent and consider patch_concept on an existing sibling instead of adding another file-mirror node. The same rule binds the slug: flat under the kind folder (elements/<role-name>), never a code path (elements/src/views/home is rejected) — path-style slugs collide the moment two files share a basename and the graph silently merges distinct nodes.

Inputs: kind (required), slug (required), title (required), body, +5 more. Returns: ok, slug, changed, filePath, +2 more

add_conceptsA

Batch-create multiple nodes in one call — same per-row shape as add_concept. Use after analyze_repo_structure or another reviewed proposal flow when the agent has K accepted candidates from the user — replaces K×add_concept round-trips. Each row is processed independently: existing-slug / invalid-kind / missing-required-fields / non-object row shape / unknown row fields surface as { slug, ok: false, error } rows whose errors include a concepts[n] row label, single unknown-field rows include receivedField plus one-row unknownFields, multi unknown-field rows report every unknown field with nearest hints and Received fields: ..., and duplicate input slugs report the later concepts[n] row plus first-seen concepts[m] with structured rowName / firstSeenAt; the rest still land. A row whose normalized title matches an earlier landed row in the same batch still lands but carries a near-duplicate warning — patch_concept the earlier node instead of forking the same concept (duplicates are the #1 growing-vault failure mode). concepts[] order in the response matches the input. Cap = 50 per call (split into multiple batches for larger sets). NO atomic rollback — if you need all-or-nothing semantics use single add_concept calls. Invalid-only batches return no row-level write metadata and no top-level postWriteMaintenance. When at least one row changes the vault, the response includes one compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers for the final graph. Rows whose title is a bare file path follow the same rule as add_concept above. Prefer one capability node covering a directory plus a short elements: list over one row per file, unless each file's role differs in a stated sentence.

Inputs: concepts (required). Returns: concepts, postWriteMaintenance

add_relationA
Idempotent

Add a semantic relation between two nodes. Appends to the matching frontmatter graph key (domains / capabilities / elements / dependencies / relates / contains / describes); domain sets the source node's inline parent domain. The relation type picks which key receives the entry. A new depends_on relation requires a nonblank why; an already-existing edge remains an idempotent read even if legacy data has no rationale. R11: optional expected_mtime — pass the source-side mtime from a prior get_concept so concurrent external edits throw VaultConflictError. Invalid relation type is rejected before endpoint slug resolution with a closest-value hint and structured valueName / receivedValue / suggestion / allowedValues repair fields in structuredContent, with no changed, alreadyExists, or postWriteMaintenance write metadata. Changed writes return compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers so agents can immediately see graph cleanup / relation suggestions after the edge lands. For multiple already-approved semantic edges use add_relations({relations: [...]}) (batch, idempotent, max 50). infer_imports.moduleEdges require exact-evidence review, a semantic rationale, and human approval first.

Inputs: to (required), from (required), type (required), why, +1 more. Returns: ok, to, key, from, +4 more

add_relationsA
Idempotent

Batch-add multiple relations in one call — same per-row shape as add_relation. Use after analyze_repo_structure or another review flow when the agent has K semantic edges accepted by the user — replaces K×add_relation round-trips. Inferred module edges are not accepted merely because imports exist; review exact evidence and include the required nonblank why for every new depends_on. Each row is processed independently and idempotently: existing edges return {ok: true, alreadyExists: true}; missing source/target slugs / unknown type / non-object row shape / unknown row fields surface as {ok: false, error} with a relations[n] row label and structured rowName; unknown type rows include a closest-value hint with structured valueName / receivedValue / suggestion / allowedValues; single unknown-field rows include receivedField plus one-row unknownFields; multi unknown-field rows report every unknown field with nearest hints, allowedFields, receivedFields, and Received fields: .... relations[] order in the response matches the input. Cap = 50 per call. NO atomic rollback — for all-or-nothing semantics use single add_relation calls. Tip: avoid expected_mtime in batch when multiple rows share the same from slug — the first row mutates that file so the second would see a stale mtime. Invalid-only batches return no row-level changed / alreadyExists write metadata and no top-level postWriteMaintenance. When at least one row changes the vault, the response includes one compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers for the final graph.

Inputs: relations (required). Returns: relations, postWriteMaintenance

analyze_repo_structureA
Read-only

R16 (autonomous ingest base) — analyze a code repository and propose ontology node candidates. side effect 0 (vault frontmatter NOT modified). Returns deterministic candidates the agent must turn into an evidence-backed proposal and move through the construction lifecycle before any exact batch-writer rows are released. Repository structure is implementation evidence, not automatic business meaning: extractionContract and proposedBusinessOntology make that uncertainty explicit. Detects:

  • package.json name → project candidate

  • README.md first H1 → project title fallback

  • README.md H2 sections (skipping generic "Usage"/"Installation"/etc) → domain candidates

  • src/features|entities|widgets|views/* (FSD) → capability/element candidates

  • src/* depth-1 folders (generic) → capability candidates + index entry → element

  • apps/* and packages/* members with package.json → implementation element candidates

  • README.rst + bounded static setup.py → Python project/package evidence without execution

  • mixed current and future/negated/deprecated README prose → exact current candidate excerpt plus bounded line-scoped reviewRequiredEvidence; review units stay visible but cannot support a proposal claim

  • document excerpts expose excerptInfo for selected prose only. excerpt-truncated keeps incomplete excerpts review-required; replay its hash-bound nextSourceRead with sourceOnly:true, then follow sourceEvidence continuations before claiming an omitted condition

  • selected safe README sections share the existing 1,200-character budget deterministically; no document, heading, or excerpt cap grows

  • root Python packages plus at most 12 import-connected implementation boundaries → direct modules plus up to 2 exact security/policy/risk file anchors; unused files are not mirrored and no capability is inferred from imports

  • bounded root Cargo package or repo-contained literal direct workspace members → typed feature declaration + literal cfg/cfg_attr source provenance; predicates are not evaluated and no runtime/import/semantic dependency is inferred

  • a complete proposal may select at most 4 additional exact TypeScript, JavaScript, Python, or Rust file endpoints already observed by infer_imports for distinct navigation roles; exact dependency direction is validated and these files never become automatic candidates

  • when the packet identifies an implementation path but omits the rule or effect needed for review, optional sourceReads returns bounded exact source lines with a full-file hash and continuation coordinates. Follow-up reads carry the returned expectedSha256; every proposal or qualification call replays all selected ranges with that hash. Raw source remains untrusted observed evidence and never establishes semantic meaning, approval, or write authority

  • a selector with mode: 'outline' lists a file's declarations with line numbers so the next lines read is exact. For a file longer than about 200 lines, outline it first and then read the exact lines, rather than reading the head of the file and recording the rest as unread. An outline returns no source text and no citation, so it supports no claim; replay line ranges, not outlines, with a proposal or qualification

  • an element proposal may keep an ordinary citation and append reviewed navigation:primary|supporting|test:<path>#<symbol> evidence strings (limits 1/1/3); the server verifies only those named current files, renders human-readable Evidence bullets, and rejects missing, ambiguous, unsafe, or task-inferred coordinates without treating them as behavior proof

Optionally pass a complete proposal to validate project/domain/capability/element definitions, typed relations, citations, risk controls, domain placement, implementation paths, confidence, and typed competency answers with resolvable concept/relation/evidence/path witnesses. Partial or visible-gap answers remain warnings instead of disappearing behind findings 0. A unqualified-project-exclusion warning is an exact human-acceptance gap, while an evidence-limit exclusion remains an error. Source-hidden review may leave exact source-body detail partial; source-aware citation verification decides support before evidence provenance can pass. A mandatory non-gap warning blocks the first review before qualification begins. For a bounded first pass, freeze claim id, statement, and proposalRefs before isolated source-hidden and source-aware lanes run in parallel; separately audit material Definition, Includes, Excludes, and Uncertainty assertions even when several claims share one proposal ref. Join sealed receipts without mutation before human acceptance. A passing validation first returns a deterministic non-writing reviewPlan, planDigest, sourceDigest, and eight-phase construction lifecycle. An independent evaluator must measure the approved competency questions and source-hidden task, then a human may declare acceptance bound to that exact plan digest/revision and every visible gap. Pass the resulting constructionQualification:v1 packet as qualification; only a current, admissible packet releases the exact reviewed rows as writePlan. The lifecycle also reports a shadow-only admission tier; self_qualified is an observation, not a write permission. Declared approval provenance is not identity authentication. Do not call write tools unless proposalValidation.canWrite is true and a writePlan is present; write every concept row successfully before writing relations.

Use the initial discovery call when a user asks "이 codebase 분석해줘" / "bootstrap the ontology"; repeat the same analysis call only for explicit source continuations and digest-bound proposal or qualification replay. For an evidence continuation only, set sourceOnly:true with sourceReads: the response keeps identical bounded sourceEvidence and returns no candidates or lifecycle data. Source-only cannot accompany proposal or qualification and never grants write authority. Single source of truth preserved — only the user (via your subsequent add_concept calls) writes to the vault.

Inputs: ignore, maxDepth, proposal, rootPath, +3 more. Returns: domains, project, skipped, canWrite, +12 more

compile_ontologyA
Read-only

Compile the whole markdown vault into a deterministic graph artifact: canonical nodes, edges, aliases, graph issues, graph-array canonicalization actions, and optional adjacency indexes. This is the compiler-style read path for graph-database-like use: call it before advanced reasoning, indexing, export, or non-developer-friendly graph views. Includes a stable semantic graphHash and maxMtime for cache invalidation. side effect 0. Large vaults (100+ nodes) can exceed the MCP token cap with the full payload. summary: true returns counts + graphHash + byKind/byDomain aggregates with no arrays, for cheap polling, and a call with no argument that asks for arrays returns the same bounded summary plus delivery, which names the two ways to the rest: full: true for every array, or nodesLimit/nodesOffset / edgesLimit/edgesOffset to slice them. The response includes nodesPagination / edgesPagination meta with {offset, limit, total, returned, hasMore, nextOffset} when sliced.

Inputs: full, summary, edgesLimit, nodesLimit, +3 more. Returns: edges, nodes, byKind, issues, +23 more

connection_infoA
Read-only

Return the exact active vault root and code-repository root used by this MCP process, including how each root was resolved. Call first when a client may have stale configuration or multiple workspaces. Root changes require restarting the MCP process. Always returns guide.card, the construction card, plus guide.topics. Pass guide to also receive guideText, the full text of that topic, because a host may truncate the server instructions while tool results arrive whole.

Inputs: guide. Returns: guide, server, repoRoot, sameRoot, +5 more

connect_project_sourceA

Bind a project node to the local code folder it describes, measure it, and write the source receipt. This is what nextAction: connect_source (and repair_source_binding / measure_source / remeasure_source) asks for. Omit rootPath and the server infers it: the git repository enclosing the vault wins, otherwise the nearest ancestor folder carrying a project manifest. Without confirm: true nothing is written — you get the proposed folder, how many declared path: claims actually land in it, and the exact confirming call. Re-running with a different rootPath replaces the binding; disconnect_project_source removes it. The absolute root stays in the local gitignored sidecar .ontology-atlas/project-sources.json and never enters the receipt, the graph markdown, or any handoff.

Inputs: projectSlug (required), repair, confirm, rootPath. Returns: ok, mode, undo, remedy, +10 more

delete_conceptA
Destructive

⚠ DESTRUCTIVE — permanently deletes the vault .md file. Two-stage safety: Both preview and confirmed responses identify the node by permanent uid plus current slug. 1. Without confirm: true the call is a dry-run — returns a backlinks preview without deleting. 2. If any backlinks exist the call throws — refuses while other nodes still reference this slug. Pass force: true to delete anyway (the referrers become dangling). Successful deletion returns the frontmatter + body so a user who deleted by mistake can recreate the node via add_concept. Directories are left untouched. Pass expected_mtime to guard against concurrent external edits — throws if the file changed on disk since you read it. Confirmed deletes return compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers for the final graph.

Inputs: slug (required), force, confirm, expected_mtime. Returns: ok, uid, slug, dryRun, +12 more

disconnect_project_sourceA
Destructive

Remove a project node's local source binding and its receipt. The reversal of connect_project_source — use it when the wrong folder was bound, or to stop measuring. Without confirm: true it only reports what would be removed. Other projects' bindings are never touched, and no ontology markdown changes.

Inputs: projectSlug (required), confirm. Returns: ok, remedy, changed, removed, +6 more

finalize_project_meaningA

Finalize the current project competency Markdown after concept/relation writes, vault validation, and a complete project compile. The server derives the current body digest, project graph hash, source fingerprint, and witness inventory itself; callers cannot submit or restamp those values. This writes only a small provenance receipt to .ontology-atlas/project-meaning.json. It never stores raw answers, witness text, absolute source roots, or remote coordinates. ok: true means the receipt was written, not that source currentness is verified; read meaningAssessment or a fresh agent_brief for the fail-closed categorical result.

Inputs: projectSlug (required), expected_mtime (required). Returns: ok, changed, contract, graphHash, +5 more

find_evidenceA
Read-only

Find vault docs that mention a given concept by title. Useful when an AI agent asks where a capability is realized in code or docs. Each match includes a prose excerpt (max 200 chars, headings/tables/code skipped) so agents see what the matching doc says without an extra get_concept call. Matches are RANKED by a deterministic relevance score (title match > frontmatter ref > body, plus a title token-overlap tiebreaker), then by whether the doc is a graph node, then slug — best-first. A vault holds ordinary markdown too (meeting notes, memos, drafts have no kind: and are not graph nodes); every row says which it is via isNode, non-nodes rank below nodes of equal relevance, and nodesOnly: true filters them out. Do not cite a non-node as graph evidence without saying so. Returns the best 50 by default (limit up to 500), with total matches and limited when more matched. When zero docs mention the title, the response includes a growthHint — near-titled vault nodes to check first, or an add_concept scaffold if the concept looks genuinely new.

Inputs: title (required), limit, nodesOnly. Returns: query, total, limited, matches, +4 more

find_neighborsA
Read-only

Return the one-hop graph neighborhood around a node. Unlike find_backlinks, this is graph-frontmatter only and can include outgoing, incoming, or both directions. Returns canonical edges plus neighbor node summaries so agents can inspect a local subgraph in one call.

Inputs: slug (required), limit, types, direction, +1 more. Returns: edges, nodes, types, center, +4 more

find_orphansA
Read-only

List orphan nodes — docs that no other node references via any frontmatter array key. Useful as a cleanup starting point or to answer "which nodes are unused?". Same matching policy as find_backlinks (full slug or final segment). Root/sentinel kinds like project and vault-readme are excluded by default.

Inputs: kind, excludeKinds. Returns: total, orphans

find_pathA
Read-only

Shortest path between two nodes (undirected BFS). Returns { from, to, hops: [slug...], nodes: [{uid, slug, kind, title, domain?}], edges: [{from, to, via, rationale?}] } where each via is the frontmatter key (domains / domain / capabilities / elements / dependencies / relates / contains / describes) that linked the two slugs and rationale is the one-line relation_notes sentence the declaring document stores for that pair (present only when one is stored) — so the agent sees not just that A and B are connected but by which key and, when someone wrote it down, why. Returns { found: false } when no path is found within maxHops, plus a growthHint — a concrete add_relation (both endpoints exist) or add_concept (an endpoint is missing) example so the unanswered question becomes a vault-growth signal instead of a dead end. maxHops defaults to 5 and is capped at 20.

Inputs: to (required), from (required), maxHops. Returns: to, from, hops, edges, +5 more

get_conceptA
Read-only

Fetch one node by exactly one selector: slug (canonical slug or unique alias) or immutable uid. Successful responses always carry both the permanent uid and current canonical slug; graph relations and graph-operation inputs remain slug-based. Returns frontmatter, body, direct graph neighbors, outgoingEdges (each {to, via, rationale?}, the rationale being the stored relation_notes sentence when one exists), and mtime. By default you get excerpt — the first prose paragraph only. The node body is where the construction rules put definition, evidence, confidence, and in-scope/out-of-scope, so pass body: "full" whenever you are reading a node to answer a question rather than just to identify it. bodyInfo always reports totalChars / returnedChars / truncated, so a partial read is never silent. For K specific selectors in one call use get_concepts({slugs: [...]}) or get_concepts({uids: [...]}). When a slug does not resolve, structured growth guidance remains available.

Inputs: uid, body, slug. Returns: uid, body, slug, mtime, +8 more

get_conceptsA
Read-only

Fetch multiple nodes by exactly one selector array: slugs (canonical slugs or unique aliases) or immutable uids. Same per-row shape as get_concept; successful rows always return permanent uid plus current canonical slug. Order matches the selected input array. Missing or invalid slug rows return partial {slug, ok:false, error, ...repairFields} rows, so later valid slugs still resolve; UID misses likewise return {uid, ok:false, error, ...repairFields} without aborting the batch. Graph relations and graph-operation inputs remain slug-based.

Inputs: body, uids, slugs. Returns: concepts

get_constellationA
Read-only

Read one saved constellation by immutable ID from this configured vault. Returns paged saved membership and user purpose separately from current UID-resolved node facts, review currentness, bounded evidence starting points, real declared internal relations, unresolved identities, and direct outside-scope dependencies. UID and merged-UID claims are the only identity source; display paths/titles never retarget. No writes or external sending.

Inputs: id (required), limit, offset, relationLimit, +1 more. Returns: source, current, contract, coverage, +5 more

git_historyA
Read-only

Read commit history scoped to the active vault path only. Returns bounded newest-first hashes, subjects, and authored timestamps plus limited/hasMore, shallow-repository state, and historyComplete so agents do not mistake a truncated or shallow view for complete evidence. Commits that touched only files outside the vault are excluded. Read-only; never initializes, fetches, pulls, commits, or pushes.

Inputs: limit. Returns: ok, head, count, limit, +11 more

git_snapshotA
Destructive

Create a local, vault-scoped Git checkpoint. Dry-run by default and returns exact expectedHead, files, validation, risk, and the shared previewReady/canConfirm/wouldChange/blockedReasons safety contract. confirm:true requires that expectedHead, blocks validator errors and Git operations in progress, commits only the vault pathspec, leaves outside files untouched, and never pushes.

Inputs: confirm, message, expectedHead. Returns: ok, head, risk, files, +24 more

git_statusA
Read-only

Inspect local Git state for the active vault only. Returns HEAD/branch, vault files, outside-vault change counts, staged-outside-vault warnings, and in-progress operation risk. Read-only; never initializes, stages, commits, or pushes.

Inputs: no named parameters. Returns: ok, head, risk, files, +20 more

index_projectA
Read-only

Project ontology indexing plan — run analyze_repo_structure + infer_imports + validate_vault in one read-only call. Use for large or already-existing projects where the agent needs a resumable ontology indexing checkpoint before writing. Its extractionContract treats source facts as observed evidence, README/folder meanings as proposals, and only persisted ontology meanings as shared; it also returns competency questions, uncertainty, approval gates, and whether active-vault validation actually applies to the analyzed project. The plan distinguishes raw candidates into existing, ambiguous-alias review, and genuinely new buckets, then returns exact reviewCalls for retrieving full rows. side effect 0: this tool never writes markdown. CLI index --apply may write analyzer-proposed concepts and containment, but inferred imports remain review-only and are never auto-promoted to depends_on.

Inputs: maxDepth, maxFiles, rootPath, threshold, +1 more. Returns: mode, next, plan, analyze, +9 more

infer_importsA
Read-only

R17 (autonomous ingest deeper) — walk TS/JS files in a code repo and infer file-level + module-level import edges. It also walks bounded root Python packages, bounded src/source-layout Python packages, and deterministic Rust use/file-module/literal-include dependencies. A valid root Go module additionally exposes typed local package-import evidence; it stays separate from legacy file edges and never self-approves a semantic relation. Structured coverage names the supported languages; Rust support is bounded static text evidence and does not expand macros, evaluate cfg, resolve symbols, or prove runtime impact. side effect 0 (vault frontmatter NOT modified). moduleEdges are source-backed review candidates, never self-approving semantic depends_on relations. When you know an implementation file, set focusPath (or reviewMode:"focus") before considering full: Atlas returns bounded exact incoming/outgoing static import receipts, counts, and a cursor without requiring a vault. This focused source boundary is not runtime impact or a semantic relation. Omit reviewMode for size-safe automatic delivery: scans whose estimated full MCP result is at most 128 KiB keep the complete response; larger reconciled scans return exactly one compact, non-writing nextRelationReview:v1 packet plus a delivery receipt and stateless cursor. Use reviewMode:"next" to request that bounded packet explicitly. reviewMode:"full" preserves the complete shape, but a result over 128 KiB additionally requires allowLargeResponse:true; this second confirmation prevents coding agents from accidentally opting into a multi-megabyte response. Oversized raw scans without a loadable reconciliation vault fail with an actionable error instead of emitting an unbounded default response. Every compact candidate carries absentEndpoints. If an endpoint is missing, nextCalls is empty and endpointModelling separates an evidence-only analysis call from the complete rootPath + proposal validation contract, source-bound drafts, and queue resume. It never calls get_concepts or relation_check on a missing slug, never claims the analysis call created an endpoint, and never promotes a path-derived slug into a business kind or definition. Each module edge includes whole-edge source-role/import-usage counts, productValueCount, kindCounts, and a bounded exact file-edge evidence receipt. Missing vault edges remain rationale_review_required: inspect both concepts and the observed direction, ask the user, then call add_relation with an explicit why. Test-only or type-only evidence stays visible but must not be framed as a product depends_on approval question without separate product meaning evidence. Detects:

  • relative imports (./, ../) → resolved to file paths

  • dynamic import() / require() / export ... from

  • bare side-effect imports (import "X")

  • apps/* and packages/* workspace imports collapse to analyzer-compatible element slugs

  • bounded static Python import / from ... import statements in root or src/source-layout packages with init.py; imports nested under an explicit TYPE_CHECKING guard are type_only; source is parsed as text and never executed

  • external package imports listed separately

  • tsconfig.json compilerOptions.paths aliases first, then fallback common @/* aliases → resolved to internal files when the target exists; otherwise unresolved as alias-not-found

Use after analyze_repo_structure to pull real dependency edges from the code, not just suggestedRelations heuristics. Unless reconcile:false, also returns reconciliation (+ reconciliationSummary counts): the module edges diffed against the vault's compiled depends_on edges into inBoth / review-required missing edges / inVaultNotInCode (possibly-stale vault edges). Missing edges carry source evidence and a rationale_review_required gate, never a write action. Single source of truth preserved — inspect both concepts, explain why the semantic dependency holds, and ask the user before one explicit add_relation call with why.

Inputs: ignore, maxFiles, rootPath, focusPath, +8 more. Returns: edges, contract, coverage, delivery, +14 more

inspect_architectureA
Read-only

Read one reviewed architecture-profile/v1 document from the active vault, scan the connected repository with the existing bounded static import analyzer, and return an architectureBrief:v1 for humans and coding agents. The profile declares scoped roles, intended dependency rules, and which known import usages those rules govern; source imports remain observed evidence with usage-qualified receipts. The result distinguishes conforms, violated, and unknown, and never treats unsupported languages, unclassified import usage, empty role mappings, or unmapped edges as compliance. Pattern labels are human/document declarations, not folder-name inference. side effect 0.

Inputs: maxFiles, rootPath, profileSlug. Returns: profile, contract, sideEffect, conformance, +2 more

list_conceptsA
Read-only

List every ontology node in the vault (each .md file with a frontmatter kind:). Filter by kind, domain, and/or since (mtime-based incremental sync). Large vaults are resumable with offset + limit; always follow pagination.nextOffset while hasMore is true. AI agents call this first to grasp the codebase's mental model.

Inputs: kind, limit, since, domain, +2 more. Returns: nodes, total, limited, returned, +4 more

list_constellationsA
Read-only

List saved constellation metadata from this configured vault only. Returns bounded names, user-purpose state, timestamps, member counts, exact sidecar revision, and honest unavailable status for missing/corrupt/unsupported data. Saved membership is task scope, not an ontology relation, review decision, or complete impact claim.

Inputs: limit, offset. Returns: total, source, limited, contract, +5 more

list_kindsA
Read-only

Vault kind distribution — { total, byKind: { capability: N, ... } }. A quick census so AI agents can size up the vault without paging through list_concepts.

Inputs: no named parameters. Returns: total, byKind, referencedOnlyTotal, conceptsIncludingReferenced

merge_conceptsA
Destructive

⚠ DESTRUCTIVE MULTI-FILE WRITE — fold one node into another. Every backlink to fromSlug is redirected to intoSlug (frontmatter array entries + body links), then fromSlug is deleted. The survivor keeps its UID while the source UID/history is recorded in canonical merged_uids. The intoSlug prose and non-identity frontmatter are preserved as-is — they are not merged automatically (use patch_concept after if you want to combine descriptions). Tail-only references are also redirected. Two-stage safety:

  1. Without confirm: true the call is a dry-run — returns the redirect plan + list of deletions without writing.

  2. With confirm: true the rewrites and the delete happen in one pass. Throws if either slug is missing. Confirmed writes return compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers for the final graph.

Inputs: fromSlug (required), intoSlug (required), confirm, expected_mtime, +1 more. Returns: ok, dryRun, changed, deleted, +15 more

patch_conceptA

Update the frontmatter and/or body of an existing ontology node. Use when an AI agent revises, deepens, or reclassifies a node. Frontmatter patches are key-by-key — null deletes a key, omission preserves it. Body is fully replaced when provided, otherwise preserved. Pass expected_mtime (from the previous get_concept response) to detect concurrent external edits — throws VaultConflictError if the file has changed on disk since you read it. Changed writes return compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers so agents can immediately continue graph cleanup.

Inputs: slug (required), body, frontmatter, expected_mtime. Returns: ok, slug, changed, filePath, +1 more

query_conceptsA
Read-only

Typed filter DSL — search vault nodes by predicate. Built for saved-filter / smart-list cases that find_path (BFS) cannot answer, such as "which capabilities have zero elements?", "stub-only nodes in domain=auth", or "has(depends_on) excluding vault-readme".

Grammar (case-insensitive keywords, whitespace-tolerant): filter := atom (AND|OR atom)* atom := NOT? predicate predicate := key=value | key!=value | has(key)

Keys: kind / domain / slug / title for equality, plus any graph frontmatter array key for has(...). kind and has(...) keys are enum-validated with nearest-value hints. Example: kind=capability AND domain=auth AND NOT has(elements) — capabilities under domain auth that have zero elements (= unfinished caps). When total=0, the response includes a growthHint — it names any referenced kind/domain that has 0 nodes in this vault, or nudges you to loosen the filter.

Inputs: filter (required), limit. Returns: total, filter, limited, matches, +2 more

query_ontologyA
Read-only

Analysis archive: analysis_history reads immutable diagnostic Markdown summaries without compiling the graph; use analysisMode, project, limit (1–100 scanned files, default 30), and analysisCursor. analysis_record reads one exact run or review with recordId (UUID). Records retain raw answers, full-body evidence when available, request scope and uncertainty. They are not approved ontology facts; stored qualification describes captured evidence, never current source validity. Reviews are joined to their exact run/finding id. Follow pagination even if a filtered page is empty. These archive operations do not support query_plan. Run graph-engine queries over the freshly compiled ontology artifact. Operations: neighbors (local graph neighborhood), path (one compiled-edge route between two nodes with aligned nodes[] summaries), all_paths (bounded simple paths between two nodes with per-path nodes[] summaries plus limit/searchBudget/exhaustive/truncatedByBudget/totalPathsExact metadata and evidence guidance), query_plan (EXPLAIN-style side-effect-free cost/index estimate plus execution advice before a target operation, filter-preserving suggestedQuery, and filter-aware estimate.totalMatches for match_nodes/match_edges), centrality (PageRank-style core-node ranking plus bridge/authority/hub lists), communities (label-propagation clusters inside the graph), similar_nodes (duplicate/overlap candidates before writes), explain_relation (direct edges, shortest path, and shared-neighbor explanation between two nodes), reachability (transitive graph closure from a start node), pattern_walk (explicit relation-sequence paths such as project → domains → capabilities), impact (incoming by default: what depends on this node), blast_radius (impact grouped by kind/domain with cross-domain edge risk), subgraph (bounded N-hop graph slice for UI/agent views), builder_context (persisted Workshop focus, layout positions, direct graph slice, and safe write handoff; unsaved UI drafts are explicitly excluded; operation name retained for compatibility), overview (counts, relation distribution, and hubs), schema (kind-relation-kind patterns), facets (filter/dashboard aggregates), match_nodes (graph DB-style node rows with degree filters plus a followUp packet for the first returned row), match_edges (graph DB-style edge pattern rows plus a followUp packet for the first returned real edge), node_profile (single node detail dashboard), domain_profile (domain detail dashboard), domain_matrix (domain-to-domain coupling), project_scope (project-contained graph slice), project_map (domain-by-domain project map), relation_check (schema-aware preflight before add_relation), components (connected graph islands), lineage and containment_tree (project/domain/capability containment), cycles (directed dependency-cycle checks), topological_order (prerequisite-first dependency ordering), recommend_relations (safe domain-containment suggestions), growth_plan (side-effect-free ontology expansion candidates, plus a nextReads group that turns the ## Uncertainty section of each node into the reads it asks for: kind, the statement as written, the paths and line ranges it names, and a one-sentence proposed read plus patch_concept, ordered cheapest-first and reporting reason: no_bodies when no node bodies were loaded), maintenance_plan (ordered post-write graph cleanup/repair actions with stable action id, count-safe summary fields, byPhase / bySeverity / byKind remaining-queue buckets, ready cursor cursor.found=true / cursor.reason=null, cursor nextAfterActionId/hasMore pagination metadata, afterActionId resume, unknown-cursor empty page with cursor.nextAfterActionId=null / cursor.hasMore=false, kind filters, executable graph-array canonicalization, executable flags, and current-page nextExecutableAction / nextReviewAction pointers), agent_brief (Claude Code/Codex handoff prompt, structured businessOntologyLens with business-first outcome → domain → capability → element read order, graphDbQueryPack for facets, schema, match_nodes, match_edges, domain_matrix, centrality, all_paths, explain_relation, and business_questions scans for outcome / domain boundary / capability claim nodes / implementation evidence edges, structured cliFallbackCommands, recipes, graph entrypoints, graph_traversal playbook, traversalStrategy plan_before_enumeration/bounded_path_evidence/containment_cross_check guidance, playbook evidence/stopWhen checklists, write guardrails, relationDecisionGuide, resultContracts for all_paths completeness and match_nodes/match_edges followUp evidence, and read-first write policy), meaning_repair_review (provenance-bound, byte-bounded typed evidence pages and literal full-body read calls for the compact meaning repair manifest), workspace_brief (first-contact status + next actions), and health (one-shot graph integrity dashboard whose relationCensus labels compiler declaration counts and the nonnumeric canonical app-map comparison unit). For agent_brief, select project explicitly when the vault has more than one project. Omitted detail and detail:"full" return the complete project-scoped diagnostic contract. For a known coding task, call detail:"compact" directly after connection_info; do not precede it with workspace_brief or a full inventory unless the question needs whole-vault health. Compact v3 requires a nonblank request-local task (max 2000 characters) and returns structuredContent and a handoff text of at most 12000 UTF-8 bytes together: final source/meaning currentness, claim-compatible broad capability selection, persisted element/path evidence, explicit unknown impact and verification, exact full-body next reads, and a detail:"full" follow-up. Its meaningRepair is meaningRepairCompact:v2: status, conflict guards and the first repair step verbatim, plus the omitted step ids and stop-condition count that only detail:"full" carries; read it before repair step 2. Definition and Includes support desired work; Excludes may align with explicit non-goals, while a desired/negative boundary conflict, an unsupported claim, or a tied top claim returns no capability. content[0].text is a self-sufficient handoff and structuredContent the typed facts without it; each carries the first repair call with its guards and the full-detail call. When the selected element Markdown contains reviewed Primary implementation / Supporting implementation / Focused test coordinates and the bound source is current, taskNavigation verifies only those named files and returns exact current lines plus the reviewed non-exhaustive IN/OUT boundary. After those reads, Atlas rechecks the same source identity, fingerprint, revision, and graph hash; any mismatch removes the exact target and downgrades the complete outer currentness contract. A ready prompt reads primary, supporting, focused tests, and a verified manifest together; requires named positive and negative regression tests with exact observable output; and runs the focused check once followed by one non-overlapping full check. Missing, ambiguous, stale, unsafe, or unrecorded coordinates emit no exact target. Task matching selects evidence only; it never searches the repository, never proves source behavior, never persists task text, never approves meaning, and never writes the vault. For impact and blast_radius, only declared depends_on is allowed; use reachability/subgraph for structure. Blast radius reports unknown risk/completeness plus review_required or declared_with_rationale edge qualification until relation-level source receipts exist. A missing depends_on preflight is schema-only: relation_check returns proposedAction:null plus a non-writing approvalGate until the agent explains the observable ability and semantic rationale and receives explicit human approval. Accepts canonical slugs or unique aliases. side effect 0. Use this when you need graph-database-like answers without pulling the full compile_ontology payload.

Inputs: operation (required), to, from, kind, +53 more. Returns: operation, compiledSummary

read_sourceA
Read-only

Vault source documents only; repository code is read through analyze_repo_structure sourceReads. Read the text of one raw source under sources/, cut into the units a wiki citation names (docs/ONTOLOGY-ATLAS-SPEC.md §11): a DOCX by heading (h:<slug>; paragraphs before the first heading are p1), an XLSX by sheet and row (s<n>r<m>), a CSV by row (r<n>), a text or HTML file by line (l<n>). Each unit carries the exact anchor to write into [[src:sources/<file>#<anchor>]], so a page cites what it quotes. A PDF returns no text: the agent runtime reads PDFs natively, page by page, and cites #p<n>. Nothing is converted and kept — the file is read on request and the text returned once. Paging: from (1-based unit index) and limit (default 200, max 1000); when truncated is true, next is the from to continue with. sheet narrows a workbook to one sheet number. Returns { path, format, unitCount, from, units: [{anchor, text, kind, heading?, sheet?}], truncated, next?, sha256, note? }. side effect 0. Use it in place of a shell command when a Compile, Check or ask turn needs what a DOCX or XLSX says.

Inputs: path (required), from, limit, sheet. Returns: from, next, note, path, +5 more

reclassify_conceptA
Destructive

⚠ MULTI-FILE WRITE — change a concept kind and optionally its canonical slug/domain in one previewable transaction. The permanent UID is preserved. Redirects backlinks like rename_concept, and a referrer that lists the node under domains/capabilities/elements moves the entry to the list for the new kind when its own kind keeps that list; otherwise the entry stays and warnings names it. Replaces a generated starter body with the new kind template while preserving custom prose. Defaults to dry-run.

Inputs: slug (required), newKind (required), body, domain, +3 more. Returns: ok, uid, dryRun, changed, +14 more

remove_relationA
DestructiveIdempotent

Safely remove one exact typed relation and its relation_notes rationale from a source node. Defaults to dry-run; pass confirm:true to write. Supports expected_mtime conflict protection. Use this instead of replacing a whole frontmatter array with patch_concept.

Inputs: to (required), from (required), type (required), confirm, +1 more. Returns: ok, to, key, from, +10 more

rename_conceptA
Destructive

⚠ MULTI-FILE WRITE — change a slug and update every backlink in one atomic graph-level operation. The node UID is preserved; only its current human-readable slug changes. Renames the .md file (oldSlug → newSlug, directory move OK), updates the moved file's frontmatter slug: key, and rewrites every backlink — frontmatter array entries (capabilities / elements / dependencies / relates / contains / describes), inline-string keys, and body links [[oldSlug]] / (oldSlug.md). Tail-only references (mcp-server for capabilities/mcp-server) are also redirected to the new tail. Two-stage safety:

  1. Without confirm: true the call is a dry-run — returns updates (each affected file with before/after array keys + bodyChanged flag) without writing.

  2. With confirm: true the file is moved and all backlinks are rewritten in one pass. Throws if oldSlug missing or newSlug already taken (unless overwrite: true). Use this instead of patch_concept + N find_backlinks + N patch_concept loops. Confirmed writes return compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers for the final graph.

Inputs: newSlug (required), oldSlug (required), confirm, overwrite, +1 more. Returns: ok, uid, moved, dryRun, +13 more

replace_relationA
Destructive

Atomically replace one exact relation with a new target and/or type, moving or replacing its rationale in the same frontmatter write. Defaults to dry-run; pass confirm:true to write. Supports expected_mtime.

Inputs: from (required), newTo (required), oldTo (required), newType (required), +4 more. Returns: ok, from, dryRun, changed, +7 more

validate_vaultA
Read-only

R+ (cycle 46) — validate every doc in the vault, return per-doc + per-code aggregate. Replaces the K-round-trip pattern of list_concepts then per-doc get_concept (whose warnings: [...] is per-file). 8 issue codes — unclosed-frontmatter, parse-zero-keys, malformed-frontmatter-line, malformed-quoted-scalar, missing-kind, empty-kind, unknown-kind, missing-uid, invalid-uid, invalid-merged-uids, non-canonical-merged-uids, missing-expected-field, non-canonical-graph-array, dangling-graph-reference, duplicate-slug, duplicate-uid, definition-missing, boundary-missing, epistemic-exclusion, uncertainty-missing, slug-outside-kind-folder, folder-only-evidence, dependency-unwitnessed, dependency-unjudged, starter-example-node, kind-under-sources. Returns { scanned, problems: [{slug, issues: [{code, severity, message}]}], problemsPagination, summary: { problemFiles, errorFiles, warningFiles, byCode: { code: { severity, count, files } } } }. problems is one page, files with errors first and then by slug: offset (default 0) and limit (default 100, max 500) choose it, a page left at the default limit stops sooner when its text would pass 128 KiB, and problemsPagination.nextOffset resumes it, so follow pages until hasMore is false before calling the vault clean. summary always counts the whole vault; each byCode entry names at most 20 files and says how many more in filesOmitted. Also returns pathDrift: frontmatter path: / elements: source paths that no longer exist on disk (vault→code drift), resolved against repoRoot (default: the active resolved repository root from connection_info). Ontology-slug references are never flagged. Fix via patch_concept or remove the stale entry. Also returns evidenceDrift: one Git walk dates every cited path and every concept document, and each concept is current (cited code unchanged since the document), stale (a cited file changed after the document — read it before trusting the recorded meaning), missing (cited path gone) or unknown (nothing cited, no commit in the window, or only a folder-level path moved — listed under folderOnly, because a folder changes on almost any commit). checked: false names why nothing was dated; it never means nothing moved. side effect 0. Use when an agent needs the whole-vault health view: first-contact before writes, before / after a batch write, or surfacing issues to the user.

Inputs: limit, offset, repoRoot. Returns: scanned, summary, problems, pathDrift, +4 more

validate_wikiA
Read-only

Judge the pages under wiki/ against the wiki page contract (docs/ONTOLOGY-ATLAS-SPEC.md §11): no kind:, the seven required frontmatter fields, the five sections in order, a citation on every bullet under ## Facts, and a cited path that is both declared in sources: and present in the folder. A wiki page is not an ontology node — it carries no kind: by contract, which is what keeps it out of the graph — so validate_vault says nothing about whether one fits its own shape. This is that answer. Problem codes: kind-present, missing-field:, section-order, uncited-fact, bad-citation, bad-truncation-record, citation-target-missing, describes-needs-approval. The optional sources_truncated: key lists which paths in sources: the run read only part of; it is what lets a reader tell a document written up whole from one written up in part. Returns { pageCount, failingCount, pages: [{path, problems: [{code, message, line?}]}] } — the same shape ontology-atlas wiki-validate --json prints, so a person and an agent read one report. side effect 0. Use it after writing or editing a page, and before claiming a compile finished.

Inputs: paths. Returns: pages, pageCount, failingCount

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 40 tools

    Disambiguation2/5

    Multiple graph-query tools have unclear boundaries: query_ontology contains neighbors/path/impact/subgraph operations that overlap directly with find_neighbors, find_path, find_backlinks, and compile_ontology. The analysis tools also overlap heavily (analyze_repo_structure, infer_imports, index_project, inspect_architecture), so an agent must read long descriptions to choose correctly.

    Naming Consistency4/5

    Most names follow a readable snake_case verb_noun pattern (list_concepts, add_relation, validate_vault, get_constellation). There are some noun-first exceptions such as connection_info, git_status, git_history, and git_snapshot, plus singular/plural batch pairs, but the convention remains largely predictable.

    Tool Count2/5

    Forty tools is excessive for a single MCP server, exceeding the 25+ threshold where the surface becomes heavy and hard to navigate. The count is inflated by separate read/write/query/analysis tools plus batch variants, many of which could be consolidated or exposed as operations of fewer tools.

    Completeness4/5

    The ontology concept and relation lifecycle is well covered: create, batch create, read, batch read, patch, rename, reclassify, merge, delete, add/remove/replace relations, validation, compilation, repo analysis, and git checkpoints. Minor gaps remain around constellation lifecycle (list/get only, no save/update/delete) and wiki authoring (read/validate only).

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      B
      maintenance
      Turns local code repositories into a queryable dependency graph built from AST parsing and git co-edit history, then exposes it alongside an Obsidian vault as persistent memory. Enables context retrieval, impact analysis of proposed changes, and curation of durable prose knowledge through full-text search and Personalized PageRank classification—all fully offline without API keys or embeddings.
      30
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to build and maintain a shared, git-backed Markdown wiki: they search, file, update and link notes with YAML frontmatter, keep verbatim sources, and optionally read code repos, so knowledge one assistant records is available to all the others. Runs without LLM calls, embeddings or a database, with the vault's own files defining page types, instructions and tools.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Local-first engineering memory and code-graph tools for coding agents. Supports private session handoffs, code-cited knowledge, repository graph inspection, and optional Git-backed team sharing.
      25
      29
      AGPL 3.0