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:engwithview=descendtraverses intoorg:acme/dept:eng/user:alice; a read at…/user:alicewithview=holisticwalks 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 viaPOST /v1/scopessets 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 since v0.9.10; 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. The shipped presets allow org, dept, team, app, user, agent, service, ws, project, global, system, source; dev_local additionally allows debug and temp. source is there because
every connector writes into a <root>/source:<connector> segment. If your integration mints scopes of
another type, add it to allowed_scope_types in the deployment policy
before upgrading from v0.9.9 or earlier.
The ≤ 8 segments and ≤ 64 chars/segment limits are recommendations: longer paths and segments are accepted, so keep to them in your own naming.
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(), …) islocal(no traversal). - The default for
/v1/recalland/v1/answerisholistic. - On
/v1/recall,view: "local"is accepted and normalizes togranular.
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
holisticrecall 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.
See also
- Authorization — the four-tier capability stack.
- Lifecycle — how writes flow through scopes asynchronously.