axiom_graph_search

axiom_graph.mcp.server.axiom_graph_search(project_root, query, level=None, max_results=20, node_type=None, mode='keyword', scope='all', tag=None, offset=0)

Full-text search over node level_1 and level_2 fields.

Returns one line per match: {node_id}  {level_1 summary}. A header line always reports how many results were returned and the total number of matches before the cap, so you can tell whether narrowing the query would help.

Finding all usages of a symbol

Prefer this tool over axiom_graph_list for answering “where is X used?”. The efficient pattern is:

1. axiom_graph_search(project_root, "SymbolName") – locate the node ID.

2. axiom_graph_graph(project_root, node_id, direction="in") – find callers and dependents from the index.

3. grep_search for literal call sites (construction, imports) that may not be captured as edges in the index.

This is significantly cheaper in context than calling axiom_graph_list (which dumps every node) and more targeted than reading full files.

How the query is interpreted

In keyword mode (default), the search runs through three stages, stopping as soon as any stage returns results:

1. FTS (ranked) – SQLite FTS5 full-text index, BM25-ranked. A single word finds every node containing that word, ordered by relevance. A quoted phrase ("scan module") requires both words adjacent. A prefix (scan*) matches any word starting with those characters. Multiple unquoted words (scan import) require all words to be present – if nothing contains every term, this stage returns nothing and the next stage runs.

2. LIKE-AND fallback – substring scan, all tokens must appear somewhere in the text. Same AND semantics as FTS but no ranking. Fires when FTS returns nothing (e.g. query used unsupported syntax).

3. LIKE-OR fallback – substring scan, any token matches. Broad and low-confidence; capped at 10 results regardless of max_results. If this stage fires it usually means the query terms are too common or unrelated – a more specific single term will return better-ranked results from stage 1.

In semantic mode, the query is converted to an embedding vector and matched against stored node embeddings via cosine similarity. This finds conceptually related nodes even when the exact words differ. Requires embeddings to have been generated during axiom_graph_build. Falls back to keyword mode if embeddings are unavailable.

Parameters:

project_root str

Absolute path to the indexed project.

query str

Search string. A single specific term or a quoted phrase returns ranked results from the FTS index. A prefix ending in * (e.g. resolv*) matches all words sharing that root. Multiple space-separated terms require all of them to appear in the same node.

level int | None

1 – search level_1 (one-line summaries) only; faster and less noisy when you already know the function/module name. 2 – search level_2 (full docstrings) only; useful when looking for behaviour described in prose rather than in a name. None (default) – search both fields.

max_results int

Maximum number of nodes to return (default 20). The header line shows the total match count so you can raise this when needed. LIKE-OR results are always capped at 10 regardless of this value.

node_type str | None

Restrict results to a single node type: "atomic_process" for functions/methods, "composite_process" for modules, or omit to search all types.

mode str

Search mode: "keyword" (default) uses FTS5 full-text matching. "semantic" uses embedding-based vector similarity search (deprecated as of 2.1.0; slated for removal in 3.0 – use keyword search).

scope str

Filter results by source: "code" returns only code nodes, "docs" returns only doc section nodes, "all" (default) returns both.

tag str | None

Only return nodes with this tag.

offset int

Number of leading matches to skip before returning results (default 0). Pair with max_results to page through a large result set.

Return type:

str