Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt

Use this file to discover all available pages before exploring further.

Most Synap deployments are single-agent: one AI agent, backed by one Instance running one Memory Architecture Configuration (MACA). All memory flows through that single Instance, and the people your agent serves are kept separate by scopes — not by running additional Instances.
If you have one agent with a single, coherent purpose, you want a single-agent architecture. You do not create a new Instance per user or per customer — scopes handle that isolation for you.

​
What “single-agent” means in Synap

A single-agent architecture has three fixed pieces:
  • One Instance — the deployed unit that owns the memory store and credentials.
  • One MACA — generated automatically from the Use-Case Markdown file you upload at creation. It governs what gets extracted, how it is stored, and how retrieval ranks results for this agent.
  • Scopes for isolation — every memory is written and read at a scope in the chain User → Customer → Client. Two different end-users on the same Instance never see each other’s memories, because their memories live at different user_id scopes.
The Instance is infrastructure; the scope chain is what isolates memory. You scale the number of people your agent serves by passing more user_id / customer_id values — never by provisioning more Instances.

​
The three single-agent shapes

The right way to map your world onto Synap’s scopes depends on who your agent serves. Describe these roles in the Role Descriptions section of your use-case file, and Synap tunes the MACA’s primary scope accordingly.

Personal assistant

One person is the Client, Customer, and User at once. The scope hierarchy collapses — effectively everything is User-scoped. Best for consumer apps where each account is a single individual.

Single-tenant app

One organization (Customer) with many individual Users. Shared organizational knowledge lives at Customer scope; personal context lives at User scope.

B2B multi-tenant

Many Customers, each with many Users — all served by the same agent on one Instance. The most common SaaS shape. Customer scope isolates tenants; User scope isolates individuals within a tenant.
All three are single-agent: they differ only in how you populate the scope chain, not in how many Instances or MACAs you run.

​
How memory is governed

The single MACA is the whole memory architecture for the agent. It decides which memory types are extracted, how memories are partitioned across scopes, which retrieval modes are available, and how long memories are retained. You do not author or tune it directly — you describe the agent in the use-case file and Synap generates the configuration. 
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(api_key="synap_api_key")

# Same Instance, different people — isolated by scope, not by Instance
await sdk.memories.create(
    document="User: I prefer concise answers and dark mode.",
    document_type="ai-chat-conversation",
    user_id="user_alice",
    customer_id="acme_corp",
)

await sdk.memories.create(
    document="User: Always include code examples in responses.",
    document_type="ai-chat-conversation",
    user_id="user_bob",
    customer_id="acme_corp",
)

# Alice's retrieval never surfaces Bob's preferences
context = await sdk.user.context.fetch(
    user_id="user_alice",
    customer_id="acme_corp",
)

​
Scaling a single agent

A single-agent architecture scales to many users and customers without any change to its topology:
  • More users or customers never require more Instances. Pass new user_id / customer_id values and the scope chain isolates them automatically.
  • Staging vs. production is a separate concern. Use a distinct Instance per environment so test data never mixes with production memory — each is still a single-agent deployment.
  • Behavior changes (new task categories, new compliance rules) are made by re-uploading the use-case file, which regenerates the MACA. The topology stays the same.
Separate Instances for staging and production is an environment split, not a multi-agent architecture. You still have one agent per Instance, each with its own MACA.

​
When to graduate to multi-agent

Stay single-agent as long as your deployment is one agent with one purpose. Consider a multi-agent architecture when:
  • You run specialized agents (e.g., a sales agent and a support agent) that should share what they learn about the same users, or
  • Different agents need materially different extraction behavior (a different MACA per role), or
  • You are modeling a team of agents under one organizational umbrella.

​
Next steps

Multi-Agent Memory Architecture

Architect memory across several agents — shared scopes, separate Instances, or agent teams.

Memory Scopes

How the Client, Customer, and User scopes isolate and share memory.

Customized Memory Architectures

The MACA that Synap generates for your Instance.

Use-Case Markdown

The file that describes your agent and shapes its MACA.