xray

Overview ¶

Command recall is a local code-intelligence substrate: it parses repositories, documentation and Kubernetes manifests into a semantic graph, snapshots that graph to disk, and serves retrieval over MCP so a coding agent can ask structural questions — who calls this, what breaks if I change it, why was this decided — instead of grepping.

Everything is local. Embeddings go to an OpenAI-compatible endpoint you run (llama.cpp, Ollama, vLLM, LM Studio); nothing else leaves the machine.

Which subcommands a build carries depends on CGO, because only the Tree-sitter parser needs a C toolchain:

static build (CGO_ENABLED=0)
  xray graph serve-snapshots   serve read tools from pre-built snapshots
  xray graph servicemap        build a service-dependency graph from a catalog
  xray graph update|status|build   drive a running server (editor/agent hooks)
  xray graph search <query>    search the snapshots from the shell, no server
  xray graph impact <qn>...    blast radius of changing symbols, read from a snapshot
  xray graph services <snap>   derive a service catalog from a code map
  xray graph install           drop skills + hook into a repo's .claude/
  xray graph dump <snapshot>   inspect a snapshot: summary, header, vectors, JSON
  xray graph keygen            generate an age identity for encrypted snapshots

cgo build (CGO_ENABLED=1 — the default for `make build`)
  everything above, plus:
  xray graph serve             parse + embed live, serve MCP
  xray graph snapshot          build offline .graph.gob.gz snapshots
  xray graph dump <repo-dir>   parse a tree and print/JSON its graph

The parse modes are stubbed in the static build (parse_nocgo.go, dump_parse_nocgo.go) and exit with a message pointing at the CGO build, rather than silently missing.

`xray graph dump <target>` — look at a graph without a server.

The target is either a REPOSITORY DIRECTORY, which is parsed on the spot (the cheapest way to see what the extractors pull out of a tree — no embedder, no index; needs the CGO build because it parses), or a SNAPSHOT FILE (<label>.graph.gob.gz), which is read directly (internal/engine only, so it works in the static build too). Options pick the view:

(default)   header line + graph summary: counts by kind, sample nodes/edges
-header     the snapshot header alone — fingerprint, counts, routing summary —
            without decoding the body, so it stays cheap on a big map
-vectors    the embedding cache: one line per vector (-grep/-limit/-n)
-routing    the header's routing vector (the embedded summary)
-json       the selected view as JSON instead of text

Why the vector view exists: the cache in a snapshot is keyed by the embedded TEXT (index.nodeText: signature + path + a bounded body slice), not by node identity, because every rebuild constructs fresh nodes. So "what exactly was embedded for this node?" and "did the rebuild hit the cache or re-embed?" can only be answered by looking at the cache keys themselves — and before this that meant a throwaway Go program each time. -header prints the fingerprint, which is what to check BEFORE loading a snapshot under a server built at different dims: a Dims mismatch is a hard rejection at load, a model-name mismatch only warns, and neither is obvious from the file name.