System Architecture

Matrices follows the following system

What owns what

Workspace
├── Identities        Roles        Toolsets        Connections
├── Profiles          models[] · systemPrompt · hooks[] · roleIds[]
└── Agents            profileId · identity · budget?
    ├── Threads → Turns → Events / Waits
    ├── Memory (agent namespace)     + workspace-namespace memory
    ├── Schedules · Subscriptions
    └── Artifacts / Sites / Images

Everything above the agents line is configuration you write once and share: identities, roles, toolsets, connections, and the profiles (with their hooks) that assemble those into behavior. Everything below it is what happened: an agent’s threads, memory, and schedules, which are durable and only reachable through that agent. Feeds are the exception. They’re shared, and that’s what lets agents talk to each other. All of it lives in one workspace.

Cardinality

Relationship	Shape	Notes
agent → profile	N:1	many agents can share one profile
agent → identity	N:1	set at creation, immutable
profile → roles	N:M	at most 8 roles per profile
role → tools	1:N	allow and deny entries, 32 each
connection → owner	N:1	owner is the `workspace` or one `identity`
thread → agent	N:1	threads never cross agents
schedule → agent	N:1	fires into a new or existing thread
subscription → (agent, feed)	N:1 each	one agent woken by one feed
feed → workspace	N:1	feeds are shared, not agent-owned

What a turn freezes

When a turn starts, Matrices works out its configuration once and freezes it for that turn and any replay:

the profile ID and profile version
the one model picked from the profile’s selectors
the system prompt and the hook list
the resolved access, meaning what it may call: each selected role by version, the exact built-in tools, the eligible toolsets, and any conditional grants

Edit a profile, its roleIds, or a role’s own rules and the change lands on the next admitted turn. Work already running keeps the snapshot it started with. The budget is checked at the same moment, so lowering one stops new turns rather than killing a running one. From there it loops: ask the model, run the tool calls the snapshot allows, append the results, ask again. That same resolved access decides what the model can find, and checks every call as it runs. Credentials are attached to the outgoing request, so the model never sees a raw secret and never grants itself anything.

Control plane, data plane

                     your app / the API
                            │
              ┌─────────────┴──────────────┐
              ▼                             ▼
      Control plane                    Data plane
  workspace · profiles · agents · roles  threads · turns · messages
  toolsets · model catalog               tools · waits · event logs
              │                             │
              │  signed turn snapshot       │
              └────────────┐   ┌────────────┘
                           ▼   ▼
                  model gateway · action gateway
                  memory · artifacts · scheduler

The control plane is configuration: what an agent is and what it may do. The data plane is execution: what it actually did. One API key reaches both, and the API reference shows how the endpoints split.

Start here

The model

Rules

Guides

Reference

Resources

System Architecture

What owns what

Cardinality

What a turn freezes

Control plane, data plane

​What owns what

​Cardinality

​What a turn freezes

​Control plane, data plane

What owns what

Cardinality

What a turn freezes

Control plane, data plane