Skip to main content

atomic query

Query the knowledge graph.

Synopsis​

atomic query <SUBCOMMAND>
atomic query search <QUERY> [-k <LIMIT>] [-t <KIND>] [--json]
atomic query neighbors <NODE_ID> [-d <DEPTH>] [--json]
atomic query callers <ENTITY_ID> [--json]
atomic query entities <PATH> [--json]
atomic query code <PATTERN> [-g <PATH_FILTER>] [-t <FILE_TYPE>] [-n <MAX>] [-i] [--json]
atomic query graph <QUERY> [--depth <DEPTH>] [-o <FILE>] [--json | --dot]
atomic query index [--rebuild] [--stats]
atomic query embed [-p <PATH>]
atomic query enrich [--change <FULL_HASH>] [--rebuild]
atomic query reindex
atomic query plan [--json]
atomic query ask <QUESTION> [-t <MAX_TURNS>] [--json]

Description​

atomic query is the read surface of Atomic's knowledge graph (KG), a graph that connects code entities, files, changes, views, and vault content (memories, intents, goals) into one searchable structure. The graph is fed from three directions:

  • VCS data — recorded changes, files, and views (via enrich)
  • Code structure — tree-sitter entities (functions, classes, types), parsed on demand
  • Vault content — memories, intents, and goals (atomic vault)

Identifier Requirements​

Several subcommands take node or entity IDs. IDs are namespaced — use the right namespace and the right discovery command:

ID typeFormatWhere to find it
KG node IDchange:abc123, file:src/auth.rs, intent:PIMO-1, memory:…, view:…query search
Entity IDentity:src/auth.rs:verify:42 (file : name : line)query entities <PATH> or query search --kind entity
Change hashfull hash only for enrich --changeatomic log --full-hash

Subcommands​

Search & Exploration​

query search — Search the Graph​

Keyword search over node IDs, labels, and summaries.

Synopsis​

atomic query search <QUERY> [OPTIONS]

Arguments​

<QUERY> — Search query text.

Options​

OptionDescription
-k, --limit <LIMIT>Maximum results (default: 10)
-t, --kind <KIND>Filter by node kind (change, entity, file, view, memory, intent, goal)
-p, --pool <POOL>Candidate pool size
--jsonOutput as JSON

Examples​

# Find nodes related to authentication
atomic query search "authentication tokens"

# Find entity nodes only, as JSON
atomic query search "verify" --kind entity --json

query neighbors — Get a Node's Neighborhood​

Synopsis​

atomic query neighbors <NODE_ID> [OPTIONS]

Arguments​

<NODE_ID> — A namespaced KG node ID, e.g. change:abc123, file:src/auth.rs, intent:PIMO-1 (see Identifier Requirements).

Options​

OptionDescription
-d, --depth <DEPTH>Traversal depth (1 or 2) (default: 1)
--jsonOutput as JSON

Examples​

# What is connected to this intent?
atomic query neighbors intent:PIMO-1

# Two hops out, machine-readable
atomic query neighbors file:src/auth.rs --depth 2 --json

query callers — Find Callers of an Entity​

Synopsis​

atomic query callers <ENTITY_ID> [OPTIONS]

Arguments​

<ENTITY_ID> — Full entity node ID, e.g. entity:src/auth.rs:verify:42. Get entity IDs with atomic query entities <path>.

Options​

OptionDescription
--jsonOutput as JSON

Examples​

atomic query entities src/auth.rs        # list entities and their IDs
atomic query callers entity:src/auth.rs:verify:42

query entities — List Entities in a File​

List tree-sitter entities (functions, classes, types) in a source file.

Synopsis​

atomic query entities <PATH> [OPTIONS]

Arguments​

<PATH> — File path, relative to the repository root.

Options​

OptionDescription
--jsonOutput as JSON

--json is strict about the path: a file Atomic cannot parse (anything that is not a supported source file) exits non-zero with Unsupported file type: <path> on stderr and prints nothing on stdout, so a caller never mistakes a bad path for an empty result. Without --json the same message is printed and the command exits 0.

Examples​

atomic query entities src/auth.rs

query code — Search Source Code Content​

Search the recorded source in your current view (regex supported). Atomic renders file bytes straight from the graph, so no index build or checkout is required.

Only files the current view contains are searched. Ignored files and folders are intentionally excluded — anything matching .gitignore, .ignore, .atomicignore, the global ignore file, or an Atomic-internal path (.atomic/, .git/, .vault/, .atomic-sandbox*), plus files over 10 MiB and binary files, produces no results here. See What's Indexed — and What's Intentionally Excluded for the full policy.

Synopsis​

atomic query code <PATTERN> [OPTIONS]

Arguments​

<PATTERN> — Search pattern (regex supported).

Options​

OptionDescription
-g, --path-filter <PATH_FILTER>Restrict to files matching this path pattern
-t, --file-type <FILE_TYPE>Restrict to a file type (e.g. rs, cpp, py)
-n, --max-results <MAX_RESULTS>Maximum results (default: 30)
-i, --case-insensitiveCase-insensitive search
--jsonOutput as JSON

