Multi-Agent Workspaces

cortex-engine supports multiple agents in a single workspace, each with completely isolated memory. You can run a researcher, a writer, and a trader in the same codebase without their memories ever mixing.

Adding Agents

npx fozikio init my-workspace
cd my-workspace
npx fozikio agent add researcher --description "Research agent"
npx fozikio agent add writer --description "Writing agent"
npx fozikio agent generate-mcp   # writes .mcp.json with scoped servers

Each agent gets its own memory namespace. The researcher agent cannot read or write writer memories, and vice versa.

Serving Specific Agents

# Default namespace (no --agent flag = default agent)
npx fozikio serve

# Serve a specific agent namespace
npx fozikio serve --agent researcher
npx fozikio serve --agent writer

Claude Code Integration

The generated .mcp.json (via agent generate-mcp) includes entries for each agent:

{
  "mcpServers": {
    "researcher": {
      "command": "npx",
      "args": ["@fozikio/cortex-engine", "--agent", "researcher"]
    },
    "writer": {
      "command": "npx",
      "args": ["@fozikio/cortex-engine", "--agent", "writer"]
    }
  }
}

Claude Code loads both servers. Tools from each server appear namespaced in the tool list.

Cursor / Windsurf

Add the same JSON to your client's MCP settings. Each agent appears as a separate MCP server with its own tool set.

How Isolation Works

Each agent's memory is stored in a separate namespace within the same storage provider:

• SQLite — separate tables per namespace within the same .fozikio/cortex.db file
• Firestore — separate document collections per namespace

Agents share the same embedding engine and LLM provider configuration. Memory is completely independent.

agent_invoke — Cross-Agent Dispatch

The agent_invoke() tool lets one agent dispatch a sub-task to another cortex-aware agent. The sub-agent has access to the same memory graph and can observe() its findings back into shared (or namespaced) memory.

# Dispatch a research sub-task
agent_invoke("Research best practices for JWT token rotation")

# Target a specific agent namespace
agent_invoke("Summarize the authentication thread", { agent: "researcher" })

# Use a specific model
agent_invoke("Draft a migration plan", { model: "gemini-2.0-flash" })

This is useful for parallelizable sub-tasks — research, drafting, analysis — where you want the work captured in memory automatically without blocking the parent agent.

Shared vs. Isolated Memory

By default, each agent has isolated memory. If you want agents to share observations, use the same namespace — or use agent_invoke() with explicit memory writes:

# Agent A dispatches to Agent B, asking it to observe findings into Agent A's namespace
agent_invoke("Research and observe findings about Redis performance", {
  agent: "researcher",
  observe_back: true
})

Agent-First Setup

The fastest path to a multi-agent workspace: open an AI agent in an empty directory and say "set up a cortex multi-agent workspace with a researcher and a writer." The agent runs the init and agent add commands, reads the generated files, and is immediately productive.

CLI Management

npx fozikio agent list                          # list all configured agents
npx fozikio agent add trader --description "..."  # add another agent
npx fozikio agent remove trader               # remove an agent
npx fozikio agent generate-mcp                 # regenerate .mcp.json

Health and Stats Per Agent

Most CLI commands accept --agent to scope to a namespace:

npx fozikio health --agent researcher     # memory health for researcher only
npx fozikio vitals --agent researcher     # vitals for researcher namespace
npx fozikio wander --agent researcher     # graph walk in researcher memory