Axon: a local knowledge graph your AI coding agent can query over MCP

What problem Axon claims to solve, and for whom

The README opens with a concrete failure story: an AI agent edits UserService.validate() without knowing that 47 functions depend on the return type, that 3 execution flows pass through it, and that payment_handler.py changes alongside it 80% of the time. The stated cause is that agents work with flat text. They grep for callers, miss indirect ones, and have no model of how code is connected. The README adds that context windows are finite and that LSPs do not expose call graphs.

The audience is therefore narrow and specific. It is developers who already run a coding agent such as Claude Code against a repository and who want that agent to answer structural questions, not just text questions. The second audience is the same developer wearing a different hat: someone who wants to look at the graph themselves in a browser. Both groups are served by the same index, which is the design decision that makes Axon more than an MCP wrapper.

What Axon is not is a general static analysis suite. The README lists dead code detection, coupling analysis and inheritance trees, but those appear as views inside the dashboard rather than as a rule engine you configure. If your need is CI-enforced policy, this is the wrong shape.

The 12-phase pipeline and what the graph actually holds

Axon precomputes structure at index time. The README describes a 12-phase pipeline that runs once over the repository, and the sample session output names the phases in order: walking files, parsing code, tracing calls, analyzing types, detecting communities, detecting execution flows, finding dead code, analyzing git history, and generating embeddings. In the sample, 142 files produce 623 symbols, 1,847 edges, 8 clusters and 34 flows in 4.2 seconds. Those numbers come from the README's own illustration and should be read as an illustration, not a benchmark.

The storage layer is KuzuDB, an embedded graph database, with igraph and leidenalg used for community detection. Parsing is tree-sitter, with separate grammar packages for Python, JavaScript and TypeScript listed in pyproject.toml. That combination explains why the tool is local-only: there is no server to call, and the README states there are no API keys and no data leaving the machine. Embeddings are 384-dimensional vectors from BAAI/bge-small-en-v1.5, generated through fastembed.

Search is a fusion of three strategies rather than a single index. BM25 full-text matching runs through KuzuDB FTS, semantic vector search runs against the embeddings, and a Levenshtein fuzzy pass catches typos and partial matches. The README says the three are combined with Reciprocal Rank Fusion, with test files down-ranked at 0.5x and source functions and classes boosted at 1.2x. Results are then grouped by execution flow. That last step is the interesting one: grouping by flow is what lets a single tool call carry architectural context instead of a ranked list of name matches.

Installing Axon and running a first index

The distribution name and the command name differ, and that is the first thing to get right. The package is axoniq on PyPI, while the console script declared in pyproject.toml is axon. Install it with pip:

pip install axoniq

Python 3.11 or newer is required; pyproject.toml sets requires-python to >=3.11 and lists classifiers for 3.11, 3.12 and 3.13. Then index a repository from its root. The README's TL;DR uses exactly this form:

cd your-project && axon analyze .

The command prints a phase-by-phase progress trail and finishes with a summary line naming the symbol, edge, cluster and flow counts. The README's example reports 623 symbols, 1,847 edges, 8 clusters and 34 flows. Your own counts will differ; what matters is that the run completes and writes the graph.

To look at the result, launch the dashboard. The default port is 8420, and the README documents both a watch mode and a custom port:

axon ui
axon ui --watch
axon ui --port 9000

The dashboard has three views: an Explorer with a force-directed graph rendered through Sigma.js and WebGL, an Analysis view with health score, coupling heatmap, dead code report, inheritance tree and branch diff, and a Cypher Console for running queries against the graph. The README also documents a shared host mode that serves the UI and multiple MCP sessions at once:

axon host --watch

For agent use, the README gives a .mcp.json block to place in the project root:

{
  "mcpServers": {
    "axon": {
      "command": "axon",
      "args": ["serve", "--watch"]
    }
  }
}

After that, the agent can call the tools the README names: axon_impact, axon_query and axon_context. The README's example is axon_impact("validate") returning affected symbols grouped by depth into will break, may break and review, with confidence scores.

