Workspace commands.

What a workspace is

A workspace is an addressable context boundary in Empirical. Your personal workspace is for preferences that follow you; a team workspace is for a project, client, product, or temporary collaboration. The active workspace is sent with CLI requests so memory does not silently mix across contexts.

Mental model: Think of a workspace as the filing cabinet an agent is currently allowed to use—not as a second login or a replacement for source control.

When to use a workspace

Create one when several people or agents need the same project context, when client information must stay separate, or when you want a clean context for a demo or experiment.

• Personal: writing style, tooling preferences, and durable defaults
• Project: architecture decisions, deployment rules, and handoff notes
• Client or experiment: intentionally isolated context with its own members

• See how workspace scope affects memory →

Manage the active workspace

Start by inspecting available workspaces and the current selection. select is interactive; use is convenient for scripts and accepts a number, name, or ID. Inside a git repository, use binds the workspace to that project by writing .empirical/workspace.json at the repo root, so sessions in other repositories are unaffected; --global sets the machine-wide default instead, and unbind removes a project binding. Every memory command resolves the workspace the same way, first match wins: the EMPIRICAL_WORKSPACE_ID environment variable, the nearest project binding, the global selection, then the server-side client selection. workspace current and whoami print which source applied.

empirical workspace list
empirical workspace current
empirical workspace select
empirical workspace use "Project Atlas"            # inside a repo: binds this project
empirical workspace use "Project Atlas" --global   # machine-wide default
empirical workspace unbind
empirical workspace create "Project Atlas" --description "Shared engineering context"

Verify: Run empirical whoami and check cliWorkspace.source. A tag-scoped query that returns nothing for a tag you know exists is almost always a workspace mismatch, not a search problem.

Query across several workspaces

One question sometimes spans a personal note and a team decision. Pass --workspaces with list numbers, names, or IDs, or --all-workspaces, to search several workspaces in one call. Results are merged into one ranked list and each row carries its workspaceId. Paging with --cursor or offsets is not available across workspaces; without the flag a query is scoped to the single active workspace exactly as before. The same option exists on the MCP query_memories tool (workspaceIds) and on POST /api/v1/memories/recall.

empirical memory query --match "deployment rules" --workspaces "Default Workspace","Project Atlas"
empirical memory query --match "deployment rules" --all-workspaces

Idea documents

A workspace with a shape can nest items: an idea with sub-ideas beneath it, at any depth. Any item can be read back as a single document containing everything under it, which is how you hand a whole line of thinking to a person or to an agent without reassembling it yourself.

• The document follows the order the tree is arranged in, not the order things were written
• Type, status and field names are rendered from the workspace shape, so a status reads as its label rather than its key
• Available from the terminal, the portal (View as document on a memory) and agents (get_memory_tree)

empirical memory tree --memory-id <id> --out idea.md

Boundary: Nesting is a property of a shaped workspace. In a workspace without a shape every memory is flat, and asking for a document returns just that memory.

Invite people and delete carefully

Invite operations apply to the active team workspace. Deletion is a dry run until --confirm; the default personal brain cannot be deleted. Export anything that must survive before removing a workspace.

empirical workspace invite create --role writer --expires-in-days 7 --max-uses 3
empirical workspace invite list
empirical workspace invite revoke <token>
empirical workspace delete "Project Atlas" --confirm

• Export before cleanup →
• See the short command reference →