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. In local mode, the workspace owner starts or adopts the loopbackmemcore-server before serving. In external mode, the operator-managed endpoint must already be reachable. |
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.
CPU governor#
The CPU governor configures adaptive resource allocation for background indexing on Windows, Linux and macOS. Apply these variables in the daemon's launch environment and restart to activate changes. The CPU governor reference describes resource policies, platform support and diagnostics. These controls are independent of CoreML acceleration and the memtrace govern command.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_CPU_GOVERNOR | off | Set on to enable budget waits, background scheduling and loop parking. Unset or off disables governance; diagnostic CPU accounting remains available. |
MEMTRACE_CPU_BUDGET_CORES | half the performance cores, minimum 1 | Background CPU allowance in cores; accepts finite values of zero or greater, including fractions such as 0.5. Idle boost can raise this allowance. This is not a hard cap on every process or accelerator. |
MEMTRACE_BACKGROUND_ON_BATTERY | reduced | reduced gives background work one quarter of its allowance and interactive work one half. off pauses background bulk work on battery. full ignores battery reductions, including the default pause at 15% charge or below. |
MEMTRACE_CPU_IDLE_BOOST | on | Allow background work the interactive allowance after five minutes of user inactivity when other signals permit it. Set off to retain the background allowance while idle. |
MEMTRACE_IDLE_BURN_WATCHDOG | on when the governor is enabled | Temporarily park registered background loops when CPU is consumed without recorded progress. The default observation window is 600 seconds. Set off to disable this watchdog while leaving the governor enabled. |
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 | on for Apple Silicon in the 1.1.13 nightly | Controls the CoreML execution provider on Apple Silicon. Nightly 1.1.13-nightly.20260906.6948f83 requests CoreML by default. Set 0 for CPU-only execution. First use can compile the model. CoreML registration does not guarantee every operation runs on the Neural Engine, and CPU fallback remains available. |
MEMTRACE_DISABLE_COREML | unset (false) | Set 1 to force CoreML off, even when MEMTRACE_ENABLE_COREML is on. Useful for a CPU-only comparison or diagnosing compilation failures. This does not enable or disable the CPU governor. |
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_ALLOW_NON_GIT | unset | Set to 1 to index directories that are not git repositories, as a point-in-time snapshot. Equivalent to the --allow-non-git flag. Off by default: discovery would otherwise treat any directory as a repository. Temporal tools return empty for these scopes and say so explicitly — see Indexing directories without git. |
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_ENUMERATION_TIMEOUT_SECS | 120 | Ceiling on list_indexed_repositories. Past it the call reports an error naming the recovery path instead of blocking the session until the MCP client's own idle timeout fires. Set 0 to wait indefinitely — useful when debugging a slow enumeration, since the bound would otherwise cut the observation short. Raise it on a very large store rather than disabling it. |
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 memcortex-daemon sidecar bootstrap that memtrace start runs 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, and by the first-run setup the memtrace command performs when npm skipped the install script.
| 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_NO_AUTO_SETUP | unset (false) | Set to 1 to turn off the first-run setup. npm 12 and later skip install scripts unless allowed, so the first memtrace command after an install or upgrade refreshes an existing setup (or asks, on a new install). This turns off only that first-run step: memtrace setup, memtrace update/install/upgrade (including the upgrade offered at memtrace start), and an install script npm is allowed to run still set up or refresh your agent configuration. |
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.