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.
What is a Client?
A Client is the top-level organizational entity in Synap. It represents your company, team, or application. When you sign up for Synap and create an account, you are creating a Client. Every Client has a unique identifier in the formatcli_<hex16> (for example, cli_a3f8b1c2d4e5f678). This identifier is immutable and used throughout the Synap API and SDK to scope operations to your organization.
Client fields
| Field | Type | Description |
|---|---|---|
client_id | string | Unique identifier. Format: cli_<hex16>. Immutable after creation. |
name | string | Human-readable organization name. Used in the Dashboard and audit logs. |
website | string | Organization website URL. Optional, used for identification. |
description | string | Free-text description of the organization or use case. |
context | JSONB | Arbitrary metadata stored as JSON. Use for internal tagging, billing references, or integration metadata. |
status | enum | One of active, inactive, or soft_deleted. Controls whether the Client’s Instances can operate. |
created_at | timestamp | When the Client was created. Set automatically. |
updated_at | timestamp | When the Client was last modified. Updated automatically on changes. |
When a Client is set to
inactive or soft_deleted, all of its Instances are effectively suspended. No ingestion or retrieval operations will succeed until the Client is reactivated.What is an Instance?
An Instance is a deployed Synap memory agent. It is the unit of deployment — each Instance has its own isolated memory store, configuration, credentials, and scope hierarchy. You create Instances under a Client to represent different AI agents, environments (staging vs. production), or use cases. Every Instance has a unique identifier in the formatinst_<hex16> (for example, inst_7b2e9a1c3d4f5678).
Instance fields
| Field | Type | Description |
|---|---|---|
instance_id | string | Unique identifier. Format: inst_<hex16>. Immutable after creation. |
client_id | string | The Client this Instance belongs to. Links to the parent organization. |
agent_type | string | Describes the type of agent (e.g., support-bot, sales-assistant, personal-ai). Informational. |
status | enum | One of active, inactive, suspended, initializing, or deleting. Controls operational state. |
parent_instance_id | string | null | Optional. If set, this Instance is a child in a hierarchical Instance tree. |
metadata | JSONB | Arbitrary metadata. Use for environment tags, version tracking, or deployment metadata. |
created_at | timestamp | When the Instance was created. |
updated_at | timestamp | When the Instance was last modified. |
Instance lifecycle
Every Instance progresses through a well-defined lifecycle. Understanding these states helps you manage deployments and debug issues.Provisioning
When you create a new Instance (via the Dashboard), it enters the
provisioning state. During this phase, Synap allocates storage namespaces and applies the initial Memory Architecture Configuration. The Instance is not operational in this state — ingestion and retrieval calls will be rejected.Active
Once initialization completes, the Instance transitions to
active. This is the normal operational state. The Instance accepts ingestion requests, processes memories through the pipeline, and serves retrieval queries. All authentication credentials are valid.Inactive
An Instance can be set to
inactive manually from the Dashboard to temporarily pause operations. Memories are preserved but no new ingestion or retrieval is processed. Use this for planned maintenance, cost management, or temporary decommissioning. Reactivating an Instance restores full functionality.Suspended
A
suspended Instance has been forcibly disabled, typically due to policy violations or billing issues. Unlike inactive, suspension can only be lifted by Synap support. All operations are blocked.
What each Instance owns
Each Instance is a fully isolated environment. When you create an Instance, Synap provisions the following resources exclusively for it:API Keys
One or more API keys (format:
synap_<random>) generated from the dashboard. Each key authenticates the SDK. The SHA-256 hash is stored; the raw key is shown once at generation time and can be individually revoked.Memory Architecture Config
The per-instance Memory Architecture Configuration (MACA) that controls how memories are extracted, stored, and retrieved. Synap generates it automatically from the Use-Case Markdown file you upload at instance creation — the more detail you provide there, the better the starting configuration. See Customized Memory Architectures and Use-Case Markdown.
Memory Store
Isolated vector and graph storage namespaces. Memories stored in one Instance are never accessible from another Instance unless explicitly shared through scope configuration.
Scoped Memory Boundaries
Within an Instance, memory is isolated along the scope chain (User → Customer → Client), enforced at the storage layer. See Memory Scopes.
Analytics & Audit Trail
Per-Instance metrics for ingestion throughput, retrieval latency, memory counts, and pipeline health. All operations are audit-logged with timestamps and actor identity.
Hierarchical Instances
Instances can be organized in a parent-child hierarchy by setting theparent_instance_id field. This is useful when you need to model complex deployment topologies.
When to use hierarchical Instances
- Multi-environment deployments: A parent Instance for production with child Instances for staging and development, sharing common configuration patterns
- Multi-tenant applications: A parent Instance per major customer segment, with child Instances for individual tenants that inherit baseline configuration
- Agent teams: A parent Instance for a team of AI agents where child Instances represent individual specialized agents that share organizational knowledge
parent_instance_id pointing at the parent. Both creates happen through Dashboard → Instances → New Instance.
Hierarchical Instances are an organizational tool. Memory isolation is still enforced per-Instance. If you need child Instances to access parent memories, configure shared scoping at the Client level. See Memory Scopes for what Client scope means.
Managing Clients and Instances
Clients and Instances are created and managed through the Dashboard. The SDK runs inside an Instance once it exists; it does not create or list Instances. Navigate to Instances in the left sidebar of the Synap Dashboard. From there you can:- View all Instances with status indicators
- Create new Instances with guided setup
- Edit Instance metadata and configuration
- Monitor Instance health and pipeline metrics
- Suspend or deactivate Instances
Next steps
Memories & Context
Learn how data flows through Synap from ingestion to retrieval.
Memory Scopes
Understand how memory isolation works across users, customers, and organizations.
Authentication
Deep dive into Synap’s authentication with API keys.
Memory Architecture
Configure how your Instance stores, processes, and retrieves memory.