memtrace workspace

Inspect and manage the two ways multiple repos can share one Memtrace index: path-based Folder Groups and named, registry-based Workspaces.

Overview#

memtrace workspace manages the two ways multiple repos can share one Memtrace index. A Folder Group is path-based: a .memtrace-workspace marker file in a parent directory whose immediate-child git repos share one .memdb, usually created automatically by memtrace start's auto-bless flow. status inspects a Folder Group and unbless removes just the marker without deleting any data.

A Named Workspace is registry-based: an explicit, named group of repos anywhere on disk, stored as one TOML file per workspace under ~/.memtrace/workspaces/, and started with memtrace start --workspace <NAME>. The remaining verbs — create, add, remove, list, show, rename, delete — manage that registry.

With no verb given, the command defaults to status on the current directory. An unrecognized verb prints usage and exits 2. See Workspaces for the concepts behind both models.

status (default)#

Read-only report on the Folder Group governing PATH (default: the current working directory, canonicalized if it resolves). It walks up from PATH looking for a .memtrace-workspace marker using the same membership-aware resolver the data-dir logic itself uses, so status never reports a marker that indexing wouldn't actually anchor on.

It prints the workspace root, the marker file path, the shared .memdb path, which repos actually share the index (immediate children of the marker directory only), which repos deeper in the tree do not share it, and whether the repo you're standing in is a member. If no marker applies, it prints No .memtrace-workspace marker found. This verb is purely read-only and always exits 0.

$ memtrace workspace
# Same as: memtrace workspace status .

unbless#

Removes only the .memtrace-workspace marker file governing PATH (default: cwd) — a single remove_file call. The shared .memdb directory is left in place, untouched. No index data is deleted.

After unbless, each member repo goes back to resolving its own git-root-scoped database on its next memtrace start or memtrace mcp run. Prompts for confirmation (default No) unless --yes is passed. If the file removal fails, it exits 1.

$ memtrace workspace unbless --yes
# Removes the Folder Group marker governing the cwd, no prompt.
# No index data is deleted; each repo gets its own database on next start.

create#

Creates an empty Named Workspace: writes ~/.memtrace/workspaces/<ULID>.toml with the display name, an immutable ULID id, and a creation timestamp. Errors with exit 2 if the name is already taken — name matching is case-insensitive, so Client-X and client-x collide.

add#

Adds one or more git repos as members of NAME, auto-creating the workspace if it doesn't exist yet. Every path must contain its own .git; all paths are canonicalized and validated before anything is persisted — this is all-or-nothing, so one bad path means nothing is written, not even the auto-created workspace.

Re-adding an existing member is a no-op, not a duplicate.

$ memtrace workspace add client-x ~/code/api ~/code/web
# Creates the Named Workspace "client-x" (if needed) and adds two repos
# from anywhere on disk as members.

remove#

Removes one member path from NAME. If the path wasn't a member, the command succeeds as a no-op.

list#

Lists every Named Workspace, sorted case-insensitively by name, with member count and whether its data directory already exists (exists) or the workspace has never been started (not yet started). Folder Groups are not shown here — use memtrace workspace status for those.

Corrupt registry files, and files whose body id doesn't match their filename, are silently skipped — the filename is treated as the source of truth, which protects delete/rename/purge from ever cross-wiring two workspaces.

show#

Full detail for one Named Workspace: name, immutable id, created time, data directory (~/.memtrace/workspaces/data/<id>/), and each member with a health check — (ok) if it will really be indexed, otherwise a diagnosis: path missing, no .git, git worktree, or git submodule. It uses the same detect_one_repo check that start/index actually use, so the health check reflects real behavior, not a guess.

$ memtrace workspace show client-x
# Inspect members with per-path health checks, plus the data dir and creation time.

rename#

Renames the display name only. Errors if NEW already names a different workspace.

delete#

Removes the registry entry for NAME after a confirmation prompt (default No, skipped with --yes).

By default the data directory is preserved — delete prints where it lives so you can inspect or remove it later. Pass --purge-data to also remove_dir_all it. A purge is refused (naming the live pid, and suggesting memtrace stop) if a running memtrace process still has that data directory open.

$ memtrace workspace delete client-x --yes --purge-data
# Removes the registry entry AND its data dir, non-interactively.
# Refused if a live memtrace process still has the data dir open.

The --workspace overload#

memtrace start accepts --workspace <ARG>, and ARG is overloaded between a Named Workspace and a plain directory path:

• A registered Named Workspace name wins over a same-named directory in the current working directory.
• Only tokens with path syntax — starting with /, ., or ~ — are always treated as a path, never looked up as a name.

When --workspace resolves to a Named Workspace, start substitutes that workspace's member list for normal repo auto-discovery, and the index lives under the workspace's own id-keyed data directory rather than any member's own location.

$ memtrace start --workspace client-x
# Starts the daemon over the named workspace: one shared index in
# ~/.memtrace/workspaces/data/<id>/ covering all members.

Flags & environment#

Flags

Environment

See Workspaces for how Folder Groups and Named Workspaces relate to each other, and memtrace start for how a workspace is actually booted.