Where Axon stops being the right tool

The classifier in pyproject.toml says Development Status :: 3 - Alpha. That is the project's own label, and it should set expectations for anyone planning to build on the CLI or the REST API. The README advertises a FastAPI server with a full REST API and points to an API Endpoints section, but the section is not present in the portion of the README available here, so the shape and stability of those endpoints cannot be confirmed from the documentation.

The licence is a second gap. The pyproject.toml declares license = "MIT" and includes the OSI Approved :: MIT License classifier, but the repository's top-level entries do not list a LICENSE file. The README's licence badge points at a LICENSE path on the main branch. If licence terms matter to your organisation, read the actual file rather than the metadata field.

Language coverage is a third boundary. The dependency list includes tree-sitter grammars for Python, JavaScript and TypeScript only. A repository that is mostly Go, Rust or Java will index poorly or not at all, and the README does not describe a fallback. The topics list mentions TypeScript, which is consistent with the grammar set.

Finally, the git-history phase is only as good as the repository's history. The README's coupling example, payment_handler.py changing alongside the edited file 80% of the time, depends on commits being present and meaningful. A shallow clone or a repository with squashed history gives that phase nothing to work with, and the README does not document how it degrades.

How Axon differs from a plain code graph MCP server

The closest comparison in the search data is a code graph MCP server, a category of tool that exposes graph queries to an agent and leaves the interpretation to the model. The difference in approach is where the work happens. A thin graph server answers the question you ask: give me the callers of this function, and you get a list. Axon precomputes communities, execution flows, type relationships and git coupling at index time, then returns grouped and ranked answers to a single call. The README frames this as reliability and token efficiency: one tool call instead of a ten-query search chain.

That trade has a cost. Precomputation means the index is a snapshot, and the freshness of that snapshot depends on whether watch mode is running. A thin query server reads the current state on each call. If your agent works on a repository that changes constantly and you are not running axon serve --watch or axon host --watch, the graph drifts from the code.

A second comparison point is GraphRAG-style tooling, which the search data also surfaces. GraphRAG approaches generally build a graph from unstructured text and retrieve passages; Axon builds its graph from parsed syntax and call resolution, so its nodes are symbols and its edges are calls and type references rather than text chunks. That makes Axon's answers precise about structure and silent about intent. A comment explaining why a function exists will not appear as a graph fact.

Maintenance, upgrades and the packaging wrinkle

The last push to the default branch was on 2026-08-03. The most recent release is v1.0.1 from 2026-03-09, following v1.0.0 on 2026-03-08 and v0.2.4 on 2026-02-28. Releases and pushes are therefore not in lockstep: there has been branch activity since the last tagged release, but no release since March. Anyone pinning a version should pin to a tag and read the commits after it rather than assume the tag is the current state.

The repository is not archived. It is also not accurate to describe it as actively maintained on the strength of a push date alone; the tagged release cadence is the more useful signal, and it has been quiet since March.

Upgrade cost is dominated by the graph database. Kuzu is pinned at >=0.11.0 and the embeddings come from fastembed, so a major bump in either could require a full reindex. The README does not document a migration path between index versions, and it does not document rollback. In practice that means re-running axon analyze . after an upgrade, which the README presents as cheap at roughly five seconds for most repositories but which will scale with repository size.

The optional neo4j extra in pyproject.toml suggests an alternative storage backend, but the README does not describe how to configure it or what changes when you do. Treat it as unverified until the documentation says otherwise.

Editorial conclusion

Adopt Axon if your agent repeatedly greps for callers and misses indirect ones, and you are comfortable with an alpha-stage tool whose PyPI name does not match its CLI name. Do not adopt it if you need a stable public API, a documented rollback path, or a licence you can read off the repository root. Before installing, confirm the package name axoniq on PyPI and the MIT licence field in pyproject.toml, then run axon analyze . on a throwaway branch and read the dead code report against your own code before you trust it.

Frequently asked questions

Official sources

1. harshkedia177/axon on GitHub
2. Issues
3. Project website
4. README
5. Releases