Workspaces

Workspaces are the core organizational unit in Gyrus. Each workspace is a directory containing your knowledge notes and ADRs, allowing you to maintain separate contexts for different purposes.

Understanding Workspaces

A workspace is simply a directory with a specific structure:

my-workspace/
├── knowledge/
│   ├── README.md
│   ├── index.md
│   ├── instructions.md
│   ├── projects/
│   ├── patterns/
│   ├── tools/
│   ├── gotchas/
│   └── decisions/
└── adrs/
    └── template.md

Gyrus tracks your workspaces in a global configuration file at ~/.config/gyrus/config.json.

Creating Workspaces

Default Workspace

Initialize your first workspace with:

gyrus init

This creates a workspace at ~/gyrus with the name default.

Custom Workspace

Specify a path, name, and description:

gyrus init ~/work/brain --name work --description "Work projects and knowledge"

Project-Specific Workspace

Create a workspace inside a project directory:

cd my-project
gyrus init ./brain --name myproject --description "Project-specific notes"

Managing Workspaces

List Workspaces

View all registered workspaces:

gyrus workspaces
# or
gyrus ws

Output:

Workspaces:
  * personal    ~/gyrus                Personal knowledge
    work        ~/work/brain           Work projects
    myproject   ./brain                Project-specific notes

The * indicates the default workspace.

Switch Default Workspace

Change the default workspace:

gyrus use work

This sets work as the default for all commands.

Per-Command Workspace

Override the default for a single command:

gyrus doctor --workspace personal

Workspace Configuration

The global configuration file stores workspace metadata:

{
  "version": 1,
  "default": "personal",
  "workspaces": [
    {
      "name": "personal",
      "path": "~/gyrus",
      "description": "Personal knowledge and projects"
    },
    {
      "name": "work",
      "path": "~/work/brain",
      "description": "Work projects"
    }
  ],
  "settings": {
    "serve": { "port": 3333 },
    "daemon": { "port": 3334 }
  }
}

MCP and Workspaces

When using the MCP server, AI agents can work with multiple workspaces:

List Available Workspaces

// Agent calls gyrus_list tool
// Returns all registered workspaces

Switch Workspace

// Agent calls gyrus_switch tool with name="work"
// All subsequent operations use the work workspace

Example Agent Workflow

Agent: Let me check what workspaces are available.
[calls gyrus_list]

Agent: I see you have personal and work workspaces.
       Which should I use for this task?

User: Use work, this is for my job.

Agent: Switching to work workspace.
[calls gyrus_switch with name="work"]

Agent: Now I can search and create notes in your work workspace.

Best Practices

Workspace Organization

• Personal workspace — General learning, side projects, personal notes
• Work workspace — Company-specific knowledge, work decisions
• Project workspaces — Notes that should live with the codebase

Naming Conventions

Keep workspace names short and memorable:

• ✅ personal, work, myproject
• ❌ my-personal-notes-2026, company-work-brain

Syncing Workspaces

Workspaces are just directories. Sync them however you prefer:

• Personal: Sync via iCloud, Dropbox, or Git
• Work: Keep in company-approved storage
• Project: Commit to the project repository

Troubleshooting

Workspace Not Found

If a workspace path no longer exists:

gyrus doctor --workspace problematic-workspace

This will identify the issue.

Re-register a Workspace

If you moved a workspace, re-initialize at the new location:

gyrus init /new/path --name existing-name

This updates the path in the configuration.