CLI reference

June 7, 2026 · View on GitHub

This page mirrors the user-facing memtrace --help surface and adds the extra context that does not fit in terminal help.

memtrace [COMMAND] [FLAGS]

Run this any time to see the exact command set for your installed binary:

memtrace --help

Commands

Command	Purpose
`memtrace start`	Start the local UI/API server, file watcher, PR command loop, and workspace owner against MemDB. This is also the default command when you run `memtrace` with no subcommand.
`memtrace stop`	Stop the running `memtrace start` workspace runtime (and unload any legacy OS service registrations from older installs).
`memtrace status`	Show backend, index, and runtime status.
`memtrace mcp`	Run the MCP server for Claude, Cursor, Codex, and other MCP-compatible agents. It attaches to an existing workspace owner or becomes the owner if none is running.
`memtrace index <path>`	Index a repository or workspace into MemDB, then exit.
`memtrace code-review setup`	Choose the default headless agent for `@memtrace fix this`.
`memtrace code-review --pr <url>`	Review a GitHub pull request using local Memtrace context.
`memtrace pr status`	Show local PR watches registered by `memtrace code-review --post --watch`.
`memtrace pr sync`	Poll watched PRs once via the installed GitHub App.
`memtrace reset [repoId]`	Reset graph data. With no argument, wipes the local `.memdb`; with a repo id, removes only that repo's records and embedding cache.
`memtrace install`	Upgrade to the latest npm package. `memtrace install start` upgrades and then starts.
`memtrace install-rtk`	Run the optional RTK install/init flow.
`memtrace insight-card [repoId]`	Print the Codebase Insight Card for one or more indexed repos.
`memtrace install-hooks [--pre-commit] [--pre-push] [path]`	Install Memtrace-managed git hook blocks. Default installs pre-push only.
`memtrace uninstall-hooks [--pre-commit] [--pre-push] [path]`	Remove Memtrace-managed git hook blocks.
`memtrace pre-commit [--staged] [--agent-mode]`	Hook runtime used by installed pre-commit hooks.
`memtrace warmup [--model <name>]`	Preload and compile the local embedding model, useful on Apple Silicon.
`memtrace embed list`	List available local embedding presets.
`memtrace embed status`	Show active embedding config and current MemDB vector dimensions.
`memtrace embed set ...`	Set local or remote embedding provider configuration.
`memtrace embed test`	Probe the active embedding provider and report latency/dimensions.
`memtrace version`	Print the installed version.
`memtrace help`	Show top-level help.

Command roles

memtrace index, memtrace start, and memtrace mcp all use the same local .memdb store, but they have different lifetimes:

memtrace index . is a one-shot graph build or refresh.
memtrace start is the visible local owner: UI, watcher, PR command loop, and API server.
memtrace mcp is the agent-facing MCP server. It attaches to the visible owner if one exists; otherwise it can own the workspace itself for agent-only workflows.

Memtrace keeps an owner lock in the resolved .memdb directory, so multiple agent sessions should not open duplicate embedded MemDB owners for the same workspace.

Global flags

Flag	Applies to	Purpose
`--clear`, `--fresh`	`start`, `index`	Wipe the resolved local MemDB data directory before connecting.
`--workspace <path>`	`start`, `index`, `mcp` workspace resolution	Treat `path` as a multi-repo workspace root and write a `.memtrace-workspace` marker there.
`--no-workspace`	`start`	Disable the auto-workspace behavior when the current directory looks like a parent folder containing multiple git repos.
`--headless`	`start`	Keep the HTTP API on `MEMTRACE_UI_PORT` (default `3030`) but do not auto-open a browser tab. Use for Orbit, CI, and agent hosts.
`--no-ui`, `--no-browser`	`start`	Deprecated aliases for `--headless` (one-time note on first use). Prefer `--headless` or `MEMTRACE_HEADLESS=1`.

Removed in 0.6.10: memtrace service / memtrace daemon (OS login autostart install) was removed. Use memtrace start (optionally --headless) or memtrace mcp. memtrace stop still tears down legacy launchd/systemd/Windows service registrations if an older install left them behind.

memtrace code-review is local-first. The hosted Memtrace service only mints a short-lived GitHub App installation token. Diff analysis, graph lookup, ranking, and comment selection run on the developer machine. For the end-to-end PR workflow, GitHub comment commands, and local agent fix setup, see code-reviewer.md.

memtrace code-review setup
memtrace code-review --pr https://github.com/OWNER/REPO/pull/123
memtrace code-review --pr https://github.com/OWNER/REPO/pull/123 --post
memtrace code-review --pr https://github.com/OWNER/REPO/pull/123 --post --watch

