memtrace embed

Inspect and switch the embedding provider — local ONNX presets or a BYO OpenAI-compatible remote endpoint — with a guarded reset flow when the vector dimension changes.

Usage#

memtrace embed manages Memtrace's persistent embedder configuration: which provider (local ONNX presets or an OpenAI-compatible remote endpoint), which model, and what vector dimensionality. Settings are written to a TOML config file — per-user or per-workspace — and resolved through a strict precedence chain: workspace file > home file > env vars > built-in default (local jina-code, 768d).

Because a MemDB HNSW index cannot mix vector dimensions, switching to a model with a different dim triggers a guarded reset-and-reindex flow rather than silently corrupting the index.

Local presets#

Four local presets are built in. embed set <preset> always sets provider=local and clears any remote provider config.

list & status#

Prints the four local presets with their dims and blurbs, followed by the active model/provider/dim and where the config came from (workspace file, home file, env, or built-in default).

Shows the fully resolved picture:

• Provider, model, dim, and config location.
• The live MemDB dim with a (match) or (MISMATCH) indicator.
• The last health-check result read from ~/.memtrace/last_health.json.
• Remote-provider details (url, request_timeout_ms, max_batch, api_key_env set/unset) when provider is openai-compat.
• A note when MEMTRACE_EMBED_MODEL / MEMTRACE_VECTOR_DIMS env overrides are active.

set#

Switches the persistent embedder config to one of the local presets. On success it saves the config atomically — writes a .toml.tmp file in the same directory, then renames — to ~/.memtrace/config.toml, or, with --workspace, to <workspace>/.memtrace/embed.toml — creating parent directories as needed — and prints > Configured: <model> (<provider>, <dim>d). Wrote <path>..

--workspace requires a .memtrace-workspace marker file at or above the current directory (or the active workspace override) whose membership actually claims the search root; otherwise it errors and asks you to choose a workspace first or omit the flag. The marker itself is a small file, not a directory — the config still lives at <workspace>/.memtrace/embed.toml.

Remote (BYO) providers#

--remote openai-compat is the only supported remote kind — any other value errors with "Supported: openai-compat". This is how you point Memtrace at a self-hosted or hosted OpenAI-compatible embeddings endpoint: Ollama, Infinity, TEI, vLLM, LM Studio, or a hosted provider like OpenAI or Voyage behind an API key.

Without --dim, set sends a one-shot probe request to <url>/embeddings — body {"input":["probe"],"model":"<name>"}, plus Bearer auth if --api-key-env resolves a non-empty value — and records the length of data[0].embedding as the config dim. A non-2xx status, non-JSON body, or missing embedding fails the command (exit 2) and nothing is written.

If --api-key-env's variable is unset or empty at set-time, a warning prints to stderr but the config is still written — requests simply go out unauthenticated, which suits local Infinity/LM Studio setups with no auth in front of them.

--dim N pins the dimensionality instead of probing, and is also forwarded to the provider as a Matryoshka truncation request: OpenAI-style endpoints get dimensions: N, Voyage-hosted endpoints (host contains voyageai.com) get output_dimension: N instead, since Voyage 400s on an unrecognized argument.

Dim-mismatch reset flow#

The new config's dim is compared against the live MemDB dim. If they differ, an interactive prompt offers [r] Reset + reindex now / [c] Cancel (config NOT written) — but only when both stdin and stdout are TTYs. In a non-TTY context (CI, pipelines) the command instead errors with "dim mismatch detected and stdin is not a TTY" and exits 2, telling you to re-run with --yes-reset or --no-reset. When no MemDB dim is known yet, no reset is needed and the config is written directly.

Accepting the reset — via r or --yes-reset — prints a loud red stderr banner naming the exact directory (! ABOUT TO WIPE MEMDB DATA DIR: <path>), then runs the shared reset routine against that same path: stops OS supervisors (launchd/systemd), kills the daemon PID (SIGTERM) and anything on the UI port, then wipes the local MemDB data dir. The reset targets the exact data dir that produced the measured MemDB dim, not a newly resolved path from env/workspace.

test & cache-status#

Probes the currently active provider and prints > OK provider=... dim=... latency=...ms. For provider=local it runs a real embedding through the in-process worker — this can take 60s+ on a cold start while the model loads. For openai-compat it POSTs a single-input probe to the configured endpoint and fails if the returned dim differs from the configured dim. The result is persisted to ~/.memtrace/last_health.json, which embed status reads back.

Reports the on-disk embedding cache at ~/.memtrace/embed-cache/: total size and entry count, the configured cap (MEMTRACE_EMBED_CACHE_CAP_MB, default 2048 MB, 0 = disabled), the session hit rate, and eviction counters. Hit/miss counters are process-local, so a fresh invocation shows "(no lookups this session)".

Flags#

Environment variables#

Gotchas#

Exit codes: 0 on success (including help/list/status/cache-status); 1 when you cancel a dim-mismatch reset or embed test fails; 2 for argv parse errors and all other set failures (unknown preset/remote kind, invalid URL, missing model, no workspace marker, non-interactive dim mismatch, probe/save failures, conflicting reset flags).

Examples#

$ memtrace embed list
# See the four local presets and which config is currently active.

$ memtrace embed status
# Full resolved view: provider, model, dim, config location,
# live MemDB dim match/mismatch, last health-check result.

$ memtrace embed set bge-small
# Switch to the smaller/faster 384d local preset.
# Prompts [r]eset/[c]ancel if your MemDB was built at a different dim.

$ memtrace embed set bge-small --yes-reset
# Same switch for scripts/CI: skips the prompt, wipes the MemDB data dir
# (loud stderr warning shows the exact path), and writes the config.

$ memtrace embed set --remote openai-compat --url http://localhost:11434/v1 --model nomic-embed-text
# Point at a self-hosted OpenAI-compatible endpoint (Ollama, Infinity, TEI, vLLM, LM Studio).
# The dim is auto-discovered with a one-shot probe.

$ memtrace embed set --remote openai-compat --url https://api.openai.com/v1 \
    --model text-embedding-3-small --api-key-env OPENAI_API_KEY --dim 768
# Hosted provider with auth from an env var; --dim 768 pins the config dim
# and requests Matryoshka truncation from the provider.

$ memtrace embed set jina-code --workspace
# Write the config to <workspace>/.memtrace/embed.toml
# (requires a .memtrace-workspace marker) so only this workspace uses it.

$ memtrace embed test
# Probe the active provider end-to-end; prints dim + latency
# and records the result in ~/.memtrace/last_health.json.

$ memtrace embed cache-status
# Inspect the on-disk embedding cache size, cap, hit rate, and evictions.

See also Embedding providers for local vs remote choice, provider tables, cost/privacy, and Matryoshka dims, memtrace warmup to pre-pay the model-download and session-init cost before switching, memtrace start, memtrace index, memtrace reset.