Namespacing & Navigation
Atlas uses a two-level isolation model: org namespace (from your API key)
and session sub-namespace (from session_id).
How it works
API Key → org_namespace: acme_corp_a1b2c3
session_id → acme_corp_a1b2c3:user-456
- Every API key maps to exactly one org namespace
user_id in request bodies is always overridden server-side from your key —
clients cannot access another org’s data- Adding
session_id creates an isolated sub-namespace within your org
Use cases for session_id
| Use case | Recommended session_id |
|---|
| Per-user memory in a SaaS app | user-{uuid} |
| Per-conversation isolation | conv-{uuid} |
| Per-agent in a multi-agent system | agent-{name} |
| Shared team memory | Omit session_id |
Multi-tenant example
# Tenant A — completely isolated
brain_a = CognitiveBrain(
api_key="atlas_...",
user_id="any_value", # overridden server-side
session_id="tenant-acme",
)
# Tenant B — same API key, different namespace
brain_b = CognitiveBrain(
api_key="atlas_...",
session_id="tenant-globex",
)
# These two never see each other's memories
brain_a.add("Our CTO is Alice.")
brain_b.search("Who is the CTO?") # Returns nothing
Clearing a namespace
# Clear all memories for one session
DELETE /brain/clear?session_id=tenant-acme&user_id=your_namespace
# Clear all memories for the entire org (irreversible)
DELETE /brain/clear?user_id=your_namespace
/brain/clear without session_id deletes all memories for your API key.
This cannot be undone.
