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>] [--reinstall] | Download and activate a backend |
travsr embed reindex [--db <path>] [--phase1 <N>] | Embed all un-embedded nodes in the repo graph |
travsr embed status | Show the active model and binary status |
travsr embed switch <backend> | Make an already-installed backend active |
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. Defaults
to the first catalog entry if --backend is omitted. 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) |
--reinstall | Re-download even if already installed |
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) |
--phase1 <N> | Only embed symbol nodes with shell_number >= N (high-centrality first pass) |
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.
$ travsr embed switch bge-small-en-v1.5
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) |