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.

A multi-agent architecture runs more than one agent against Synap — for example a sales agent, a support agent, and an onboarding agent that together serve the same users. The central question is always the same: which agents should share what they remember, and which should stay isolated?
If you have one agent with one purpose, you want a single-agent architecture. Reach for multi-agent only when distinct agents either need to share memory about the same users or need materially different memory behavior.

​
The key rule: sharing is by scope, not by Instance

An Instance is infrastructure — it is not a memory scope. What two agents share is decided entirely by the scope IDs they address: if they ingest and retrieve with the same user_id and customer_id, they share that user’s and customer’s memories. The scope chain (User → Customer → Client) is the sharing boundary; the Instance boundary is the isolation boundary. Keep this rule in mind as you choose a pattern below — every option is just a different combination of which Instance agents run on and which scopes they address.

​
Three architecture patterns

PatternMACAMemory sharingUse when
Shared Instance + shared scopesOne MACA for all agentsFull, automatic sharing via the same user_id / customer_idAgents serve the same users and should each benefit from what the others learn
Separate Instance per agentA tailored MACA per agent roleIsolated by Instance; overlap only at Client scope if you write thereAgents have very different extraction needs, or must not see each other’s memory
Hierarchical Instances (agent teams)Per-Instance MACA, organized under a parentOrganizational grouping via parent_instance_id; isolation still per-InstanceYou are modeling a team of agents under one umbrella

​
Shared Instance + shared scopes

All agents run on one Instance and address the same scopes. Because memory is keyed by scope, every agent automatically sees what the others have stored for that user or customer. This is the simplest and most common multi-agent setup — and it is exactly the runtime pattern shown in Agent Interactions. 
# Sales agent stores context for a user
await sdk.memories.create(
    document="User: We're evaluating the enterprise plan for 500 seats.",
    document_type="ai-chat-conversation",
    user_id="user_123",
    customer_id="acme_corp",
)

# Support agent — same Instance, same scopes — sees it automatically
context = await sdk.user.context.fetch(
    user_id="user_123",
    customer_id="acme_corp",
    search_query=["enterprise plan and SSO"],
)
# context surfaces the sales conversation without the user repeating it
One MACA governs all the agents here, so they share both memory and extraction behavior.

​
Separate Instance per agent

Give each agent its own Instance — and therefore its own MACA generated from its own Use-Case Markdown. A support agent can prioritize extracting error details and resolutions, while a sales agent prioritizes buying signals and account context. Memory is isolated per Instance: the agents do not automatically see each other’s memories. Use this when agents have genuinely different jobs, or when policy requires their memories to stay separate. If two such agents still need a shared baseline (e.g. product knowledge), write that knowledge at Client scope in each Instance, or keep a dedicated knowledge Instance — but per-user context will not cross the Instance boundary.

​
Hierarchical Instances (agent teams)

When you have a team of specialized agents that belong together, model them as hierarchical Instances: create a parent Instance and point each child’s parent_instance_id at it. This is an organizational tool for grouping related deployments and sharing configuration patterns. Memory isolation is still enforced per-Instance — hierarchy organizes your agents, it does not merge their memory.

​
Choosing scopes for multi-agent

Once you have picked a pattern, decide deliberately what to share:
  • To share across agents, have them address the same user_id / customer_id. User- and Customer-scoped memories then flow between them automatically.
  • To isolate agents, give them separate Instances — the Instance boundary prevents per-user memory from leaking between agents even if they happen to use the same IDs.
  • For knowledge every agent should see, write it at Client scope (no user_id / customer_id); it is visible to all retrievals within an Instance.

​
MACA implications

There is exactly one MACA per Instance. That single fact drives the build-vs-split decision:
  • Agents that should share memory and behave the same way → put them on one Instance (one MACA).
  • Agents that need different extraction priorities, retention, or compliance handling → give them separate Instances (separate MACAs), and accept that per-user memory will not automatically cross between them.

​
Relationship to Agent Interactions

This page covers the architecture decision — how many Instances, which scopes, one MACA or several. Agent Interactions covers the runtime loop: how an individual agent retrieves context and ingests each turn during a conversation. Read this page to decide the topology; read that one to implement the request/response cycle.

​
Next steps

Single-Agent Memory Architecture

The default topology: one agent, one Instance, one MACA.

Clients & Instances

Instances, isolation, and hierarchical Instances for agent teams.

Memory Scopes

The scope chain that determines what agents share.

Agent Interactions

The runtime retrieve-and-ingest loop for a single agent.