Library, Scope, Topic, Atom: a memory model that scales with your agent fleet
Four layers answer whose memory, which domain, which subject, and which fact—how to model multi-tenant agents without mixing customer contexts.
Four questions, four layers
• Library — Which isolated memory workspace? Pass memoryLibraryId; engine binds libraryKey (library-{uuid}). • Scope — Which domain? Billing, infra, legal, product roadmap. • Topic — Which subject within the scope? Q2 renewal, VPC migration, API rate limits. • Atom — The atomic fact or narrative you retrieve and cite.
Read the full terminology in the concept guide before wiring REST or MCP clients.
Why hierarchy beats tags alone
Flat tags rot. Teams add customer-id, project-id, random labels—then retrieval becomes “search everything and hope.” Hierarchy gives you predictable filters: recall within a Topic, search within a Scope, never leak atoms across Libraries.
Multi-tenant SaaS agents should map each end-customer to Scope (or Topic) boundaries so one user’s atoms never surface in another user’s session.
Atoms are the retrieval unit
An atom is not a chunk. It is a deliberate unit of memory—often one decision, one preference, one procedure step—with optional attachments stored in object storage and indexed for semantic search.
Creating atoms via POST /api/v1/memory/atoms or memory_save_atom should always include hierarchy fields. Retrieval quality depends on metadata as much as embedding text.
Path backlinks
Atoms link to related atoms—supporting evidence, superseded decisions, upstream policies. Wake-up and recall traverse these paths so agents see context chains, not isolated snippets.
Getting started
Model one Library and two Scopes for your first memory library. Save ten atoms with clear Topics. Run memory_wake_up and memory_search from Cursor to validate retrieval before scaling ingestion.