Workspaces

A workspace lets several repositories share one Memtrace knowledge graph, so the agent can answer questions across repo boundaries — your TypeScript frontend's fetch("/api/users") links to your Rust backend's Router::route(...) even though they live in separate directories.

If you only ever work in a single repo, you can skip this page — Memtrace already does the right thing (one .memdb/ at your git root). Workspaces matter the moment you have two or more related repos (frontend + backend, a service mesh, a monorepo of packages) and you want the graph to see them as one system.

Why use one

Without a workspace, each repo gets its own isolated .memdb/. The graphs can't see each other, so cross-repo questions come back empty:

• "What backend endpoint does this client call hit?"
• "If I rename this route, which frontends break?"
• "Show the call path from the UI button to the database write."

Put those repos under one workspace and all of that resolves through a single graph. Concretely, a workspace gives you:

• One .memdb/ store for every repo beneath it.
• Cross-repo edges — HTTP calls, shared types, imports across service boundaries — detected automatically at index time.
• One owner/daemon for the whole set instead of one per repo.

Create a workspace

Pick whichever fits how you work. All three end up at the same place: a .memtrace-workspace marker file at the folder that contains your repos.

Option A — drop a marker (most explicit)

cd /path/to/parent-folder    # the folder that holds your repos
touch .memtrace-workspace    # empty file is fine

Option B — let the CLI write it

memtrace start --workspace .
# or
memtrace index --workspace .

--workspace <path> treats path as the workspace root and writes the marker there for you.

Option C — auto-detect

Run memtrace start from a folder that isn't itself a git repo but contains 2+ child directories that each have their own .git. Memtrace recognises the multi-repo shape and writes the marker automatically. Opt out with memtrace start --no-workspace.

How Memtrace picks the workspace

When memtrace start, memtrace index, or memtrace mcp boots, it walks up from the current directory and uses the first of these it finds:

1. .memtrace-workspace marker — explicit anchor. First match wins; every sibling directory beneath it shares one .memdb/. Recommended for monorepos and multi-repo setups.
2. .git/ root — per-repo fallback when no marker exists.
3. Current working directory — if neither marker nor git root is found.

Confirm where you actually landed:

memtrace status

The startup banner also prints the resolved path:

◆  MemDB embedded — in-process (data dir: /your/path/.memdb)

Worked example

$ pwd
/home/me/work/

$ tree -L 1 -a
.
├── .memtrace-workspace      ← marker, you touch-ed this
├── .memdb/                  ← ONE store for all 3 repos
├── frontend/                ← repo A (git)
├── backend/                 ← repo B (git)
└── infra/                   ← repo C (terraform-only, no git)

$ cd frontend && memtrace index .
# → registers frontend's symbols in /home/me/work/.memdb under repo_id=frontend

$ cd ../backend && memtrace index .
# → registers backend's symbols in the SAME .memdb under repo_id=backend
# Cross-language edges between frontend & backend now resolve out of the box.

Without the marker, frontend/ and backend/ would each get their own <repo>/.memdb/ and could not see each other.

What is scoped to a workspace (and what isn't)

Lives in the workspace	Lives in ~/.memtrace/ (cross-workspace)
.memdb/ — graph + vectors for every repo under the anchor	Downloaded embedding & reranker models
.memtrace/ — indexer job state (transient, small)	embed-cache/ — per-symbol embedding cache
Workspace-local embedding override (see below)	Session token, global config, logs, watches

Rule of thumb: graph data is per-workspace; models, caches, and your login are machine-global. Full directory-by-directory breakdown is in data-directories.md.

Workspace-local configuration

By default the embedding provider is read from ~/.memtrace/config.toml (machine-global). To pin a different embedder to one workspace only:

memtrace embed set jina-code --workspace
# writes <workspace>/.memtrace/embed.toml

Resolution precedence (highest first):

1. <workspace>/.memtrace/embed.toml — workspace-local override
2. ~/.memtrace/config.toml — machine-global default
3. MEMTRACE_EMBED_MODEL / MEMTRACE_VECTOR_DIMS env vars
4. Built-in default (jina-embeddings-v2-base-code, 768 dims)

See embedding-providers.md for the provider catalogue.

Switching, listing, and ownership

There is no switch or list-workspaces command — a workspace is just a directory. To move between workspaces, run Memtrace from that tree; resolution (above) does the rest.

memtrace status                          # the active workspace's .memdb path
find ~ -name .memdb -type d 2>/dev/null   # every store on this machine

Each workspace's .memdb/ keeps an owner lock (daemon.pid), so memtrace start, memtrace mcp, and the headless daemon agree on a single owner. Extra memtrace mcp processes attach to the existing owner's loopback endpoint instead of opening a duplicate store. See mcp-and-transports.md for the multi-agent picture.

Relevant flags and env vars

Flag / var	Applies to	Effect
--workspace <path>	start, index, mcp	Anchor the workspace at path; write the .memtrace-workspace marker.
--no-workspace	start	Skip multi-repo auto-detection; use git root or CWD only.
MEMTRACE_WORKSPACE_ROOT=<path>	env	Force the workspace anchor — useful for MCP hosts that launch Memtrace from an unexpected CWD.
MEMTRACE_MEMDB_DATA_DIR=<path>	env	Override the .memdb/ location directly (e.g. a faster disk).

Full references: cli-reference.md and environment-variables.md.

When not to use a workspace

• A single repo — the git-root fallback already gives you one clean .memdb/. No marker needed.
• Unrelated projects — keep them in separate workspaces so their graphs (and impact analysis) stay isolated.
• A monorepo where you only want part of it indexed — use a .memtraceignore instead of widening the workspace.

Deleting / resetting

A workspace is its directories — nothing precious lives there that the graph can't rebuild.

memtrace reset <repo_id>     # remove just one repo's records from the shared graph
rm -rf .memdb/               # wipe the whole workspace graph (daemon stopped)
rm .memtrace-workspace       # demote back to per-repo stores

The next memtrace start / memtrace index re-indexes from scratch. Your source code is never touched.