memtrace index

One-shot indexing of a repository — or an entire multi-repo workspace — into MemDB: parse to AST graph, embed, and replay git history, then exit.

Usage#

memtrace index [PATH] [--workspace <PATH|NAME>] [--clear|--fresh] [--debug]

memtrace index runs a one-shot indexing pass: parse to AST graph, persist nodes/edges, then run embeddings and git-history replay in parallel, print a summary plus a discovery report, and exit. PATH defaults to the current directory. If PATH is a workspace — a .memtrace-workspace marker, or a folder holding two or more sibling git repos — every discovered repo is indexed into one shared index.

Unlike memtrace start, memtrace index never prompts, does not arm the file watcher, and does not keep a daemon running. Use it for CI, scripted re-indexing, or a quick structural pass without booting the dashboard.

Flags#

Flag	Description
`PATH`	Directory to index. Defaults to `.`. May be a single git checkout, or a workspace root — resolution walks up for a `.memtrace-workspace` marker, falls back to workspace-shape detection (2+ child git repos, no own `.git`), then to a recursive scan for git repos under PATH. Only the first positional argument is used; extras are ignored.
`--workspace <PATH>`	Hard override for where the shared index lives. Created if missing, canonicalized, set as the data-dir anchor, and a `.memtrace-workspace` marker file is written there — with side effects even before indexing starts. Accepts both `--workspace VALUE` and `--workspace=VALUE`.
`--workspace <NAME>`	Resolves a Named Workspace from the `~/.memtrace/workspaces` registry: its per-workspace data root becomes the anchor, and its registered member repos are indexed instead of PATH. Registry names take precedence over same-named local folders. Unknown name exits 2.
`--clear / --fresh`	Wipes the local MemDB data dir (recursive remove) before connecting, then best-effort re-creates the database. In external-MemDB mode only the local cache/lock dir is removed — zero remote side effects. Equivalent aliases, detected anywhere in argv.
`--debug`	Enable debug CLI logging. Equivalent to MEMTRACE_DEBUG truthy.
`--help / -h`	Print help and exit 0 before any work runs.

Environment variables#

