Concepts

ConsciousLab has a small set of concepts that every module shares. Learning them once makes the rest of the documentation shorter.

Workspaces

A workspace is the boundary for data, members, billing and API keys. Data never crosses workspaces. Most organisations use one production workspace and one or more test workspaces.

Entities

An entity is anything events can be about, written as kind/id:

Entities do not need to be created before you reference them. The first event that mentions an entity creates its timeline.

Actors

An actor is who or what caused an event: a person (user/…), an agent (agent/…), an API key (apikey/…) or the platform itself (system/…). Every event records exactly one actor. The audit log is a filtered view of events by actor.

Events

Events are the shared record of what happened. Every module writes events and every module can read them. An event has a type, an entity, an actor, a timestamp and typed data. See Events for the full envelope.

The loop: Sense, Reason, Act

Modules are organised around one loop.

1. Sense: modules emit events from the world, such as telemetry samples, payments received or market fills.
2. Reason: agents and rules read events and current entity state, then propose actions with their evidence.
3. Act: actions execute through the module that owns them, subject to permissions and policies, and produce new events.

Policies

A policy decides whether an action may run unattended, needs approval, or is denied. Policies attach to actions, not to agents or users, and are evaluated the same way whether the action comes from the console, an agent or the API.

tool: refund.issue
rules:
  - when: amount_eur <= 50
    decide: allow
  - when: amount_eur <= 2500
    decide: require_approval
    approvers: role:support-lead
  - decide: deny

Roles and scopes

Members have a role: owner, admin, member or viewer. Roles grant scopes per module, such as payments:write or robotics:command. API keys carry scopes directly. A request succeeds only if the caller has the scope and any matching policy allows it.