ontology-atlas
Ontology Atlas MCP server lets an agent read, query, validate, analyze, and safely maintain a Markdown ontology vault tied to a codebase.
Inspect vault/repo roots, Git status, history, and create vault-scoped snapshots.
List, fetch, search, and query ontology concepts, backlinks, neighbors, paths, centrality, communities, impact, and graph health.
Compile the ontology and validate vault structure, path drift, evidence drift, and wiki pages.
Create, patch, rename, reclassify, merge, and delete concepts; add, remove, or replace typed relations with previews/confirmation.
Bind projects to local source folders, finalize project meaning, and manage saved constellations.
Analyze repository structure, infer imports, inspect architecture conformance, and plan project indexing.
Read vault source documents and analysis archives; absorb agent-instruction Markdown into document nodes.
Support safe write workflows with dry runs, expected mtimes, blocked reasons, and post-write maintenance guidance.
Provides tools for interacting with local Git repositories, including reading vault-scoped commit history, inspecting Git status, and creating vault-scoped Git checkpoints (snapshots) without pushing.
Enables exporting the compiled ontology graph as JSON-LD or GraphML, which can be opened in Neo4j for graph database analysis and visualization.

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
Install the app from the download page, or open the browser version.
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.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 citedA 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.
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 -- --runpnpm 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 |
| Browser shard options, without discovering or running tests; unknown options fail before execution |
| Each harness's instruction files are valid; Codex and Claude files need not match |
| Rebuild Moru sprites, 74 animation exports, 16 poses and compass sizes from retained project sources; inspect |
| A delegation brief with the port, scratch, checks and merge lines filled in |
| Reuse |
| Plan merging several branches as one, then prune the branches main contains ( |
| Which gates this change needs |
| Which open pull requests change the same files as this branch, and whether a trial merge conflicts |
| The decision to cite or overturn, and whether this change owes one |
| The current token ramps, resolved from app/styles |
| A new living document from its template in |
| Docs gates, including |
| Every living document's kind, status and area; one document's commits across moves |
| Moves the documents in |
| Records this repository's star and fork counts, with the day read, for the download page's open-source section |
| Rebalances the browser shards from downloaded |
| Refuses a new fixed |
| Which CI checks ever failed, per run, from the lane reports CI uploads |
| Re-shoots the app screens in |
| Where Claude Code tokens went per agent type, from local transcripts, and which runs broke the compaction window or turn caps (budget) |
| Dead files, exports and types |
| Shipped packages are on the license allow-list, and |
| Compose |
| Checks one locale's strings against |
| Whether the MCP server releases memory across repeated calls; about a minute |
| Fire CI on a draft now |
| Dry-run a merge, or merge queued pull requests until the queue is empty |
| Queue a pull request to merge (green ones merge together behind one CI run), and show the queue |
| The mechanical facts a reviewer would otherwise count by hand: line growth, 800-line files, export and dependency changes, untouched sibling tests, security paths |
| After |
| Types across every file, with Next's generated route and page types |
| 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 |
| Builds and serves the static export on a free port (or uses |
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 toolsabsorb_documentADestructive
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: documentnodes with arole: policyfrontmatter 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:
Without confirm: true the call is a dry-run — returns the classification plan per section, no writes.
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_relationAIdempotent
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_relationsAIdempotent
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_structureARead-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 candidateREADME.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 claimdocument excerpts expose
excerptInfofor selected prose only.excerpt-truncatedkeeps incomplete excerpts review-required; replay its hash-boundnextSourceReadwith sourceOnly:true, then follow sourceEvidence continuations before claiming an omitted conditionselected 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
sourceReadsreturns bounded exact source lines with a full-file hash and continuation coordinates. Follow-up reads carry the returnedexpectedSha256; 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 authoritya 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 qualificationan 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_ontologyARead-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_infoARead-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_conceptADestructive
⚠ 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_sourceADestructive
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_backlinksARead-only
Return every node that points to the target slug. Scans both frontmatter array keys (capabilities / elements / dependencies / relates / contains / describes etc.) and the wikilinks / markdown links in the body. Used by AI agents to walk the graph from a node to its dependents.
Inputs: slug (required). Returns: total, target, matches
find_evidenceARead-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_neighborsARead-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_orphansARead-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_pathARead-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_conceptARead-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_conceptsARead-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_constellationARead-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_historyARead-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_snapshotADestructive
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_statusARead-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_projectARead-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_importsARead-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_architectureARead-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_conceptsARead-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_constellationsARead-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_kindsARead-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_conceptsADestructive
⚠ 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:
Without confirm: true the call is a dry-run — returns the redirect plan + list of deletions without writing.
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-safebyPhase/bySeverity/byKindqueue buckets, actionscore, executableproposedAction, and current-pagenextExecutableAction/nextReviewActionpointers 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_conceptsARead-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_ontologyARead-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_sourceARead-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_conceptADestructive
⚠ 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_relationADestructiveIdempotent
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_conceptADestructive
⚠ 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:
Without confirm: true the call is a dry-run — returns
updates(each affected file with before/after array keys + bodyChanged flag) without writing.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-safebyPhase/bySeverity/byKindqueue buckets, actionscore, executableproposedAction, and current-pagenextExecutableAction/nextReviewActionpointers for the final graph.
Inputs: newSlug (required), oldSlug (required), confirm, overwrite, +1 more. Returns: ok, uid, moved, dryRun, +13 more
replace_relationADestructive
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_vaultARead-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_wikiARead-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
Scored across 40 tools
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.
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.
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.
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
Related MCP Connectors
A living knowledge graph to read, think against, and leave a deposit in that outlives you.
Shared memory for teams and their AI agents: Markdown concepts with typed links in shared bundles.
Personal context for every AI: search, read, and write back to your private Markdown library.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to read and write a local-first knowledge base of plain markdown files in git, with governance gates for safe, hash-anchored edits.1Apache 2.0
- FlicenseBqualityBmaintenanceTurns 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-
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseBqualityBmaintenanceLocal-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.2529AGPL 3.0