Identifiers & Scopes

CLIENT (your application)         cli_<hex16>
  └── INSTANCE (a deployed agent) inst_<hex16>   ← resolved from your API key
        └── CUSTOMER (a tenant)   customer_id     ← B2B only; auto-resolved on B2C
              └── USER            user_id
                    └── CONVERSATION  conversation_id

import uuid

conversation_id = str(uuid.uuid4())

from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(api_key="your_api_key")

# User-scoped memory (most specific), pass customer_id only on B2B
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_alice",
    customer_id="acme_corp"
)

# Customer-scoped memory (shared across users in the organization)
await sdk.memories.create(
    document="""
    Acme Corp Engineering Standards:
    - All services use Python 3.11+ and PostgreSQL
    - Code reviews require two approvals before merge
    - Deployments happen on Tuesdays and Thursdays
    """,
    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
)

# Full scope chain retrieval for a specific user (user + customer + client + world)
context = await sdk.user.context.fetch(
    user_id="user_alice",
    customer_id="acme_corp",
    search_query=["budget review process"]
)

# context.facts might include:
# - "Alice prefers dark mode" (USER scope, highest priority)
# - "Acme Corp deploys Tues/Thurs" (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",
    search_query=["engineering standards"]
)

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