Skip to main content
← CLI Reference

travsr embed

Manage the optional semantic embedding backend. Embeddings power natural-language retrieval: when a backend is active, get_context and search_symbol can seed the graph walk from vector similarity in addition to name and signature matches. Embeddings are entirely optional; Travsr works without them.

The embed sidecar runs ONNX models locally. Model weights are downloaded from HuggingFace into ~/.travsr/models/<backend>/ and the sidecar binary into ~/.travsr/bin/. Vectors are stored in a per-repo HNSW index (.travsr/<model-id>.hnsw.usearch).

Subcommands​

SubcommandDescription
travsr embed list [--json]Show available embedding backends and their install status
travsr embed init [--backend <id>] [--yes] [--reinstall] [--capacity <c>] [-j <N>] [--priority <p>]Download and activate a backend
travsr embed reindex [--db <path>] [--rebuild] [--phase1 <N>] [--capacity <c>] [-j <N>] [--priority <p>]Embed all un-embedded nodes in the repo graph
travsr embed reconfigure [--capacity <c>] [-j <N>] [--priority <p>] [--global] [--db <path>]Change the reindex resource budget and apply it immediately
travsr embed statusShow the active model and binary status
travsr embed switch <backend> [--global]Make an already-installed backend active
travsr embed gc [--apply] [--keep <model-id>]Reclaim disk space held by inactive models. Dry-run by default
travsr embed calibrate [--db <path>]Re-measure model-relative semantic floors on the existing index

travsr embed list​

Lists every backend in the catalog with its install status. Pass --json for machine output used by the VS Code extension.

$ travsr embed list

Available models​

The bundled catalog ships five backends. You can override or add models at runtime, without a recompile, via ~/.travsr/embed_catalog.toml.

Backend IDDimParamsNotes
arctic-embed-m-v1.5768109MRecommended. Best retrieval accuracy in our benchmarks. Snowflake arctic-embed, Apache-2.0.
arctic-embed-m-v1.5-256256109Marctic-embed-m truncated to 256 dimensions (Matryoshka). About 2.7x smaller vectors with minimal accuracy loss.
bge-small-en-v1.538433MFastest. Good for everyday use on any machine.
bge-base-en-v1.5768109MStronger on technical vocabulary. About 4x slower reindex than small.
bge-large-en-v1.51024335MMaximum BGE accuracy. Needs about 1.4 GB RAM.

travsr embed init​

Downloads the sidecar binary and the ONNX model files, then activates the backend. Without --backend, an interactive terminal shows a model menu; --yes skips the menu and installs the recommended default, the first catalog entry (arctic-embed-m-v1.5 in the bundled catalog). After install it embeds the repo inline with a live progress bar.

$ travsr embed init --backend arctic-embed-m-v1.5

Flags:

FlagDescription
--backend <id>Backend ID to install (run travsr embed list to see options). Wins over --yes when both are given
--yes, --no-interactiveInstall the recommended model without prompting, for scripts and CI
--reinstallRe-download even if already installed
--capacity <auto|PCT>Worker budget for the post-install reindex: auto or a percent 1-100. When omitted, an interactive terminal prompts for it; otherwise config, env or the default applies
-j, --jobs <N>Absolute number of parallel embed workers for the post-install reindex
--priority <normal|low|idle>OS scheduling priority for the post-install reindex sidecar

travsr embed reindex​

Embeds all un-embedded nodes in the current repo's graph.db. Skips nodes that already have an embedding for the active backend, so it is safe to run repeatedly.

$ travsr embed reindex

Flags:

FlagDescription
--db <path>Path to graph.db (defaults to .travsr/graph.db in the nearest git root)
--rebuildRebuild every embedding from scratch, replacing the whole index. Use after switching models. Cannot be combined with --phase1
--phase1 <N>Only embed symbol nodes with shell_number >= N (high-centrality first pass)
--capacity <auto|PCT>Worker budget for this run: auto (load-adaptive) or a percent 1-100. Overrides the embed.capacity config for this run only
-j, --jobs <N>Absolute number of parallel embed workers for this run (overrides --capacity)
--priority <normal|low|idle>OS scheduling priority for the embed sidecar this run

travsr embed reconfigure​

Persists a new reindex resource budget to config (this repo's, unless --global), then cancels any in-flight reindex and restarts it with the new settings, resuming from the partial work. At least one of --capacity, -j or --priority is required.

$ travsr embed reconfigure --capacity 50 --priority low
FlagDescription
--capacity <auto|PCT>New worker budget: auto (load-adaptive) or a percent 1-100
-j, --jobs <N>New absolute worker count (overrides --capacity)
--priority <normal|low|idle>New OS scheduling priority for the embed sidecar
--globalPersist to the machine-global config instead of this repo's
--db <path>Path to graph.db (defaults to .travsr/graph.db in the nearest git root)

travsr embed status​

Prints the currently active embedding model and the sidecar binary status.

$ travsr embed status

travsr embed switch​

Switches the active backend to another one that is already installed. Use travsr embed init first if the target backend has not been downloaded. Inside a repository it writes that repository's config (.travsr/embed.toml); pass --global to set the machine-wide default instead.

$ travsr embed switch bge-small-en-v1.5

A switch leaves the previous model's vectors in place. Reclaim them with travsr embed gc.


travsr embed gc​

Reclaims disk space held by inactive embedding models: their vectors in embed.db and their HNSW index files. It is a dry run by default and only reports what would be reclaimed.

$ travsr embed gc # report only
$ travsr embed gc --apply # actually delete
FlagDescription
--applyActually delete. Without it, only report
--keep <model-id>Keep this inactive model's vectors. Repeatable

travsr embed calibrate​

Re-measures the model-relative semantic floors against the existing HNSW index and rewrites the embed_cos_* anchors in graph.db, without re-embedding. Calibration runs automatically after every reindex; run it manually to recalibrate after a model or corpus change that did not go through a reindex.

$ travsr embed calibrate

Flags:

FlagDescription
--db <path>Path to graph.db (defaults to .travsr/graph.db in the nearest git root)

Sidecar version​

travsr embed status ends with the shared sidecars: block, reporting the installed travsr-embed version and whether it meets the version this host requires.

sidecars:
travsr-embed 1.6.0 ok

This exists because install correctness used to be judged by file presence, which never flips false when a better release ships. A cached sidecar three releases behind would run and fail with a cryptic downstream error instead of saying it was too old. A below-floor sidecar is now refused up front, with the reinstall command named. See travsr status for every state the line can report.