Variable	Default	Description
`MEMTRACE_LICENSE_KEY`	`unset`	License key used for the online auth exchange (checked before the credentials file). Index refuses to run without valid auth and suggests setting this on failure.
`MEMTRACE_OFFLINE`	`unset`	MEMTRACE_OFFLINE=1 forces authentication from the stored offline license file (`~/.config/memtrace/license.mtl`); telemetry/heartbeat disabled.
`MEMTRACE_MEMDB_DATA_DIR`	`<git-root>/.memdb (else <cwd>/.memdb)`	On-disk MemDB data dir; this is what `--clear` wipes. Resolution order: CLI `--workspace` override, then IDE workspace env, then the nearest `.memtrace-workspace` marker or git root, then `<cwd>/.memdb`.
`MEMTRACE_MEMDB_ENDPOINT`	`http://127.0.0.1:50051`	MemDB gRPC endpoint. Setting a non-loopback endpoint switches to external mode; loopback endpoints stay in local (sidecar) mode.
`MEMTRACE_MEMDB_DB`	`memtrace`	MemDB database name used by the index/replay writers.
`MEMTRACE_SKIP_EMBED / MEMTRACE_NO_EMBED`	`unset`	Truthy value (1/true/yes/on) disables the embedding stage entirely; index prints a structural-graph-only pass.
`MEMTRACE_NO_REPLAY`	`unset`	MEMTRACE_NO_REPLAY=1 skips the git-history replay stage.
`MEMTRACE_FORCE_EMBED`	`unset`	MEMTRACE_FORCE_EMBED=1 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_FORCE_REPLAY`	`unset`	MEMTRACE_FORCE_REPLAY=1 ignores the per-branch replay watermark and re-walks the full history window.
`MEMTRACE_REPLAY_DAYS`	`30`	How many days of git history the replay stage walks.
`MEMTRACE_PIPELINE_STAGES`	`unset`	MEMTRACE_PIPELINE_STAGES=1 prints per-stage timing (name, ms, items) after the pipeline summary.
`MEMTRACE_MAX_THREADS`	`n-2`	Caps rayon parse-thread parallelism for the indexing pipeline.
`MEMTRACE_DEBUG`	`unset`	Truthy value enables debug logging, same as --debug.
`MEMTRACE_EMBED_MODEL`	`jina-code`	Embedding model for the embed stage — a code-specialized 768-dim default, with bge-small/bge-base/nomic as rollbacks.

Behavior#

Argument handling strips --workspace (and its value), --clear/--fresh, and any other dash-prefixed token, keeping only the first positional as PATH (default .). --help/-h short-circuits to the help text before any work starts.

Target resolution: a single git checkout indexes just that repo; otherwise it resolves a workspace root via the .memtrace-workspace marker walk-up or the workspace-shape heuristic (2+ child git repos, no own .git) and indexes every repo discovered — a BFS scan that skips dot-dirs and node_modules/target/dist/build/vendor/.venv/__pycache__. Git worktrees are redirected to their main repo; submodules are skipped. No repos found is an error.

During the walk, Memtrace honours .gitignore, the built-in noise baseline, and repo-root .memtraceignore — see that page for syntax, examples, and how to verify skip counts via memtrace status.

A license gate runs before any indexing: failure prints a link to get a license key plus memtrace auth login/MEMTRACE_LICENSE_KEY hints and exits 1. MEMTRACE_OFFLINE=1 or a stored offline license file authenticate without network.

Storage backend startup constructs AppState mode-aware: the default local mode spawns/adopts a memcore-server sidecar over gRPC (default 127.0.0.1:50051); embedded opens the data dir in-process plus a loopback gRPC server; external dials a remote endpoint.

Stage 1 runs the ingestion pipeline per repo — parse, prepare the nodes/edges payload, persist via the engine (or gRPC in remote mode) — then prints "Indexed N nodes · M edges (X ms)" plus files/communities/processes/embeddable counts, and upserts a Repository summary record.

Stages 2 and 3 run in parallel: embeddings for embeddable nodes through the ONNX embed worker with a live progress bridge (stamping an embed-complete marker at HEAD on success), and trunk-anchored git replay — the default branch first, then the current branch's divergence — over the last MEMTRACE_REPLAY_DAYS (default 30) days, writing episode history. Both are skipped when an up-to-date marker already exists for the current HEAD.

Embed and replay failures are non-fatal: they print a warning ("Embedding stage failed (non-fatal)" / "Replay failed (non-fatal)") and the command still exits 0. Only Stage-1 pipeline failures exit 1.

On a shared external MemDB, a per-repo-per-branch indexer election runs first — if another seat already holds the lease for the same repo and branch, this run prints the peer detail and returns success without doing work. Embedded/local modes skip the election entirely.

After all stages, a discovery report is printed, WebSocket indexed events and a graph-skeleton refresh are pushed to any connected dashboard, and the process exits 0. Multi-repo runs index sequentially and abort with exit 1 on the first repo that fails — earlier repos stay indexed. Progress spinners render only when stderr is a TTY, so the command is safe in CI/headless runs and never prompts for input. .env files from the cwd and all ancestor dirs are auto-loaded at process start (existing env vars are never overridden).

memtrace index pipelineFLOW

License gate

Resolve targetrepo or workspace

--clear wipe?

Parse to graphStage 1

EmbedStage 2

Git replayStage 3

Discovery report

DECISIONSUPPORTINGSERVICESUCCESS

Gotchas#

REQUIRES AUTHENTICATION

Without a license key, stored credentials (memtrace auth login), or an offline license file, the command exits 1 before indexing anything.

NAMED WORKSPACES ARE ACCEPTED

--workspace accepts either a filesystem path or a Named Workspace NAME from the ~/.memtrace/workspaces registry. With a named workspace, Memtrace indexes that workspace's member list.

UNKNOWN FLAGS ARE SILENTLY STRIPPED

Unknown dash-flags are stripped rather than rejected, and only the first positional argument is used — memtrace index --typo repo1 repo2 indexes repo1 with no warning.

EMBEDDINGS CAN BE MISSING ON A GREEN EXIT

Embedding and replay failures do not fail the command — it can exit 0 with warnings while embeddings are missing. Re-run, or check memtrace status.

SKIP WORK ALREADY DONE

Embed and replay are skipped when completion markers exist for the current git HEAD. Use MEMTRACE_FORCE_EMBED=1 / MEMTRACE_FORCE_REPLAY=1 to override.

ONE-SHOT, NOT CONTINUOUS

This is a one-shot command: it does not arm the file watcher or leave a daemon running. Use memtrace start (or the watch_directory MCP tool) for continuous indexing.

--WORKSPACE HAS SIDE EFFECTS BEFORE INDEXING

--workspace <PATH> creates the directory and writes a .memtrace-workspace marker file there even before indexing starts; marker/registry errors exit with code 2.

Examples#

terminal

$ memtrace index
# Index the current directory — a single repo, or every repo
# in a multi-repo workspace.

$ memtrace index ~/code/myrepo
# Index a specific repository path.

$ memtrace index --workspace .
# Anchor a shared multi-repo index at the current directory
# (writes a .memtrace-workspace marker) and index all sibling repos.

$ memtrace index --workspace teamx
# Index the registered members of the Named Workspace 'teamx'
# into its own data dir (see `memtrace workspace create/add`).

$ memtrace index --clear
# Wipe the local MemDB data dir first, then index from scratch.

$ MEMTRACE_SKIP_EMBED=1 MEMTRACE_NO_REPLAY=1 memtrace index
# Fast structural-graph-only pass: skip the embedding and
# git-replay stages.