Environment variables reference
June 7, 2026 · View on GitHub
Every env var Memtrace reads, what it does, and the default. Grouped by what you'd reach for them for. Most users never set any of these — the defaults auto-tune to your machine.
Quick index
- Transport + ports
- On-disk locations
- Embedding pipeline
- Reranker
- Search / retrieval tuning
- Resource caps
- Install / uninstall lifecycle (v0.3.89)
- Watch persistence (v0.3.89)
- Headless / browser (v0.6.10)
- Legacy daemon lifecycle (removed v0.6.10)
- MemDB connection (advanced)
- Telemetry + auth
Transport + ports
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_TRANSPORT | stdio | How memtrace mcp talks to its agent. See mcp-and-transports.md. Values: stdio, streamable-http, sse (alias for streamable-http), http (alias for streamable-http). Anything else is rejected with a clear error since v0.3.32. |
MEMTRACE_PORT | 3000 | When transport is HTTP, the port memtrace mcp binds. |
MEMTRACE_UI_PORT | 3030 | Local HTTP API + dashboard port while memtrace start (or an attached owner) is running. |
MEMTRACE_UI_HOST | 127.0.0.1 | Bind address for the HTTP API. Set to 0.0.0.0 only when you intentionally need remote/VM/container exposure. |
MEMTRACE_HEADLESS | (unset) | Set to 1 to skip auto-opening a browser tab on memtrace start. The API stays bound on MEMTRACE_UI_PORT. Same as --headless. |
MEMTRACE_NO_UI | (unset) | Deprecated alias for MEMTRACE_HEADLESS (skips browser only — does not disable the HTTP API). |
MEMTRACE_NO_BROWSER | (unset) | Deprecated alias for MEMTRACE_HEADLESS. Prefer MEMTRACE_HEADLESS=1 or memtrace start --headless. |
MEMTRACE_WS_PORT | 3031 | Internal WebSocket bus that pushes index events to the UI. Don't change unless 3031 is taken. |
On-disk locations
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_DATA_DIR | <cwd>/.memtrace | Per-project indexer state. Override to put it elsewhere. |
MEMTRACE_MEMDB_DATA_DIR | <repo-root>/.memdb | The MemDB graph data dir. Anchored to the git root if there is one, otherwise the cwd. Override with an absolute path for shared / CI setups. |
FASTEMBED_CACHE_DIR | ~/.memtrace/fastembed_cache | Where downloaded embedding models live. |
MEMTRACE_DEFAULT_REPO | (unset) | If set, every tool call without a repo_id argument uses this. Convenient for single-repo workflows. |
MEMTRACE_SESSION_LEDGER | ~/.memtrace/session-ledger.jsonl | (v0.3.89) Override the JSONL value ledger path. The default is user-global so memtrace mcp (agent-launched, any cwd) and memtrace start (run from your repo) write to / read from the same file regardless of where each process started. Set to an absolute path if you want per-workspace isolation. |
Embedding pipeline
New CLI surface — most of the knobs below now have a friendlier wrapper:
memtrace embed set <preset>ormemtrace embed set --remote …writes a persistent config so you don't have to re-export env vars on every shell. Seeembedding-providers.mdfor the full command tour. The env vars listed here still work as a transient escape hatch — useful in CI — but the CLI is the recommended path for everyone else.
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_EMBED_MODEL | jina-code (jinaai/jina-embeddings-v2-base-code, 768d) | Model to use. Other accepted values: bge-small (384d, ~140 MB — legacy rollback), bge-base (768d, ~440 MB), nomic (768d). |
MEMTRACE_EMBED_QUANT | auto-picked: int8 on Apple Silicon (any tier), fp32 on Heavy tier elsewhere, int8 on Standard / Light | Embedding quantisation. Force with int8 or fp32. (v0.3.83) Apple Silicon now defaults to int8 for every tier — restores pre-f0fcf221 performance characteristics on M-Max / M-Ultra hosts where fp32 fell back to the slow CoreML CPU path (the Apple Neural Engine only accelerates int8). Set MEMTRACE_EMBED_QUANT=fp32 to opt back into fp32 on Apple Silicon (e.g. for a recall-vs-speed benchmark). Workstation Linux / Windows on Heavy tier are unchanged — CUDA / DirectML still accelerates fp32 there. |
MEMTRACE_VECTOR_DIMS | model-derived (e.g. 768 for jina-code, 384 for bge-small, 1024 for voyage-code-3) | Vector dimensionality of the HNSW index. When unset, derived from the active model so MEMTRACE_EMBED_MODEL=bge-small memtrace index . now works on a fresh install without also setting this var. Explicit values still override. Must match the active model's output dim — switching models with a mismatch raises a clear error pointing at memtrace embed set. |
MEMTRACE_EMBED_INTRA_OP_THREADS | tier-aware (1 / 2 / 4 for Light / Standard / Heavy) | Cap on ORT intra-op threads. Single biggest lever for memory on tight machines. |
MEMTRACE_EMBED_BATCH_SIZE | tier-aware (8 / 16 / 64 for Light / Standard / Heavy) | Per-batch size handed to the embedder. Memory scales linearly with this. Smaller batches finish faster per call, which matters on slow CPU paths (see MEMTRACE_EMBED_BATCH_TIMEOUT_SECS). |
MEMTRACE_EMBED_BATCH_TIMEOUT_SECS | 60 | Per-batch wall-clock ceiling. When exceeded, the embedding worker is abandoned and respawned on the next call (the bootstrap is self-healing — it just retries). On slow CPU paths (pre-AVX2 hosts: Intel Ivy Bridge / Xeon E5 v2 and older, AMD pre-Excavator) bump to 240 or higher; you'll see the warning "Embedding batch timed out after 60s …" if you need it. |
MEMTRACE_EMBED_TIMEOUT_DEBUG | (unset) | Set to 1 to log the offending input previews when a batch times out. Useful for diagnosing whether a single very long symbol body is dragging an otherwise fast batch over the limit. Off by default — these logs include source snippets. |
MEMTRACE_EMBED_RSS_LIMIT_GB | tier-aware (3 / 6 / 10 / 20 GB) | Soft RSS ceiling on the embed process that triggers back-pressure when exceeded. Set to 0 to disable the check. |
MEMTRACE_EMBED_PRESSURE | warn | (v0.3.82) System-pressure gate threshold for local embedding. Values: off (no gating), normal (block on any pressure), warn (block on Warn/Critical), critical (block only on Critical). The probe reads system-wide free + compressor + swap-rate (Mach host_statistics64 on macOS, /proc/meminfo on Linux, GlobalMemoryStatusEx on Windows). Sustained Critical pressure for 60 s consecutive trips a circuit breaker; daemon exits 75 with a clear banner instead of hanging silently. Remote providers are unaffected — when you've configured a remote embedder (OpenAI / Voyage / Ollama etc. via memtrace embed set --remote …), the gate is bypassed because the inference happens off-host and local pressure is irrelevant. |
MEMTRACE_EMBED_MIN_LINES | 4 | Don't embed symbols with fewer body lines than this. Prevents wasting cache on trivial helpers. |
MEMTRACE_LONGFN_CHUNK_THRESHOLD | 80 | (v0.3.82) Functions with more body lines than this are embedded as overlapping sub-spans rather than one blob. Improves recall on natural-language queries that match content deep inside long functions. Set to a very large number (e.g. 100000) to disable. |
MEMTRACE_LONGFN_CHUNK_SIZE | 60 | Sub-span size when chunking. |
MEMTRACE_LONGFN_CHUNK_OVERLAP | 20 | Sub-span overlap when chunking. |
MEMTRACE_FIELD_BOOST_BODY_STRINGS | 0.5 | (v0.3.82) BM25 weight on the new body_strings field (function-body string literals extracted at index time). Improves recall on natural-language → log-line queries. |
MEMTRACE_DISABLE_COREML | (unset) | Set to 1 on Apple Silicon to force CPU execution provider instead of CoreML / ANE. Useful if CoreML's first-run graph compile hangs on your machine. |
MEMTRACE_TIER | auto-detected (light / standard / heavy) | Force the host tier instead of letting Memtrace pick from RAM + CPU + accelerator signals. |
MEMTRACE_SKIP_EMBED | (unset) | Set to 1 to disable all embedding (index, watcher, semantic search). Structural graph tools still work. |
MEMTRACE_SKIP_WATCHER_EMBED | (unset) | Set to 1 to disable per-save watcher embedding only; index-time embedding still runs. |
Reranker
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_RERANK | on | Enable / disable cross-encoder rerank in find_code. Set to off for a pure BM25 + vector pipeline (~3–4 pp lower acc@1 but ~400 ms faster per query). |
Search / retrieval tuning
You typically don't need these. They exist for benchmarking and for edge cases where you want to bias the ranking yourself.
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_RRF_K | 60 | Reciprocal Rank Fusion constant. Smaller = more aggressive top-K; larger = flatter. |
MEMTRACE_RRF_BM25_WEIGHT | 2.0 | Weight on the BM25 leg in RRF. |
MEMTRACE_RRF_VECTOR_WEIGHT | 1.0 | Weight on the vector leg. |
MEMTRACE_RRF_GRAPH_WEIGHT | 0.75 | Weight on the graph signal. |
MEMTRACE_RRF_EXACT_WEIGHT | tuned default | Weight applied to exact-name matches before fusion. |
Resource caps
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_MAX_THREADS | n-2 for memtrace index, n/2 for memtrace start | Rayon parse-thread pool size. Useful to leave cores free for your editor. |
MEMTRACE_UNIFIED_CACHE_MB | 256 | (v0.4.60) Single in-RAM hot-cache budget shared across the embed-vector and backend page-cache layers (moka W-TinyLFU eviction). Defaulting to 256 MB caps the daemon's discretionary RAM at a known number; raise to 512 / 1024 on hosts with RAM headroom for a higher hit rate. Set 0 to disable the cache entirely. Replaces a set of per-subsystem caches that compounded silently. |
MEMTRACE_ORT_LOW_RSS | 0 | (v0.4.60) Opt-in ORT memory-arena toggle. When 1, every ort::Session::builder() site (rerank, splade, embedder) calls .with_memory_pattern(false), which releases CPU activation arena between batches. Cites microsoft/onnxruntime#11627. Empirical impact on our shipping models: −2.7% peak RSS for −19% throughput on the concurrent rerank+embed workload — default OFF because that trade is bad on our model sizes (34 MB int8 reranker + 140 MB int8 embedder). Turn ON only if you're running much smaller custom models where the arena dwarfs the model. |
Workspace daemon (v0.3.82)
The --workspace daemon now auto-watches .git/refs/heads/<active_branch> for new commits in addition to source files. A fresh git commit is picked up within 5 s without any explicit ping.
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_GIT_REF_WATCH | on (for --workspace), off otherwise | Enable / disable the git-ref watcher. |
MEMTRACE_GIT_REF_WATCH_DEBOUNCE_MS | 2000 | Debounce window for rapid ref changes (interactive rebase = many ref updates collapse to one delta sync after this settles). |
Branch switch (git checkout other-branch) re-targets the watcher to the new active ref without restart. Detached-HEAD doesn't crash — the watcher logs once and falls back to the file-save trigger.
Pre-commit hook (v0.3.82 — now opt-in)
⚠️ Breaking from prior versions: memtrace install no longer auto-installs the pre-commit hook. To opt in: memtrace install-hooks --pre-commit. To remove an existing one: memtrace uninstall-hooks.
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_PRECOMMIT | (unset) | Set to off / 0 / false / no / disabled for a silent no-op (kill switch checked in bash before the binary spawns, so even a broken binary can't block a commit). |
MEMTRACE_PRECOMMIT_MODE | blocking | blocking (default — sync, 1.5 s capped) OR agent (fire-and-forget — forks daemon-ping detached and exits in ~15 ms). For agentic CI / Orbit-style pipelines, set to agent. |
MEMTRACE_PRECOMMIT_TIMEOUT_MS | 1500 | Hard wall-clock cap on the blocking-mode hook (hook also wraps in || true so it never blocks the commit even on timeout). |
MEMTRACE_PRECOMMIT_MAX_RSS_MB | 512 | RLIMIT_AS cap on the pre-commit binary (Linux enforced; macOS no-op per kernel — documented). Prevents OOM. Set to 0 to disable. |
MEMTRACE_PRECOMMIT_MAX_DIFF_BYTES | 1048576 | If git diff --cached exceeds this, skip analysis (huge commits aren't worth the wait). Set to 0 to disable. |
MEMTRACE_PRECOMMIT_MAX_SYMBOLS | 500 | If parsed-affected-symbols list exceeds this, truncate (don't try to render warnings for 5,000 symbols). Set to 0 to disable. |
Claude Code hooks (v0.3.82)
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_HOOK_MODE | advisory | Set to off for unconditional no-op of the UserPromptSubmit hook. |
MEMTRACE_HOOK_DEBOUNCE_SECS | 120 | Per-session debounce window. After the hook fires once for a session, suppresses further fires within this window. Set to 0 to disable debounce (every message fires). |
MEMTRACE_HEALTH_URL | http://localhost:3030/api/health | Where the Claude Code UserPromptSubmit hook probes runtime liveness. Override for non-default UI ports. |
Session ID resolution (used to key the lock file at ~/.memtrace/hook-debounce/<session_id>.lock):
CLAUDE_SESSION_IDenv (if Claude Code sets it)CLAUDE_CONVERSATION_IDenv- Fallback: SHA-1 of
PPID + parent process start-time
Pre-push fortress hook (v0.3.82)
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_PREPUSH | (unset) | Set to off / 0 / false / no / disabled for kill switch on the pre-push fortress hook (installed via memtrace install-hooks --pre-push). |
Install / uninstall lifecycle (v0.3.89)
After @Badmrpotatohead's report that npm install -g memtrace@latest was wiping ~/.memtrace/ on upgrade, the uninstall path now distinguishes "user asked to uninstall" from "npm is upgrading me". User data is preserved by default — MEMTRACE_PURGE_DATA=1 is the explicit opt-in for a full wipe.
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_PURGE_DATA | (unset) | Set to 1 to allow npm uninstall -g memtrace to remove ~/.memtrace/ (session ledger, embed cache, auth tokens, telemetry buffer, logs). Without this, uninstall preserves user data. Has no effect during upgrades — the lifecycle gate refuses to purge during install/update/upgrade even if this var is set. |
MEMTRACE_UNINSTALL_PURGE_DATA | (unset) | Alias for the above. |
MEMTRACE_INSTALL_PARENT | (set internally) | bin/memtrace.js sets this to 1 before spawning the npm self-upgrade child process so the inner uninstall lifecycle knows it's an upgrade, not an explicit uninstall. Agents shouldn't set this manually. |
Watch persistence (v0.3.89)
After @Magalz's report that watch_directory registrations vanished on MCP disconnect, watches now persist to ~/.memtrace/watches.json and are restored on every MCP boot.
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_NO_WATCH_RESTORE | (unset) | Set to 1 to skip the watch-list restore on MCP startup. Useful if you have stale watch state you want forgotten — just unset it again on the next start to re-enable restore. |
The watch file is a JSON array of { path, repo_id, registered_at, origin } objects; origin is "manual" for entries you registered explicitly via watch_directory and "restored" for entries that were re-armed from a prior session.
Headless / browser (v0.6.10)
memtrace start --headless (or MEMTRACE_HEADLESS=1) keeps the HTTP API on :3030 but skips auto-opening a browser tab. This is the recommended mode for Orbit, CI, and agent hosts that need health/search endpoints without a GUI session.
Legacy names --no-ui, --no-browser, MEMTRACE_NO_UI, and MEMTRACE_NO_BROWSER still work as aliases and print a one-time deprecation note.
Legacy daemon lifecycle (removed v0.6.10)
memtrace service / memtrace daemon install|start|status|stop was removed in 0.6.10. Use memtrace start (foreground or --headless in tmux/screen/nohup) or memtrace mcp for agent workflows. memtrace stop still unloads legacy launchd/systemd/Windows service registrations if an older install left them behind.
The following env vars are obsolete and ignored by current binaries:
| Var | Was used for |
|---|---|
MEMTRACE_DAEMON_HEALTH_TIMEOUT_MS | memtrace daemon start health poll (removed) |
MEMTRACE_DAEMON_HEALTH_INTERVAL_MS | memtrace daemon start health poll interval (removed) |
MEMTRACE_LOGS_DIR | Override for ~/.memtrace/logs/daemon.log (file logging removed with OS service install) |
MemDB connection (advanced)
You almost certainly don't touch these. They exist for people running Memtrace against a remote MemDB cluster instead of the embedded default.
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_MEMDB_MODE | embedded (auto-detected from MEMDB_ENDPOINT if set) | embedded or remote. |
MEMTRACE_MEMDB_ENDPOINT | http://127.0.0.1:50051 | Remote MemDB gRPC endpoint. Setting this to anything other than the loopback default flips mode to remote. |
MEMTRACE_MEMDB_LOOPBACK_PORT | 50051 | When memtrace start runs in embedded mode, the loopback gRPC port the in-process MemDB binds. Other processes (memtrace mcp, MemFleet broker) attach here. Set to 0 for ephemeral. |
MEMTRACE_MEMDB_DB | memtrace | The database name within MemDB. |
MEMTRACE_MEMDB_AUTH_TOKEN | (unset) | Bearer token for remote mode. Ignored for embedded. |
Telemetry + auth
| Var | Default | Purpose |
|---|---|---|
MEMTRACE_TELEMETRY | (unset, treated as on) | The user-facing kill switch. Set to off / 0 / false / disabled / no to disable product telemetry. See TELEMETRY.md and privacy-and-telemetry.md. |
MEMTRACE_TELEMETRY_DISABLED | (unset) | Hard override. Set to 1 to block telemetry unconditionally — takes precedence over MEMTRACE_TELEMETRY and any other state. Recommended for CI / locked-down environments. |
MEMTRACE_NO_REMOTE_RECEIPT | (unset) | Set to 1 to omit the weekly-receipt symbol-name surface from heartbeats. Even if the user opted in to weekly emails on memtrace.io, this env var ensures no symbol names cross the network from this machine. The cloud then has nothing concrete to anchor an email and skips the send for that week. See privacy-and-telemetry.md §3 and telemetry-compliance-datasheet.md §6.4. |
MEMTRACE_LICENSE_KEY | (unset) | Optional bearer-style license key for non-interactive (CI / server) authentication. Most users authenticate via device flow on first run instead. |
Redis / pub-sub (multi-process deployments)
Memtrace can broadcast indexing events to a Redis channel so detached UIs and orchestrators can subscribe without polling.
| Var | Default | Purpose |
|---|---|---|
REDIS_URL | (unset) | Where to publish memtrace:indexed events. Empty = no publish; in-process WebSocket is still used. |
VALKEY_URL | (unset) | Same as REDIS_URL. Convenience alias if you're on Valkey. |
Internal / undocumented
There are a few env vars used by tests and CI that aren't part of the
stable API and may change without notice. They're all prefixed
MEMTRACE_TEST_* or RUST_LOG. Don't depend on them in production.
Examples
A 16 GB laptop running on battery, wanting maximum thrift:
export MEMTRACE_TIER=light
export MEMTRACE_RERANK=off
memtrace start
A 64 GB workstation building agent infra, wanting maximum speed and recall:
export MEMTRACE_TIER=heavy
export MEMTRACE_TRANSPORT=streamable-http
export MEMTRACE_PORT=4848
memtrace start
memtrace mcp # binds the HTTP server on :4848
A CI pipeline that needs deterministic behaviour:
export MEMTRACE_LICENSE_KEY=<your CI key>
export MEMTRACE_TELEMETRY_DISABLED=1
export MEMTRACE_DISABLE_COREML=1 # macOS CI runners
memtrace index .
A small Raspberry Pi 4 (4 GB) — tight RAM, no rerank:
export MEMTRACE_TIER=light
export MEMTRACE_EMBED_MODEL=bge-small # smaller model, 384d
export MEMTRACE_VECTOR_DIMS=384
export MEMTRACE_RERANK=off
export MEMTRACE_EMBED_BATCH_SIZE=4
memtrace start
See performance-tuning.md for more recipes.