memtrace start

The default command: cold-starts the invoked repository or folder, indexes its repos, and serves the dashboard at localhost:3030.

Usage#

memtrace start is the default command. With no workspace flag, it cold-starts exactly the invoked git repository or folder. A folder containing multiple repos owns all of those repos in one folder-local store. Bare start does not inherit an ancestor .memtrace-workspace marker or an IDE workspace root, does not prompt for consent, and does not write a marker.

After resolving that scope, start connects to (or spawns) the local MemDB storage engine, indexes every git repository in scope, arms file watchers for incremental re-indexing, and serves a REST/WebSocket API plus the dashboard UI on http://localhost:3030. Bare memtrace and the browser-suppression aliases use the same command path.

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
   Repository scope selection

   Resolves the complete repository scope before constructing config, wiping/opening MemDB, or arming a watcher. Bare start owns the invoked repo or folder as a cold scope, including every repository discovered beneath a multi-repo folder. Explicit Folder Groups, Named Workspaces, and workspace manifests replace that default. --no-workspace selects only the containing repo and refuses a broad multi-repo folder.

4. 4
   First-run sign-in gate

   If there's no saved session and no MEMTRACE_LICENSE_KEY, the device-flow browser sign-in runs inline after repository-scope validation and before configuration/storage startup.

5. 5
   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.

6. 6
   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 starts a store-owned memcore-server sidecar on an isolated loopback gRPC port. It prefers the configured/default port 50051 when available, leases another local port when necessary, and never adopts an unrelated listener.

7. 7
   Watcher readiness

   Publishes the pre-resolved repositories to startup repair and arms every repository watcher. Any watcher failure aborts startup before the HTTP/MCP runtime is advertised as ready.

8. 8
   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.

9. 9
   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.

10. 10
    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.

11. 11
    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
# Cold-start the current repo or folder, ignoring ancestor markers and IDE roots.
# A multi-repo folder uses its own local store without prompting or writing a marker.

$ 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 start --workspace-file ./memtrace-workspace.toml
# Load a portable version-1 manifest. Relative member paths and the data
# directory are anchored beside the manifest. --workspace FILE is equivalent.

$ memtrace start --bless-workspace
# Explicitly turn a sibling-repo parent into a legacy Folder Group
# and persist its .memtrace-workspace marker.

$ memtrace start --no-workspace
# From inside a marked child repo, ignore the parent marker and use this repo's
# own .memdb. From a broad parent containing multiple repos, this is refused.

$ 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.