Flags:

Flag	Purpose
`--post`	Publish GitHub PR review comments. Without this, Memtrace prints a dry-run preview.
`--watch`	After posting, track the PR locally for human response, approval, requested changes, merge, close, or new pushes.
`--dry-run`	Force preview mode even if `--post` is present.
`--max-comments <N>`	Comment budget. Default is 5 when posting and 10 for dry runs.
`--min-severity <low	medium
`--graph-mode <strict	off>`
`--repo-id <ID>`	Memtrace repo id for graph review. Defaults to `MEMTRACE_DEFAULT_REPO`, then the local repo basename.
`--repo-root <PATH>`	Local checkout root. Defaults to the git toplevel.

Run memtrace code-review setup once to choose the local headless agent used by @memtrace fix this. Non-interactive examples:

memtrace code-review setup --agent codex
memtrace code-review setup --agent claude
memtrace code-review setup --agent cursor
memtrace code-review setup --agent gemini
memtrace code-review setup --agent auto

The GitHub App must be installed on the repository before --post can publish comments. The local UI exposes an Install app action for the selected indexed repository when Memtrace can derive the GitHub owner/repo from the repo remote.

PR watches

Use watches when you want Memtrace to keep local state for posted PR reviews while you wait for human feedback.

memtrace pr status
memtrace pr sync

status reads local watch state. sync polls GitHub once and updates whether reviewed PRs are awaiting response, approved, changed, merged, closed, stale after a push, or blocked by a poll error.

Embedding provider management

Local presets:

memtrace embed list
memtrace embed status
memtrace embed set jina-code
memtrace embed test

Remote OpenAI-compatible providers, including Voyage:

export VOYAGE_API_KEY='vk-...'

memtrace embed set --remote openai-compat \
  --url https://api.voyageai.com/v1 \
  --model voyage-code-3 \
  --dim 1024 \
  --api-key-env VOYAGE_API_KEY

memtrace embed test

If the configured vector dimension does not match the existing MemDB store, Memtrace refuses to silently rebuild vectors at startup. Use memtrace embed status to inspect the mismatch, then explicitly reset and reindex when that is what you want.

Environment files

Memtrace loads .env files from the current directory and its parents without overriding variables already set in the shell. This lets a workspace carry local defaults such as:

VOYAGE_API_KEY=...
GITHUB_TOKEN=...
MEMTRACE_UI_PORT=3030

.env files are not indexed as source code.

Important environment variables

Variable	Purpose
`MEMTRACE_UI_PORT`	Local HTTP API + dashboard port. Default: `3030`.
`MEMTRACE_UI_HOST`	Bind address for the HTTP API. Default: `127.0.0.1`. Set only when you intentionally need remote/VM/container exposure.
`MEMTRACE_HEADLESS`	Skip browser auto-open on `memtrace start` (`1`, `true`, `yes`, or `on`). API stays up.
`MEMTRACE_NO_UI`, `MEMTRACE_NO_BROWSER`	Deprecated aliases for `MEMTRACE_HEADLESS`.
`MEMTRACE_TRANSPORT`	MCP transport: `stdio`, `streamable-http`, `sse`, or `http`.
`MEMTRACE_PORT`	MCP HTTP port when transport is not stdio.
`MEMTRACE_DATA_DIR`	Job state directory.
`MEMTRACE_MEMDB_DATA_DIR`	MemDB data directory. Defaults to the resolved workspace `.memdb`.
`MEMTRACE_MEMDB_MODE`	`embedded` or `remote`. Default: `embedded`.
`MEMTRACE_MEMDB_ENDPOINT`	Remote-mode MemDB gRPC endpoint.
`MEMTRACE_EMBED_MODEL`	Local embedding preset when using local embeddings.
`MEMTRACE_VECTOR_DIMS`	Explicit vector dimension override. Prefer `memtrace embed set` for normal use.
`MEMTRACE_SKIP_EMBED`	Skip all embedding (index, watcher, search). Structural graph remains usable.
`MEMTRACE_SKIP_WATCHER_EMBED`	Skip per-save watcher embedding only; keep index-time embed.
`MEMTRACE_NO_REPLAY`	Skip git-history replay. HEAD graph remains usable.
`MEMTRACE_OWNER_ATTACH`	Set to `0` to force legacy direct embedded open for debugging.
`MEMTRACE_START_PHASE2`	Set to `foreground` to run embedding/replay in the foreground instead of background phase 2.
`MEMTRACE_TELEMETRY`	Set to `off` to disable product telemetry.

See environment-variables.md for the full reference.