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
| Subcommand | Description |
|---|---|
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 status | Show 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 ID | Dim | Params | Notes |
|---|---|---|---|
arctic-embed-m-v1.5 | 768 | 109M | Recommended. Best retrieval accuracy in our benchmarks. Snowflake arctic-embed, Apache-2.0. |
arctic-embed-m-v1.5-256 | 256 | 109M | arctic-embed-m truncated to 256 dimensions (Matryoshka). About 2.7x smaller vectors with minimal accuracy loss. |
bge-small-en-v1.5 | 384 | 33M | Fastest. Good for everyday use on any machine. |
bge-base-en-v1.5 | 768 | 109M | Stronger on technical vocabulary. About 4x slower reindex than small. |
bge-large-en-v1.5 | 1024 | 335M | Maximum 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:
| Flag | Description |
|---|---|
--backend <id> | Backend ID to install (run travsr embed list to see options). Wins over --yes when both are given |
--yes, --no-interactive | Install the recommended model without prompting, for scripts and CI |
--reinstall | Re-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:
| Flag | Description |
|---|---|
--db <path> | Path to graph.db (defaults to .travsr/graph.db in the nearest git root) |
--rebuild | Rebuild 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
| Flag | Description |
|---|---|
--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 |
--global | Persist 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
| Flag | Description |
|---|---|
--apply | Actually 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:
| Flag | Description |
|---|---|
--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.