memtrace start

The default command: boots the workspace runtime, indexes your repos, arms the file watcher, and serves the dashboard at localhost:3030.

Usage#

memtrace start is the default command. It connects to (or spawns) the local MemDB storage engine, discovers and indexes git repositories under the current directory, arms a file watcher for incremental re-indexing, and serves a REST/WebSocket API plus the dashboard UI on http://localhost:3030. It runs in the foreground until Ctrl-C/SIGTERM, at which point it flushes indexes and exits.

Bare memtrace (no arguments) and memtrace --headless/--no-ui/--no-browser all fall through to this same command — there is no separate code path for them.

Flags#

Environment variables#

Boot order#

This is the exact sequence memtrace start runs through on every invocation:

1. 1
   Banner + runtime gates

   Prints the brand banner and a runtime-gates summary (RSS ceiling, pressure threshold, batch sizes, breaker state).

2. 2
   ONNX Runtime pre-flight

   Probes whether libonnxruntime can be dlopen'd. If it can't and MEMTRACE_SKIP_EMBED isn't set, start exits with code 75 (EX_TEMPFAIL) rather than degrading silently. Workaround: MEMTRACE_SKIP_EMBED=1 memtrace start keeps the structural graph working without embeddings (semantic search off, everything else on).

3. 3
   First-run sign-in gate

   If there's no saved session and no MEMTRACE_LICENSE_KEY, the device-flow browser sign-in runs inline before anything else.

4. 4
   Already-running short-circuit

   If a live, mode-compatible daemon already owns this workspace's MemDB dir (confirmed via heartbeat, not just a stale lock), start prints the existing UI URL and MemDB owner endpoint and exits Ok(()) without opening a browser tab — unless --force/--replace reclaims the owner first.

5. 5
   MemDB sidecar

   Resolves and binds the UI port (auto-bumped up to +49 if busy, unless MEMTRACE_UI_PORT was set explicitly), then connects to MemDB — default mode local spawns or adopts a loopback memcore-server sidecar over gRPC on 127.0.0.1:50051.

6. 6
   UI bind + browser auto-open

   Spawns the Axum REST/WebSocket API + dashboard server as a background task, bound to 127.0.0.1 by default (MEMTRACE_UI_HOST to change). Auto-opens the default browser to http://localhost:<port> on a fresh boot only — suppressed by --headless/--no-ui/--no-browser or their env equivalents. The server itself always starts regardless of these flags.

7. 7
   Cortex sidecars

   Also spawns, as background tasks alongside the UI server: a Cortex decision-memory sidecar bootstrap (universal/default-on for every plan since v0.8.3 — opt out via MEMTRACE_CORTEX=off; fail-safe, so a spawn failure just degrades quietly without blocking startup), Rail search-cache warming, graph/insights cache pre-warming, cross-repo HTTP link backfill/repair, and branch-attribution self-heal.

8. 8
   Workspace detection

   Discovers repos to index: the single cwd git repo first, then a Named Workspace's registered members (if --workspace <NAME> was used), then falls back to scanning up to 2 directory levels below cwd for sibling git repos. If 2+ sibling repos are found under a cwd with no .git of its own (a "Folder Group"), memtrace interactively asks (TTY-gated) before writing a .memtrace-workspace marker that shares one index across all of them.

9. 9
   Two-phase auto-index

   Arms a debounced (200ms) file watcher per discovered repo, then runs a two-phase background bootstrap: Phase 1 indexes HEAD for every repo sequentially (skipped if MEMTRACE_START_AUTOINDEX=0 or the store exceeds the large-store size threshold — 512MB by default — and isn't empty); Phase 2 runs embedding + git-history replay per repo, gated by a pressure/RSS pre-flight that backs off exponentially rather than tripping the embed breaker on transient pressure.

10. 10
    Model download

    The first embed triggers a one-time download of the default embedding model — jina-code (jina-embeddings-v2-base-code, 768-dim) — cached at ~/.memtrace/fastembed_cache. The terminal prints an explicit "First run — downloading embedding model" notice so the silent stretch isn't mistaken for a hang.

Gotchas#

Examples#

$ memtrace start
# Default: index the current repo (or discovered sibling repos),
# watch for changes, and open the dashboard at http://localhost:3030.

$ memtrace
# Identical to `memtrace start` — bare invocation falls through to the same dispatch arm.

$ memtrace start --headless
# Run without auto-opening a browser tab; the API/UI still bind on :3030
# (useful for CI, containers, or remote/background daemons).

$ memtrace start --clear
# Wipe the local .memdb data directory first, then start fresh
# (re-indexes everything from scratch).

$ memtrace start --force
# Replace an already-running owner daemon for this workspace
# instead of just reporting it and exiting.

$ memtrace start --workspace ./monorepo-root
# Hard-anchor the shared MemDB/.memtrace data dir at a specific path
# (writes a .memtrace-workspace marker there).

$ memtrace start --workspace my-team-ws
# Boot a registry-backed Named Workspace whose member repos
# can be scattered anywhere on disk.

$ MEMTRACE_SKIP_EMBED=1 memtrace start
# Start with structural indexing only, skipping the ONNX embedding pipeline
# (useful if libonnxruntime isn't installed).

See also memtrace stop, memtrace status, memtrace index, memtrace mcp, memtrace reset, memtrace workspace, memtrace connect, and memtrace doctor.