Hierarchical scope paths replace tenant_id, namespace, and workspaces.

Scopes

A scope is a /-delimited path of type:id segments that names a memory partition:

org:acme/dept:eng/user:alice

Scopes are the single namespace primitive in CortexDB. They replace what older designs split across tenant_id, namespace, and workspace.

What scopes do

  • Partition data. All writes carry a scope; all reads address a scope.
  • Form a hierarchy. A read at org:acme/dept:eng with view=descend can traverse into org:acme/dept:eng/user:alice. A read at org:acme/dept:eng/user:alice with view=holistic can walk up to ancestors.
  • Carry policy. Each scope can declare retention, default view, members, and ACLs that compose with tenant and deployment policy.
  • Get auto-provisioned. A write to a path that doesn't exist creates the scope (auto_provisioned: true). Explicit registration via POST /v1/scopes sets members and policies.

Path rules

| Rule | Detail | |---|---| | Segment shape | type:id — type from a small enum; id a free-form ULID/slug/email | | Built-in types | org, dept, team, user, agent, service, system, ws (workspace) | | Hierarchy | Order of segments matters; left-most is outermost | | Length | ≤ 8 segments; each segment ≤ 64 chars | | Encoding | URL-safe; the segment delimiter / does not need escaping inside path query parameters when passed as ?path=... |

Views (how recalls traverse scopes)

| View | Reads from | Traversal capability | |---|---|---| | raw, granular, structured | Just the scope | none | | holistic | Scope + ancestors | scope.read.holistic | | descend | Scope + descendants | scope.read.descend |

The default for layer reads is local (no traversal). The default for /v1/recall and /v1/answer is holistic.

Why one primitive

Older designs split namespacing across two or three concepts (tenant + namespace + workspace), each with its own ACL model. The result is duplicated policy logic and unclear leak boundaries. With a single hierarchical primitive:

  • One ACL model. Members + roles on a scope; inherited by descendants.
  • One quota model. Quota on a scope counts the subtree.
  • One audit model. Every audit row carries the scope path; ancestor queries are straightforward.

Common shapes

org:acme/user:alice                          # personal scope under an org
org:acme/dept:eng/team:platform              # team scope
org:acme/ws:q3-launch                        # workspace scope (cross-functional)
agent:planner_v3                             # agent's own scope (no org tier)

See API: Scopes for the CRUD surface.