Skip to content
Oka Docs

Workspace design

A workspace in Oka scopes events and learnings. It determines what context returns — query “auth” in workspace A and you get workspace A’s auth knowledge, not workspace B’s.

How workspaces work

Every event is tagged with a workspace. By default, @oka-core/reason uses the current working directory name. You can override this:

  • Environment variable: OKA_WORKSPACE=my-project
  • Per-call: Most tools accept a workspace parameter

Learnings inherit workspace scope from their source events. When you call context("auth"), results are filtered to your workspace by default.

Workspace strategies

The simplest approach. Each repository gets its own workspace, matching the directory name:

workspace: "api-service"      → auth, billing, webhooks learnings
workspace: "frontend-app"     → React, state management, routing learnings
workspace: "infrastructure"   → Terraform, CI/CD, deploy learnings

This works well because:

  • Events are naturally scoped to a codebase
  • context returns relevant results without cross-contamination
  • Team members working on the same repo share intelligence

One workspace per monorepo

For monorepos, use a single workspace. Oka’s tagging and file pattern matching handle the internal scoping:

workspace: "monorepo"
tags: ["packages/auth", "apps/api", "libs/shared"]
file_patterns: ["packages/auth/**", "apps/api/src/**"]

The consolidation engine uses tags and file patterns to keep learnings precise even within a single workspace.

Cross-workspace intelligence

Some learnings apply across workspaces — organizational conventions, shared service behaviors, team-wide patterns. Use visibility scoping:

  • user_repo (default) — scoped to you + this workspace
  • account_wide — visible to everyone in your organization
  • user_private — only visible to you

Consolidation can promote high-confidence learnings from user_repo to account_wide when they’re reinforced by multiple workspaces.

Anti-patterns

Too granular

Don’t create a workspace per branch, PR, or ticket. The intelligence value comes from accumulation over time. A workspace with 10 events won’t produce meaningful learnings.

Too broad

Don’t put unrelated projects in one workspace. “All code I work on” is too broad — context("auth") would mix auth knowledge from completely unrelated services.

Workspace per person

Don’t scope workspaces by person. The value is organizational intelligence — the patterns that emerge when multiple agents and humans contribute to the same workspace over time.