Skip to content

cli-reference.md

Latest commit

 

History

History
191 lines (152 loc) · 8.42 KB

cli-reference.md

File metadata and controls

191 lines (152 loc) · 8.42 KB

CLI reference

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 daemon.
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 daemon install/start/status/stop Install or control the optional background service where supported.
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.

Code review

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 UI port. Default: 3030.
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 embedding work. Structural graph remains usable.
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.