Examples​

# Find token-issuing code in Rust files
atomic query code "issue_token" -t rs -g "src/"

# Case-insensitive, first 5 hits
atomic query code "BearerAuth" -i -n 5

query graph — Visualize a Query​

Build a visual graph seeded by a search query.

Synopsis​

atomic query graph <QUERY> [OPTIONS]

Arguments​

<QUERY> — Search query to seed the graph.

Options​

OptionDescription
-k, --limit <LIMIT>Maximum seed nodes from search (default: 10)
--depth <DEPTH>Neighbor expansion depth (1 or 2) (default: 1)
-o, --output <FILE>Write output to a file. For HTML output (default), use an .html extension. If omitted, writes to stdout (DOT or JSON) or a temp file (HTML) and opens it
--jsonOutput as JSON (nodes + edges arrays). Always exactly one document: a query that matches nothing still emits {"nodes":[],"edges":[]} — to stdout, or to --output when given — with no diagnostic on stderr
--dotOutput as DOT (Graphviz) format instead of HTML
--max-nodes <MAX_NODES>Maximum nodes in the graph (default: 5000 for HTML, 200 for DOT)
--kinds <KINDS>Node kinds to include, comma-separated (default: all). e.g. module,file,entity for structure only, change,file for history
--changes-per-seed <N>Maximum change nodes per seed during expansion (default: 5; 0 for unlimited). Prevents change history from flooding the graph

Examples​

# Interactive HTML graph of everything around "auth"
atomic query graph "authentication"

# Structure-only DOT graph for Graphviz
atomic query graph "auth" --kinds module,file,entity --dot > auth.dot

query ask — Ask the Knowledge Graph (RAG)​

Ask a natural-language question. The command runs a small agentic loop over KG tools (default 5 turns) and answers using graph content.

Synopsis​

atomic query ask <QUESTION> [OPTIONS]

Arguments​

<QUESTION> — Natural language question.

Options​

OptionDescription
-t, --max-turns <MAX_TURNS>Maximum agentic tool-use turns (default: 5)
--jsonOutput as JSON (includes tool trace)
-v, --verboseShow live tool calls as they execute

Examples​

atomic query ask "which changes touched the token refresh flow?"
atomic query ask "what does intent PIMO-1 cover?" --json

Index Maintenance​

query index — Build the Content Search Index​

Build or update the content search index used by query code.

Ignored files and folders are intentionally excluded from the index: anything matching .gitignore, .ignore, .atomicignore, or the global ignore file, plus Atomic-internal paths (.atomic/, .git/, .vault/, .atomic-sandbox*), plus files over 10 MiB and binary files. Use --rebuild after changing ignore patterns so the index re-applies them.

Synopsis​

atomic query index [OPTIONS]

Options​

OptionDescription
--rebuildFull rebuild instead of incremental update
--statsShow index statistics after building

query embed — Rebuild Embeddings​

Rebuild embeddings for vault content (used by semantic queries).

Synopsis​

atomic query embed [OPTIONS]

Options​

OptionDescription
-p, --path <PATH>Embed only this specific path

query enrich — Enrich the Graph from VCS Data​

Derive KG nodes and edges from VCS data: changes, files, views. Run after recording work to make new changes searchable.

The graph is built from recorded changes, so ignored files and folders are not included: they are never tracked, so they are never recorded. Ignore rules (.gitignore, .ignore, .atomicignore, the global ignore file) plus Atomic-internal paths (.atomic/, .git/, .vault/, .atomic-sandbox*) also filter the file nodes this command derives. A file that was recorded before a pattern started matching it keeps its nodes — pass --rebuild to reconcile them.

Synopsis​

atomic query enrich [OPTIONS]

Options​

OptionDescription
--change <FULL_HASH>Enrich only this exact recorded change (repeat for multiple). Requires the full hash — no prefixes. Get it with atomic log --full-hash. Without this option, all VCS-derived KG data is rebuilt
--rebuildForce a clean rebuild: drop all previously enriched VCS/AST-derived KG nodes (files, modules, views, changes, entities) before re-deriving them

Examples​

# Enrich everything new
atomic query enrich

# Enrich one change (full hash required — no prefixes)
atomic query enrich --change 3f9c2ab1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

query reindex — Rebuild the KG Index​

Rebuild the KG index from all vault entries.

Synopsis​

atomic query reindex

Advanced​

query plan — Execute a Query Plan​

Execute a structured query plan as JSON on stdin. Intended for programmatic use — compose one from query search --json output or write by hand.

Synopsis​

atomic query plan [--json]

Options​

OptionDescription
--jsonOutput as JSON

Examples​

echo '{"query": "..."}' | atomic query plan

See Also​

  • vault — The shared knowledge store feeding the graph
  • log — Change history (source of change hashes)
  • querying-the-graph guide — Getting-started walkthrough