memtrace reset

Destructively resets local Memtrace memory — a full MemDB data-dir wipe by default, or a selective per-repository drop of records and caches when a repo ID is given.

Usage#

memtrace reset [<repoId>]

memtrace reset destructively resets local Memtrace memory. Without arguments it stops any running daemon (and its OS supervisor), deletes the workspace's MemDB data directory (.memdb), and reconnects so an empty database is re-created lazily. With a positional <repoId> it performs a selective wipe instead: every Node/Edge/Episode/VectorBlob record for that repository is deleted through the storage backend, plus that repo's embedding, graph-skeleton, and insights caches — the rest of the data dir is untouched.

NO CONFIRMATION PROMPT — THIS IS DESTRUCTIVE AND IRREVERSIBLE

Neither mode asks "are you sure?". The wipe begins immediately after argument dispatch. The full reset deletes on-disk HNSW segments and the write-ahead log — re-indexing from scratch is required afterwards. There is no undo.

Flags#

Flag	Description
`<repoId>`	Optional positional argument (as shown by `list_indexed_repositories` or the daemon UI). When present, switches from a full data-dir wipe to a selective per-repo wipe. Taken verbatim from argv — no flag parsing is applied to it.
`--help / -h`	Print the reset usage text and exit without touching anything. Detected at any argv position before dispatch, so it's the only flag that safely combines with `reset`.

Environment variables#

Variable	Default	Description
`MEMTRACE_MEMDB_DATA_DIR`	`<workspace anchor>/.memdb`	The directory the full reset deletes with `remove_dir_all`. An env override wins over the `--workspace` CLI override, IDE workspace env anchors, and the marker/git-root walk-up. Setting this is the reliable way to scope a reset at a specific store — `reset` itself doesn't parse `--workspace`.
`MEMTRACE_MEMDB_MODE`	`local`	Controls reset semantics. In `local`/`embedded` mode the data dir IS the database, so reset wipes and re-creates it. In `external` mode (explicit env, a `team.toml` endpoint, or a non-loopback `MEMTRACE_MEMDB_ENDPOINT`) the full reset only removes local cache/lock artifacts and never contacts the remote server; the selective `reset <repoId>` form is refused outright.
`MEMTRACE_UI_PORT`	`3030`	Port scanned in the daemon-kill fallback: if no live PID file is found, reset kills memtrace-named processes listening on this port before wiping.
`MEMTRACE_MEMDB_ENDPOINT`	`http://127.0.0.1:50051`	MemDB gRPC endpoint. A non-loopback value (without an explicit `MEMTRACE_MEMDB_MODE`) implies external mode and therefore the artifacts-only reset. The endpoint is echoed in the external-mode notice and in reconnect failure messages.
`MEMTRACE_MEMDB_DB`	`memtrace`	Database name used when Memtrace reconnects after a local wipe, and named in the external-mode notice/refusal messages.
`MEMTRACE_DEBUG`	`off`	Truthy value enables debug CLI logging for reset. Use the env var, not a `--debug` flag — a flag after `reset` would be misread as the repoId positional.

Behavior#

Full reset (no arguments):

Step 0 boots out every Memtrace OS supervisor before killing PIDs, so a KeepAlive/Restart rule can't respawn the daemon mid-wipe — macOS launchctl bootout+unload for each *memtrace*.plist in ~/Library/LaunchAgents, Linux systemctl --user stop for *memtrace*.service units, Windows sc stop for services named *memtrace*.
Step 1 sends SIGTERM to the PID recorded in ~/.memtrace/memtrace.pid (sleeping 500ms for the shutdown handler to release the data-dir flock), deletes the PID file, then falls back to killing memtrace-named processes on the UI port if the PID-file kill didn't land.
Step 2 recursively deletes the resolved MemDB data directory with remove_dir_all. Not-found counts as success ("already absent"); any other IO error aborts the command with a non-zero exit. Deleting the whole directory — rather than truncating record kinds through the backend — is deliberate so on-disk HNSW segments and the WAL go too.
Step 3 (local/embedded mode) reconnects by constructing AppState — in default local mode this spawns or adopts a loopback memcore-server sidecar — so an empty database is ready for the next run. Reconnect failures are non-fatal: a warning prints and the next memtrace start creates the database lazily; the command still exits 0.

In external mode (MEMTRACE_MEMDB_MODE=external/remote, a team.toml endpoint, or a non-loopback endpoint), the full reset removes only the local cache/lock dir (daemon.pid, daemon-state.json), skips the reconnect entirely — zero remote side effects — and prints a notice that the remote MemDB was NOT modified and must be reset server-side by an administrator.

