Skip to main content
Start with user-scoped memories. Add customer and client scopes as your application grows. You can always broaden scope later — narrowing scope after the fact requires re-ingestion.

​
The scope chain

Synap uses a four-level hierarchical scope chain, ordered from narrowest (most private) to broadest (most shared):
Scope chain hierarchy: User (narrowest) to Customer to Client to World (broadest)
USER → CUSTOMER → CLIENT → WORLD
 ↑                              ↑
 Most private             Most shared
 Narrowest                Broadest
When Synap retrieves memories, it searches the scope chain from narrowest to broadest. User-scoped memories take priority over customer-scoped memories, which take priority over client-scoped, and so on. This ensures that the most specific, relevant memories surface first.

​
Scope levels

​
User scope

The most granular scope. Memories stored at the user level are visible only when that specific user is the context for a retrieval query. Use this for personal information, individual preferences, and conversation-specific knowledge.
AspectDetail
VisibilityOnly when user_id matches the query
IsolationComplete — no other user can see these memories
Use casesPersonal preferences, individual history, private conversations
Examples:
  • “User prefers dark mode and concise responses”
  • “User’s name is Alice Chen”
  • “User is based in Portland, Oregon”
  • “User is preparing for an annual review next week”

​
Customer scope

Memories shared across all users within a customer or organization. Use this for company-wide knowledge, shared context, and organizational facts. In a B2B SaaS application, a “customer” is typically one of your client’s end-customer organizations.
AspectDetail
VisibilityWhen customer_id matches the query, regardless of user_id
IsolationAll users within the customer can see these memories
Use casesCompany policies, shared projects, organizational structure
Examples:
  • “Acme Corp’s fiscal year ends in March”
  • “Company uses Jira for project management and Slack for communication”
  • “The engineering team is migrating to microservices”
  • “Primary contact for billing is [email protected]”

​
Client scope

Memories shared across all customers of your application. In the Synap hierarchy, you (the developer) are the Client. Client-scoped memories are visible to all users of all your customers. Use this for product knowledge, documentation, and announcements.
AspectDetail
VisibilityAll users across all customers of your application
IsolationNone within your application — all customers share these memories
Use casesProduct documentation, feature announcements, domain knowledge
Examples:
  • “Our product supports SSO with SAML and OIDC”
  • “Version 3.2 introduces bulk import for CSV files”
  • “Billing inquiries should be directed to [email protected]”
  • “The API rate limit is 1000 requests per minute”

​
World scope

Global knowledge shared across all Instances. This is rarely used directly by application developers. It exists primarily for Synap-managed global knowledge and cross-instance shared resources.
AspectDetail
VisibilityAll Instances, all customers, all users
IsolationNone — truly global
Use casesGeneral domain knowledge, shared ontologies, global entity registries
Examples:
  • General domain knowledge applicable across all applications
  • Shared entity type definitions
  • Universal formatting conventions
Most applications only need User and Customer scopes. Client scope is useful for product-wide knowledge, and World scope is managed by Synap internally. You do not need to use all four levels.

​
How scoping works with retrieval

When your agent fetches context, Synap merges memories from all applicable scopes in the chain. The merge follows a strict priority order: narrower scopes take precedence over broader scopes.

​
Retrieval flow

1

Identify applicable scopes

Based on the user_id and customer_id in the retrieval request, Synap determines which scopes to search. If both are provided, all four scope levels are searched. If only customer_id is provided, User scope is excluded.
2

Search each scope

The retrieval engine searches vector and graph stores within each applicable scope level, returning candidate memories from each.
3

Merge and deduplicate

Candidates from all scopes are merged. If the same fact exists at multiple scope levels (e.g., a user-scoped fact and a customer-scoped fact about the same topic), the narrower-scoped version takes priority.
4

Rank and return

Merged candidates are ranked using the configured ranking signals (recency, relevance, confidence) and returned up to the configured budget limits.

​
Priority resolution example

Consider a scenario where conflicting information exists at different scopes:
ScopeMemoryPriority
User”Preferred language: French”Highest (returned)
Customer”Company language: English”Lower (returned as additional context)
Client”Default language: English”Lowest (may be returned if token budget allows)
In this case, the user’s language preference (“French”) surfaces first because user scope has the highest priority. The customer-level default (“English”) is still available as additional context, letting your agent understand both the personal preference and the organizational default.

​
Scoped ingestion and retrieval

​
Ingesting memories with scope

When you ingest content, the scope is determined by the user_id and customer_id parameters: 
from synap import Synap

sdk = Synap(api_key="your_api_key")

# User-scoped memory (most specific)
await sdk.memories.create(
    document="User: My name is Alice and I prefer dark mode.\nAssistant: Noted!",
    document_type="ai-chat-conversation",
    user_id="user_123",
    customer_id="acme_corp"
)

# Customer-scoped memory (shared across users in the organization)
await sdk.memories.create(
    document="Acme Corp's engineering team uses Python 3.11 and PostgreSQL for all services.",
    document_type="document",
    customer_id="acme_corp"
    # No user_id — scoped to customer level
)

# Client-scoped memory (shared across all customers)
await sdk.memories.create(
    document="Our platform now supports webhook notifications for ingestion completion.",
    document_type="document"
    # No user_id or customer_id — scoped to client level
)

​
Retrieving memories across scopes

When retrieving, Synap automatically includes all applicable scope levels: 
# Retrieve with full scope chain (user + customer + client + world)
context = await sdk.user.context.fetch(
    user_id="user_123",
    customer_id="acme_corp"
)

# context.facts might include:
# - "Alice prefers dark mode" (user scope)
# - "Acme Corp uses Python 3.11" (customer scope)
# - "Platform supports webhook notifications" (client scope)

# Retrieve without user scope (customer + client + world only)
context = await sdk.customer.context.fetch(
    customer_id="acme_corp"
)

# Retrieve client scope only
context = await sdk.client.context.fetch()

​
Scope hierarchy table

ScopeIdentified byVisible toTypical contentPriority
Useruser_id + customer_idOnly that userPersonal preferences, individual historyHighest
Customercustomer_idAll users in that customer orgCompany policies, shared projectsHigh
ClientImplicit (your application)All users across all customersProduct docs, announcementsMedium
WorldGlobalAll Instances everywhereGeneral domain knowledgeLowest

​
Common scoping patterns

For a personal AI assistant serving one user at a time with no multi-tenant requirements.Ingest everything with user_id. Each user has completely isolated memory.
For a B2B application where each customer organization has multiple users, and you need both per-user personalization and shared organizational knowledge.Ingest user conversations with user_id + customer_id. Ingest company documents with just customer_id. Use client scope for product documentation.
For an application where all users share the same knowledge base and there is no per-user personalization.All memories are at the Instance level. No user or customer isolation. Simplest setup but no personalization.
For an application where organizational knowledge is primary but individual users can have some personal preferences.Default scope is customer. Personal preferences can be added by including user_id on specific ingestion calls.

​
Next steps

Entity Resolution

Learn how entities are resolved within scope boundaries.

Memory Architecture

Configure scoping strategies in MACA.

Multi-User Scoping Guide

Step-by-step guide to implementing multi-user, multi-tenant memory.

Clients & Instances

Understand the organizational hierarchy that scopes operate within.