Environment variables
The validated reference for every environment variable Memtrace reads — runtime and ports, MemDB, embeddings, MCP, Cortex, git hooks, install, telemetry, and licensing — grouped with defaults.
Every variable below is read directly by the memtrace binary or its npm installer — nothing here is invented or inferred. Where the same setting has both a CLI flag and an env var (like --headless / MEMTRACE_HEADLESS), the env var is the durable way to set it in a shell profile, Docker image, or CI job. Booleans generally accept 1/true/on/yes for "on" and 0/false/off/no for "off" unless noted otherwise.
Runtime & ports#
Controls for memtrace start's network binds, data locations, and process behavior.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_UI_PORT | 3030 | HTTP port for the REST API, WebSocket (/ws), and dashboard UI. If left unset and the port is busy, start scans up to 49 ports above it and binds the first free one with a warning; if you set this var explicitly and it's busy, start fails instead of silently moving. |
MEMTRACE_UI_HOST | 127.0.0.1 | Bind host for the UI/API server. Loopback-only by default for security — set e.g. 0.0.0.0 to expose it on the LAN or a container network intentionally. Blank or whitespace values also fall back to loopback. |
MEMTRACE_PORT | 3000 | HTTP port for the MCP endpoint when MEMTRACE_TRANSPORT is not stdio. A bind failure is a hard error suggesting a free port. |
MEMTRACE_HEADLESS | unset (false) | Env equivalent of --headless: suppresses the automatic browser-tab open only. The HTTP API and dashboard UI still bind and serve exactly as in the default path. (Deprecated aliases MEMTRACE_NO_UI / MEMTRACE_NO_BROWSER do the same thing and print a one-time deprecation note.) |
MEMTRACE_START_FORCE | unset (false) | Env equivalent of --force/--replace: when a live, compatible daemon already owns this workspace, reclaim/replace it instead of exiting with the existing owner's URL. |
MEMTRACE_DEBUG | unset (false) | Env equivalent of --debug: raises tracing/log verbosity for the run. Honors RUST_LOG when set. |
MEMTRACE_DATA_DIR | .memtrace | Memtrace's own data dir (FTS indexes, caches) — resolved against the git repo root (or an ancestor .memtrace-workspace marker), falling back to the current directory only when neither is found. Not literally <cwd>/.memtrace inside a git repo. |
MEMTRACE_MAX_THREADS | auto | Caps rayon parse/index parallelism. memtrace index otherwise uses all performance cores; memtrace start otherwise uses efficiency cores on Apple Silicon (falling back to half of total cores on Intel/unknown hosts). |
MEMTRACE_WORKSPACE_ROOT | unset | Workspace anchor consumed by editor-launched MCP hosts (VS Code, Cursor) alongside --workspace; memtrace start also auto-populates it for child processes when it detects a workspace root. |
MEMTRACE_BLESS_WORKSPACE | unset (false) | Env equivalent of --bless-workspace: pre-answers "yes" to the interactive Folder-Group prompt (≥2 sibling repos, no .git of the cwd's own) instead of requiring a TTY confirmation before sharing one index. |
MemDB#
MemDB is the storage engine behind the knowledge graph. These variables select and locate it — see the knowledge graph for what it stores.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_MEMDB_MODE | local | How this process reaches MemDB. local (default) spawns or adopts a loopback memcore-server sidecar over gRPC; embedded opens the store in-process instead of a sidecar; external connects to an operator-managed remote gRPC endpoint. Legacy aliases: sidecar=local, remote/hosted=external. |
MEMTRACE_MEMDB_DATA_DIR | <git-root-or-cwd>/.memdb | On-disk MemDB data directory. Wiped by memtrace reset or start --clear/--fresh. Also where the workspace-owner state file (daemon-state.json) lives for owner-attach detection. |
MEMTRACE_MEMDB_ENDPOINT | http://127.0.0.1:50051 | MemDB gRPC endpoint pinged at startup in local/external mode. If unreachable, memtrace mcp prints "could not reach MemDB" and exits 1 — in practice this means memtrace start (or an already-listening memcore-server) needs to be running first. |
MEMTRACE_MEMDB_LOOPBACK_PORT | 50051 | Loopback gRPC bind port for the local memcore-server sidecar. External clients (e.g. MemFleet) attach here too. Set to 0 for an ephemeral port. |
MEMTRACE_MEMDB_DB | memtrace | MemDB database name. |
MEMTRACE_MEMCORE_SERVER_PATH | unset (auto-resolved) | Explicit path to the memcore-server sidecar binary for local mode, for custom builds or non-standard install layouts. Memtrace otherwise resolves it next to its own binary. |
MEMTRACE_MEMDB_AUTH_TOKEN | unset | Bearer token for a team/external MemDB session, remote mode only. Precedence is --token flag > this env var > connection-file memdb_token > the token stored in ~/.config/memtrace/credentials.json. Enterprise seat minting remains a compatibility fallback. |
MEMTRACE_MEMDB_AUTH_TOKEN is the env-var way to supply a MemDB bearer token without persisting anything to disk. An administrator can issue a user file through memtrace access; running memtrace connect with that file writes its bearer to ~/.config/memtrace/credentials.json. That stored token is only used when neither --token nor MEMTRACE_MEMDB_AUTH_TOKEN is set.
Embeddings#
Controls for the local ONNX embedding pipeline that powers semantic search. See Embedders for the full provider/preset picture.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_EMBED_MODEL | jina-code | Active embedding preset. jina-code (768d, code-specialised) is the default; rollback options are bge-small (384d), bge-base (768d), and nomic (768d). |
MEMTRACE_VECTOR_DIMS | auto-derived | Vector dimensionality. When unset, it's auto-derived from MEMTRACE_EMBED_MODEL (768 for the default jina-code); an explicit value always overrides the derived dimension. |
MEMTRACE_SKIP_EMBED | unset (false) | Skips the ONNX Runtime dlopen pre-flight and the embedding pipeline entirely — structural (non-semantic) indexing still works. Without it, a missing or broken libonnxruntime makes memtrace start exit with code 75. |
MEMTRACE_SKIP_WATCHER_EMBED | unset (false) | Disables only the live file-watcher's per-save embedding step, while keeping embeddings during a full index. Useful to cut background CPU/model load on a machine doing heavy live editing. |
MEMTRACE_EMBED_IDLE_TIMEOUT_SECS | 120 | How long the in-process embedding model stays loaded after its last use before being released. Raise it (e.g. 3600) to keep the model warm across a long editing session at the cost of resident memory. |
MEMTRACE_ENABLE_COREML | unset (false) | Explicit opt-in to compile and run the embedding model on Apple's Neural Engine via CoreML. Default is CPU-only even on Apple Silicon — this is a genuine opt-in, not part of the default first-run cost. |
Indexing & replay#
Controls for structural indexing, git-history replay, startup auto-indexing, and community detection. These are useful for CI, low-memory machines, and debugging first-run startup cost.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_NO_REPLAY | unset (false) | Skips the git-history replay stage. The current HEAD still indexes, but historicalgit_commit episodes are not replayed into the temporal graph for that run. |
MEMTRACE_FORCE_REPLAY | unset (false) | Ignores the per-branch replay watermark and re-walks the configured replay window, even if Memtrace believes replay is already current. |
MEMTRACE_REPLAY_DAYS | 30 | How many days of git history the replay stage walks. |
MEMTRACE_START_AUTOINDEX | unset (auto) | 0/false/off/no disables the startup structural auto-index entirely; 1/true/on/yes forces it; unset falls back to a large-existing-store size heuristic. |
MEMTRACE_START_AUTOINDEX_LARGE_STORE_MB | 512 | Size threshold (MB) above which startup auto-index is skipped automatically. Set to 0 to disable the size gate. |
MEMTRACE_FORCE_EMBED | unset (false) | Forces the embed pass even when an embed-complete marker exists for the current HEAD; also auto-forced when the HNSW index is detected as degraded. |
MEMTRACE_SKIP_COMMUNITY is not a supported Memtrace environment variable. Community detection is part of the structural indexing pipeline, is surfaced through tools such as list_communities, and is only bypassed by internal diagnostic builds. User installs should treat it as ignored.
MCP#
Controls for memtrace mcp, the server AI coding agents talk to.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_TRANSPORT | stdio | MCP transport. stdio (default) is JSON-RPC over stdio for Claude Code, Codex, Cursor, etc. streamable-http (aliases http, and legacy sse, which prints a deprecation hint) serves MCP over HTTP at http://0.0.0.0:<MEMTRACE_PORT>/mcp for orchestrators multiplexing many agent sessions. Any other value is a fatal error, not a silent fallback to stdio. |
MEMTRACE_MCP_UI | unset (off) | Truthy value has the same effect as memtrace mcp --ui: also start the dashboard/API listener on MEMTRACE_UI_PORT (bound on 0.0.0.0) alongside the otherwise-headless MCP server. A bind failure (e.g. a running memtrace start already owns the port) is silently ignored. |
memtrace mcp is headless by default — no UI port binds unless MEMTRACE_MCP_UI or --ui is set. If a memtrace start runtime already owns the workspace, the MCP process attaches to it and reuses the same MemDB instead of spawning its own.
Cortex#
Cortex decision memory defaults to active for every plan — no dev flag or entitlement grant is needed.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_CORTEX | unset (on) | Set to off to opt out of the Cortex sidecar bootstrap (memcortex-daemon + memcortex-mcp) that memtrace start spawns in the background. Cortex is universal by default across every plan; this is the only opt-out. |
Hooks#
Controls for the git pre-commit and pre-push hooks installed by memtrace install-hooks.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_PRECOMMIT | unset (on when installed) | Kill switch for the pre-commit hook. Set to off and the installed hook script exits immediately, paying zero process-spawn cost. The pre-commit hook itself is opt-in at install time (install-hooks --pre-commit) — a bare install-hooks only installs pre-push. |
MEMTRACE_PRECOMMIT_TIMEOUT_MS | 1500 | Time budget for the pre-commit blast-radius analysis before it gives up and lets the commit through. |
MEMTRACE_PRECOMMIT_MODE | blocking | blocking (default) runs the analysis synchronously in the commit path. agent lets the hook return quickly and finish analysis in the background — useful for agent-driven commits where the extra latency is not acceptable. |
MEMTRACE_PREPUSH | unset (on when installed) | Kill switch for the pre-push gate. Set to off (or 0/false/no/disabled) to skip it for one shell. Pre-push is the default-installed hook because it blocks a bad push, not a bad commit — the rationale for keeping it default-on while pre-commit is opt-in. |
Install#
Controls read by the npm installer (install.js) during npm install -g memtrace and memtrace setup.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_INSTALL_YES | unset (false) | Pre-approves the consent-gated user-config integration phase (agent MCP registration, skills, git hooks) so a plain npm install -g memtrace doesn't stop and defer. Equivalent to memtrace setup --yes after the fact. (Alias: MEMTRACE_ASSUME_YES.) |
MEMTRACE_SKIP_CUDA_EP | unset (false) | Set to 1 to skip the Windows-NVIDIA-only CUDA execution-provider download (a large one-time asset) during install. Retry later with memtrace gpu install-cuda. |
MEMTRACE_FORCE_NOAVX2 | unset (false) | Forces the installer to select the *-noavx2 platform package family instead of relying on its runtime AVX2 probe (/proc/cpuinfo, a PowerShell feature check, or sysctl on macOS). Useful for testing or a host with a broken feature probe. |
MEMTRACE_FORCE_AVX2 | unset (false) | Forces the installer to select the standard (AVX2) platform package, overriding the runtime probe. |
Telemetry#
See Telemetry & privacy for what's collected. This variable is the supported kill switch for the telemetry pipeline.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_TELEMETRY | unset (on) | Set to off (also 0/false/disabled/no) to disable telemetry unconditionally. |
Licensing#
Signing in is required for local use; this variable is the non-interactive alternative to the browser device-flow.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_LICENSE_KEY | unset | Supplies a license key directly, bypassing the interactive first-run device-flow sign-in — the standard way to authenticate in CI or headless environments. |
For where these values ultimately write to disk, see Data directories; for the embedding preset table in full, see Embedders; for MCP transport details, see Transports.