Selective reset (memtrace reset <repoId>): refused outright in external mode, before any daemon stop or connection — it would otherwise issue delete-by-property writes against the shared remote database. In local/embedded mode it stops the daemon (an 800ms settle sleep instead of 500ms), opens the backend in-process, pre-counts Node/Edge/Episode records for the repo, then issues delete-by-property per kind in dependency order — Edge first, then VectorBlob, Node, Episode — so a partial failure leaves no dangling references. This is the exact same helper the MCP delete_repository tool uses.

Selective reset also removes the repo's on-disk derived caches: the embedding cache file at ~/.memtrace/embed-cache/<sanitized-repoId>.redb, graph-skeleton cache files under <data_dir>/graph-cache (repo-prefixed .mtgs files plus the cross-repo aggregate, so it can't serve stale merged data), insights cache files at <data_dir>/insights-cache/*__<sanitized-repoId>.json, and it invalidates the in-process BM25/FTS index for the repo. It ends by calling backend.shutdown() to fsync the WAL and page cache before exit, so a kill -9 between the delete and the next start can't resurrect the wiped records.

Neither mode asks for confirmation — the wipe begins immediately after argument dispatch. Progress renders as a colored 3-step banner on stderr; the full reset finishes with "MemDB wiped — ready for a clean index" and suggests memtrace index .. The same wipe semantics are reachable from two other doors: memtrace start --clear/--fresh and memtrace index --clear/--fresh (shared helper), and memtrace embed set dimension-mismatch resets.

Full reset vs. selective resetFLOW

memtrace reset

repoId given?

Stop daemonPID + supervisor

Delete .memdbremove_dir_all

Reconnectfresh store

Delete repo recordsEdge→Blob→Node→Episode

Clear repo caches

TRIGGERDECISIONSUPPORTINGREMEDIATIONSERVICE

Gotchas#

DESTRUCTIVE AND IRREVERSIBLE — NO CONFIRMATION

memtrace reset starts wiping immediately. The full wipe deletes on-disk HNSW segments and the WAL — re-indexing from scratch is required afterwards. There is no prompt and no undo.

NEVER PASS FLAGS AFTER RESET

The repoId is read verbatim from argv, so memtrace reset --debug or memtrace reset --workspace X is interpreted as a selective reset of a repo literally named --debug / --workspace. Only --help/-h is safe. Scope the target with MEMTRACE_MEMDB_DATA_DIR or by cd'ing into the workspace instead.

EXTERNAL/TEAM MODE CHANGES SEMANTICS COMPLETELY

Full reset clears only this machine's cache/lock artifacts and never contacts the remote MemDB; a selective reset <repoId> is refused with a non-zero exit because it would delete records from the shared remote database. A present .memtrace/team.toml with an endpoint — or a non-loopback MEMTRACE_MEMDB_ENDPOINT — implies external mode even without MEMTRACE_MEMDB_MODE set.

A FULL WIPE DOESN'T CLEAR EVERYTHING

The full wipe deletes only the .memdb data dir. Per-repo embedding caches under ~/.memtrace/embed-cache/*.redb survive a full reset — they're only removed by the selective reset <repoId> / delete_repository path — as do models and credentials under ~/.memtrace.

KILLS DAEMONS SYSTEM-WIDE-ISH

Reset stops every OS supervisor artifact matching *memtrace* (launchd/systemd/Windows service) and any memtrace-named process on the UI port — not just the one serving this workspace's store.

CURSOR MAY RESPAWN A DAEMON IMMEDIATELY

If Cursor is configured to launch memtrace mcp, it can respawn a daemon right after the wipe; reset prints a dedicated warning when it detects this risk.

RECONNECT IS BEST-EFFORT

If MemDB can't be reached after the wipe, reset still exits 0 and defers database creation to the next memtrace start.

Examples#

terminal

$ memtrace reset
# Full local wipe: stop supervisors + daemon, delete the workspace
# .memdb dir, reconnect so an empty database is re-created.
# No confirmation prompt.

$ memtrace reset my-repo
# Selective wipe of one repository: deletes its nodes/edges/episodes/
# vector blobs plus embedding, graph, and insights caches. Other repos
# in the same store are untouched.

$ MEMTRACE_MEMDB_DATA_DIR=/path/to/project/.memdb memtrace reset
# Pin the wipe to an explicit data dir (the env override beats all
# workspace-anchor resolution). Use this instead of --workspace,
# which reset does not parse.

$ memtrace reset --help
# Print usage and exit; nothing is touched.