Indexing

Commands that build and maintain the axiom-graph index.

axiom-graph

Axiom-graph – project knowledge indexer for AI agents.

Usage

axiom-graph [OPTIONS] COMMAND [ARGS]...

init

Initialise (or re-initialise) the axiom-graph index for PROJECT_ROOT.

Creates .axiom_graph/graph.db, runs a full scan, and establishes code_hash/desc_hash baselines for every node. This is the safe first-run command.

If the database already exists, init asks before deleting it. It resets only the index: every baseline, staleness signal, verification record and the change history. It keeps the axiom-graph.toml settings and the agent-policy doc. After the build, when no doc carries the agent-policy tag, it writes axiom-graph’s shipped agent policy as an editable doc in the primary docs root; an existing policy doc is never overwritten.

The reset flags reset one thing each and never touch the index: --policy writes the shipped policy (asking before it overwrites the project’s policy doc; it needs an index), and --settings resets axiom-graph.toml to the defaults, keeping project_id (it lists the settings that change and asks). Together they run policy first, then settings. --yes answers their prompts; without a terminal and without --yes the answer is no. --all resets the index, the toml and the policy doc behind one confirm that --yes never skips.

The project id resolves like build’s: --id, then the toml’s project_id, then the id of the index being replaced, then the directory name (an empty id counts as unset). The id is recorded as project_id in axiom-graph.toml when the toml does not hold it yet (the file is created, or the key added under [axiom_graph]), so every later command, in a worktree or a fresh clone too, uses the same id. When the toml already holds a different project_id, --id is refused before any prompt and nothing changes.

Usage

axiom-graph init [OPTIONS] PROJECT_ROOT

Options

--id <project_id>

Project ID prefix, recorded in axiom-graph.toml (default: the toml’s project_id, else the existing index’s id, else the directory name)

--policy

Reset only the agent-policy doc: write axiom-graph’s shipped default, asking before it overwrites an existing one. Needs an index; never touches it.

--settings

Reset only axiom-graph.toml to the defaults, keeping project_id, after listing what changes and asking. Never touches the index; axiom-graph build applies the new settings.

--all

Reset everything behind one confirm: the index, axiom-graph.toml (to the defaults, keeping project_id) and the agent-policy doc (to the shipped default).

--yes

Answer yes to the –policy and –settings prompts. It never skips the confirm before the index is deleted, so it is an error without –policy or –settings.

Arguments

PROJECT_ROOT

Required argument

build

Scan PROJECT_ROOT and add newly-discovered nodes/edges.

Always runs in discovery-only mode: only new nodes are inserted, existing ones are untouched (staleness signals preserved). Edges are always updated.

To reset all baselines, use axiom-graph init instead.

Usage

axiom-graph build [OPTIONS] PROJECT_ROOT

Options

--id <project_id>

Project ID prefix; must match the id the index stores (default: axiom-graph.toml’s project_id, else the stored id, else directory name)

--purge

Re-run the deleted-file pass after the build (every build already runs it). To remove NOT_FOUND nodes, use axiom-graph purge –all-not-found.

Arguments

PROJECT_ROOT

Required argument

check

Report per-node staleness / confidence status (two-dimensional).

By default only non-VERIFIED nodes are shown. Pass –all for a full inventory. A summary line is always printed first. Only what changed since the last check is recomputed; –full recomputes every node.

Usage

axiom-graph check [OPTIONS] PROJECT_ROOT

Options

--all

Show all nodes including VERIFIED (default: problems only).

--fail-on <fail_on>

Exit 1 if matching problem nodes remain after verification promotion.

Default:

'none'

Options:

none | stale | unverified | any

--format <output_format>

Output format.

Default:

'text'

Options:

text | json

--strict-annotations

Exit 1 if any annotation finding surfaced (composable with –fail-on=stale).

--full

Recompute every node from a re-hash of every file, instead of only what changed since the last check.

Arguments

PROJECT_ROOT

Required argument

mark-clean

Mark NODE_ID as manually verified clean (MANUAL_VERIFIED).

Usage

axiom-graph mark-clean [OPTIONS] NODE_ID PROJECT_ROOT

Options

--reason <reason>

Why the documentation is still accurate.

Arguments

NODE_ID

Required argument

PROJECT_ROOT

Required argument

checkout

Copy the axiom-graph DB into WORKTREE_PATH via VACUUM INTO.

Usage

axiom-graph checkout [OPTIONS] WORKTREE_PATH

Options

-p, --project-root <project_root>

Source project root.

--force

Overwrite existing DB in target.

Arguments

WORKTREE_PATH

Required argument