Workspaces & branches

How cold folder scopes, explicit Folder Groups, Named Workspaces, and portable manifests select repositories and storage — plus branch-aware graph history.

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 — giving each invocation a clear repository and storage scope, and versioning the graph across branches so a query never mixes work that shouldn't mix.

Workspace scopes#

A workspace scope is the set of repos owned by one Memtrace runtime and one MemDB store. Choose the lightest form that matches how the repositories are organized:

Cold folder scopes#

Bare memtrace start scopes itself from the directory where you invoke it. Inside a git repository, that repository owns the run. From a folder containing multiple repositories, all discovered repositories belong to one cold scope backed by that folder's local .memdb.

Cold start deliberately ignores ancestor .memtrace-workspace markers and IDE workspace roots. It never prompts and never writes a marker. This keeps starting Memtrace in one repo from silently attaching to a database created for a different parent workspace.

Folder Groups#

A Folder Group is the legacy persistent form for sibling repositories under one parent. It is now explicit: run memtrace start --workspace <PATH> or invoke start at the parent with --bless-workspace / MEMTRACE_BLESS_WORKSPACE=1. Memtrace writes a .memtrace-workspace marker at that root so compatible processes, including MCP clients launched from member repos, can converge on its shared .memdb.

Bare start does not create or inherit this marker. Use a Folder Group only when the persistent path-based identity is intentional; use a cold folder scope when the invoked folder alone is enough, or a portable manifest when membership should travel with the project.

--no-workspace is the explicit single-repo escape hatch. From anywhere inside a child repo, it selects only that repo and its own .memdb. From a broad parent containing several repos it refuses, because one daemon cannot own several independent stores; run it from the child you want.

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.

Portable workspace manifests#

A workspace manifest is a small TOML file that can live with the project and be shared in version control. It declares exactly which git repositories belong to the workspace without creating a machine-local registry entry or a .memtrace-workspace marker.

version = 1
name = "client-x"
members = [
  "./api",
  "../shared/web",
  "/opt/company/worker",
]

version is required and currently must be 1; name is optional; members must contain at least one unique git repository. Relative member paths resolve from the manifest's directory, while absolute paths are used as written. The same directory anchors the workspace's local .memdb, so moving a project tree with relative members preserves its shape.

$ memtrace start --workspace-file ./memtrace-workspace.toml
# Explicit, unambiguous manifest form.

$ memtrace start --workspace ./memtrace-workspace.toml
# Equivalent shorthand when --workspace points to a file.

The --workspace overload#

--workspace accepts a legacy Folder Group path, a Named Workspace name, or a portable manifest file. Memtrace resolves the argument by shape:

• An existing FILE, or a path ending in .toml, is loaded as a portable workspace manifest. Use --workspace-file when you want the intent to be explicit.
• 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.
• Any remaining PATH is a hard legacy Folder-Group override: it anchors the shared data-dir resolution at that location and writes a .memtrace-workspace marker.

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.