Scopes

What is a scope tree?

A scope tree is a hierarchical namespace structure that isolates grains by tenant, environment, or agent. You define ordered levels (organization, environment, agent) that constrain how grains are organized.

Scopes solve the multi-tenancy problem for AI memory at the data layer. Instead of running separate memory instances per tenant, you run one context database with a scope tree that enforces isolation. Each grain lives at a specific path like acme/prod/bot1, and recall queries restricted to a scope path only return grains within that subtree. This lets a single Areev instance serve thousands of autonomous memory partitions without cross-contamination.

The tree defines the shape of the hierarchy, not the data. Grains are placed into scopes by setting their namespace to a slash-separated path. The tree levels validate that paths conform to the expected structure. If you define three levels (organization, environment, agent), then acme/prod/bot1 is valid but acme/bot1 would skip a level.

PUT /api/memories/multi-tenant/scope-tree
Content-Type: application/json

{
  "id": "main",
  "levels": [
    {"name": "organization", "description": "Top-level tenant"},
    {"name": "environment", "description": "Deployment environment"},
    {"name": "agent", "description": "Individual agent instance"}
  ],
  "created_at_ms": 1709251200000
}
areev scope-tree-set --file scope-tree.json
areev scope-tree-get --json

How do I query within a scope?

Add scope_path to your recall request to restrict results to grains within that scope. Use include_siblings to also search sibling namespaces at the same depth.

Scoped queries are the primary access pattern for multi-tenant AI agent memory. When you set scope_path to acme/prod/bot1, only grains in that exact namespace are returned. With include_siblings set to true, Areev also searches sibling scopes at the same depth — acme/prod/bot2, acme/prod/bot3, and so on. This is useful when agents in the same environment need to share context.

Scope filtering happens at the index layer, not as a post-retrieval filter. This means scoped queries are as fast as unscoped ones — the engine only scans the relevant namespace partition. All other recall parameters (query, subject, filters, limits) work identically within a scoped request.

import areev

db = areev.open("./my-data")
hits = db.recall(query="user preferences", scope_path="acme/prod/bot1")
hits = db.recall(query="user preferences", scope_path="acme/prod/bot1", include_siblings=True)
POST /api/memories/multi-tenant/recall
Content-Type: application/json

{
  "query": "user preferences",
  "scope_path": "acme/prod/bot1",
  "include_siblings": true,
  "limit": 20
}
areev recall --query "user preferences" --scope-path acme/prod/bot1 --include-siblings

How do I erase an entire scope?

Use POST /api/memories/{id}/scope-erase to crypto-erase all grains in a scope path. This destroys the encryption key for that scope, making all grains in it permanently unreadable.

Scope erasure is the tenant-level data destruction mechanism. It satisfies GDPR Art. 17 for an entire tenant or environment in a single call. The response returns an erasure proof with scope_path, count, key_fingerprint, and timestamp — a compliance-grade record that demonstrates the data was destroyed.

Scope erasure is irreversible. All grains in the scope path become indecipherable ciphertext. Use this when offboarding a tenant, decommissioning an environment, or fulfilling a regulatory erasure request that covers an entire context database partition.

POST /api/memories/multi-tenant/scope-erase
Content-Type: application/json

{
  "scope_path": "acme/staging"
}
areev forget scope acme/staging

How do I manage the scope tree?

Retrieve the current tree with GET, update it with PUT, or remove it with DELETE. Deleting the scope tree does not delete grains — it only removes the hierarchy definition.

When you update the scope tree, existing grains are not migrated. Their namespace paths remain unchanged, and the new tree definition applies only to validation of future operations. This means you can reshape the hierarchy without disrupting stored data, though old grains may not conform to the new level structure.

The tree is a schema-level construct that guides organization. It does not retroactively enforce structure on existing grains — treat it as a forward-looking contract for how new data enters the system.

GET /api/memories/multi-tenant/scope-tree

PUT /api/memories/multi-tenant/scope-tree
Content-Type: application/json

{
  "id": "v2",
  "levels": [
    {"name": "tenant"},
    {"name": "region"},
    {"name": "service"},
    {"name": "instance"}
  ],
  "created_at_ms": 1709337600000
}

DELETE /api/memories/multi-tenant/scope-tree
areev scope-tree-get --json
areev scope-tree-set --file updated-tree.json