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)Recommended conventions — not enforced in v0.9.9
The following are conventions the server does not currently enforce (verified on v0.9.9): the built-in
type set (org, dept, team, user, agent, service, system, ws), the ≤ 8 segments limit, and the
≤ 64 chars/segment limit. A scope like banana:x/user:y, a 9-segment path, or a 70-char segment all
write successfully (202). Treat these as recommended (and possibly reserved) rather than hard rules until
enforcement lands — don't rely on the server to reject a malformed scope.
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.