Scopes

Hierarchical scopes are CortexDB's single namespace primitive — precise memory partitions as delimited paths of type:id segments.

A scope is a /-delimited path of type:id segments (e.g. org:acme/dept:eng/user:alice). Scopes are CortexDB's single namespace primitive, replacing the separate "tenant", "namespace", and "workspace" concepts of older systems with one hierarchical model that carries ACLs, quotas, and audit uniformly.

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 traverses into org:acme/dept:eng/user:alice; a read at …/user:alice with view=holistic walks up to ancestors.
Carry policy. A scope can declare retention, default view, members, and ACLs that compose with tenant and deployment policy.
Auto-provision. 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.

Scope path shape

A scope is one or more type:id segments joined by /. Each segment must contain a : — a bare word is rejected (422 INVALID_BODY). Left-most is outermost.

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                   # an agent's own scope (no org tier)

Scope types are validated on creation; depth and length are not

The first write into a new scope segment whose type is outside the deployment's defaults.allowed_scope_types is refused with 422 UNREGISTERED_SCOPE_TYPE ("scope type banana is not in deployment defaults.allowed_scope_types"). Existing scopes are unaffected: the check runs only when a scope is created. Which types are allowed depends on the deployment preset (table below). If your self-hosted integration mints scopes of another type, add it to allowed_scope_types in the deployment policy first.

The ≤ 8 segments and ≤ 64 chars/segment limits are recommendations: longer paths and segments are accepted, so keep to them in your own naming.

Allowed scope types

Deployment	Preset	Allowed scope types
Hosted CortexDB cloud	`cloud_shared_saas`	`org`, `dept`, `team`, `app`, `user`, `agent`, `service`, `ws`, `project`, `source` (10)
Self-hosted, one organization	`on_prem_enterprise`	the 10 above plus `global` and `system` (12)
Dedicated single-tenant cloud	`cloud_private`	the 10 above plus `global` and `system` (12)
Local development and evaluation (the default preset)	`dev_local`	the 12 above plus `debug` and `temp` (14)
Self-hosted, many tenants	`cloud_shared_saas`	the same 10 as the hosted cloud

See Deployment Presets for how to choose one (CORTEX_DEPLOYMENT_PRESET).

source is there because every connector writes into a <root>/source:<connector> segment. On the hosted cloud a source: scope is created by the first write into it; registering one by hand with POST /v1/scopes is not allowed there (it needs scope.create.custom).
global (a cross-tenant pool) and system are not available on the hosted cloud.
A type outside the list, such as channel: or repo:, is refused on the first write into a new scope. Put the name under an allowed type instead: org:acme/source:slack/project:general.

Recall views and traversal

View	Reads from	Traversal capability
`raw`, `granular` (alias `local`), `structured`	just the scope	none
`holistic`	scope + ancestors	`scope.read.holistic`
`descend`	scope + descendants	`scope.read.descend`
`lineage`	supported (specialized)	—

The default for layer reads (facts(), beliefs(), …) is local (no traversal).
The default for /v1/recall and /v1/answer is holistic.
On /v1/recall, view: "local" is accepted and normalizes to granular.

What scopes enable

Unified security — the four-tier capability stack (Deployment → Tenant → Scope → Actor) enforces "outer deny is final": no descendant can override an ancestor's denial. See Authorization.
Dynamic context traversal — a holistic recall pulls ancestor context without switching keys.
Native multi-tenancy — hierarchy and isolation are built into the database, not app middleware.

FAQ

What is a scope? A type:id-segment path that defines a partitioned memory boundary — the single namespace primitive, replacing tenant/workspace models.

How do scopes interact with the capability stack? Scopes are the third tier (Deployment, Tenant, Scope, Actor); policy is evaluated hierarchically with "outer deny is final."

What is a holistic recall view? It queries the current scope and all ancestors simultaneously, blending personal memory with organizational knowledge.

Can agents access memory outside their scope? No — access is enforced at the storage level; agents cannot traverse hierarchy edges without explicit capabilities.