Workspaces & branches

Two ways to share one Memtrace index across repos — auto-detected Folder Groups and registry-backed Named Workspaces — plus how the graph stays branch-aware over time.

Most repos are indexed alone: one git root, one .memdb. But real projects often span more than one repo, and every repo has more than one branch. Memtrace handles both — sharing an index across sibling repos when it makes sense, and versioning the graph across branches so a query never mixes work that shouldn't mix.

Two kinds of workspace#

A workspace is a set of repos that share one Memtrace index. There are two ways to get one, and they solve different problems:

Folder Groups#

A Folder Group forms when you run memtrace start in a parent directory that has no .git of its own but contains two or more sibling git repos as immediate children. Memtrace detects the shape and asks, once, whether those repos should share a single index instead of each getting its own. Say yes — interactively, with --bless-workspace, or with MEMTRACE_BLESS_WORKSPACE=1 — and it writes a .memtrace-workspace marker file at that parent directory. Every immediate-child repo under the marker now resolves the same shared .memdb.

Decline, or run non-interactively without the bless flag, and each repo keeps its own database — nothing is shared. The prompt requires a TTY; in CI or other non-interactive contexts it silently declines unless you pass the bless flag or env var.

memtrace workspace status [PATH] is the read-only inspector — the default verb when you run bare memtrace workspace. It reports the marker path, the shared .memdb path, which repos actually share the index (immediate children of the marker only — a repo nested deeper does not share it and is reported separately), and whether the repo you're standing in is a member.

memtrace workspace unbless [PATH] undoes a Folder Group by deleting exactly one thing: the .memtrace-workspace marker file. It never touches the shared .memdb — no index data is deleted. Each sibling repo simply resolves its own per-repo database again on its next memtrace start or memtrace mcp.

Named Workspaces#

A Named Workspace is an explicit, registry-backed group of repos that can live anywhere on disk — no shared parent directory required. Each one is stored as its own TOML file at ~/.memtrace/workspaces/<ULID>.toml, keyed by an immutable id, with its own dedicated data directory at ~/.memtrace/workspaces/data/<id>/.

$ memtrace workspace add client-x ~/code/api ~/code/web
# Creates the "client-x" workspace (if it doesn't exist yet) and
# adds two repos from anywhere on disk as members.

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

$ memtrace workspace show client-x
# Full detail: members with per-path health checks, data dir, created time.

$ memtrace workspace list
# Every Named Workspace, with member count and whether it's been started yet.

The full verb set is create | add | remove | list | show | rename | delete. A few behaviors worth knowing:

• add validates every path — each must contain its own .git — before persisting anything. One bad path aborts the whole call with no side effects, not even an auto-created workspace.
• show runs the same repo health check that start/index use, so "(ok)" means the repo will really be indexed; otherwise it explains why (path missing, no .git, a git worktree indexed via its main repo, or a submodule indexed via its parent).
• rename changes the display name only — the registry filename and data directory are both keyed on the immutable id, so a rename can never orphan a live index.
• delete removes the registry entry but preserves the data directory by default; add --purge-data to also remove it (refused if a live memtrace process still has that data dir open).
• Workspace names are case-insensitive for lookup, creation, and rename collisions.

The --workspace overload#

--workspace takes either a path or a name, and Memtrace tells them apart by shape, not by an extra flag:

• A PATH (anything with path syntax — /, ., or ~) is a hard Folder-Group override: it anchors the shared data-dir resolution directly at that location and writes a .memtrace-workspace marker there.
• A bare NAME with no path syntax resolves against the ~/.memtrace/workspaces/ registry as a Named Workspace, replacing normal cwd-based repo auto-discovery for that run. A registered name wins over a same-named directory in cwd.

Branch-temporal memory#

Every repo's graph is also versioned across branches, not just across time. Memtrace keeps a per-branch live HEAD for the graph, applies checkout deltas incrementally as the watcher notices a branch switch, and filters queries on two axes at once: branch and time. Ask what a symbol looked like, and the answer scopes to the branch you're actually on — without losing the rest of the graph's history, which stays queryable across branches too.

This is on by default. There's no flag to opt in — the only lever is an escape hatch, MEMTRACE_BRANCH_TEMPORAL, and unset means active.

Git worktree overlays#

Git worktrees are tracked as overlays on top of their main repo's index rather than as separate indexed repos — this is also why memtrace workspace show flags a worktree path rather than treating it as a normal member. The MCP tools list_worktrees and cleanup_worktrees manage this overlay state directly, and cleanup_stale_records clears other stale records left behind by removed worktrees.

See the memtrace workspace CLI reference for every subcommand, flag, and example in full, or the knowledge graph for how the underlying bi-temporal graph is structured.