Production Checklist

Run through this checklist before every production deployment, not just the first one. Configuration changes, SDK upgrades, and new features each warrant a fresh review.

Authentication and Security

Credential management is the foundation of a secure Synap integration. A compromised API key gives an attacker full access to your instance’s memory store.

API key stored in a secrets manager

Never hardcode API keys in source code, environment files committed to version control, or Docker images. Use a proper secrets manager:

AWS: Secrets Manager or SSM Parameter Store
GCP: Secret Manager
Azure: Key Vault
Self-hosted: HashiCorp Vault

# Good: loaded from secrets manager at runtime
import boto3

def get_api_key():
    client = boto3.client("secretsmanager")
    response = client.get_secret_value(SecretId="synap/api-key")
    return response["SecretString"]

sdk = MaximemSynapSDK(
    api_key=get_api_key()
)

API key is stored in a secrets manager (not in code, .env files, or container images)

Webhook signature verification implemented

If you receive webhooks from Synap, always verify the signature before processing the payload. Unverified webhooks can be spoofed by attackers.

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Webhook signature verification is implemented and tested

API key rotation schedule established

API keys should be rotated periodically. You can have multiple active keys per instance, so rotation is zero-downtime: generate a new key, roll it out, then revoke the old one.

Recommended rotation cadence: every 90 days for standard deployments, every 30 days for high-security environments
Document the rotation procedure in your team’s runbook
Automate rotation if possible (e.g., via a cron job or CI/CD step)

A long-running process needs one extra step. An SDK keeps the credential it was constructed with for its whole life, so rolling the new key into your secrets manager is not by itself enough to make a live process use it. If you construct with MaximemSynapSDK(api_key=...), the new key produces a new SDK and takes effect immediately. If you construct with an explicit instance_id, that id is the identity and you get the existing SDK back (still on the old key), so await sdk.shutdown() before reconstructing, or restart the worker. Do that before revoking the old key, or in-flight requests will start failing authentication.

API key rotation schedule is established and documented

The runbook says how running processes pick up the new key (reconstruct after shutdown(), or restart), and that this happens before the old key is revoked

One API key per SDK, on a supported version

If a single process ever holds more than one Synap API key (a key per customer or tenant, staging and production side by side, or a worker that switches keys between jobs) pin maximem-synap ≥ 0.4.1.On 0.4.0 and earlier, the second and later SDKs constructed in one process silently adopted the first one’s credentials, so their reads returned the first key’s memory and their writes were committed against that instance. It produced no error and no log line. A process that uses a single API key was never affected.

pip install --upgrade "maximem-synap>=0.4.2"

maximem-synap is pinned to ≥ 0.4.1 (≥ 0.4.2 recommended) if any process uses more than one API key

SDK Configuration

Proper SDK configuration ensures your integration performs well under production load and does not generate excessive logging or resource usage.

Log level set appropriately

In production, set log_level to "WARNING" or "ERROR". The "DEBUG" and "INFO" levels generate high-volume output that degrades performance and can expose sensitive information in log aggregators.

config = SDKConfig(
    log_level="WARNING"    # Not "DEBUG" or "INFO" in production
)

log_level is set to "WARNING" or "ERROR" (not "DEBUG" or "INFO")

Timeouts configured for your SLA

Default timeouts are suitable for most applications, but review them against your latency requirements:

Timeout	Default	Guidance
`connect`	5s	Increase to 10s if your infrastructure has high network latency
`read`	30s	Decrease for latency-sensitive paths; increase for large batch operations
`write`	10s	Usually sufficient; increase for large document ingestion

config = SDKConfig(
    timeouts=TimeoutConfig(
        connect=5.0,
        read=30.0,
        write=10.0
    )
)

Timeouts are reviewed and aligned with your application’s SLA requirements

Retry policy tuned

The default retry policy (3 attempts, exponential backoff with jitter) is appropriate for most use cases. Adjust if needed:

High-throughput systems: Reduce max_attempts to 2 to avoid retry storms
Critical operations: Increase max_attempts to 5 for reliability
Low-latency paths: Reduce backoff_max to limit total retry time

config = SDKConfig(
    retry_policy=RetryPolicy(
        max_attempts=3,
        backoff_base=1.0,
        backoff_max=10.0,
        backoff_jitter=True     # Always enable jitter in production
    )
)

Retry policy is reviewed and tuned for your workload profile

Cache backend enabled

The SQLite cache backend significantly improves retrieval performance for repeated queries. Ensure it is enabled:

config = SDKConfig(
    cache_backend="sqlite"     # Not None
)

cache_backend is set to "sqlite" for production performance

Session timeout configured

The session_timeout_minutes setting controls how long an authenticated session lasts before requiring re-authentication. The default is appropriate for most cases, but adjust based on your security requirements:

Standard applications: 60-480 minutes (1-8 hours)
High-security environments: 5-30 minutes
Long-running batch processes: 720-1440 minutes (12-24 hours)

session_timeout_minutes is configured appropriately (range: 5-1440)

Memory Architecture

Synap generates each Instance’s memory configuration automatically from the use-case file you upload. Before going to production, make sure that file reflects the agent you are actually deploying.

Use-case file accurately describes the production agent

The use-case Markdown you uploaded at instance creation drives every memory decision: which categories are extracted, how scopes are partitioned, what retention behavior applies. Review it now and re-upload an updated version if the agent’s purpose, audience, or compliance requirements have shifted since you created the Instance.

Use-case file reflects the production agent’s behavior, audience, and compliance posture

Verify retrieval quality on representative queries

Before going live, run a handful of representative production queries against the Instance and confirm the returned memories are relevant and complete. Catch retrieval drift before users do.

Retrieval quality validated on at least 10 representative queries

Confirm the Instance is in the active state

Check the Dashboard to confirm your Instance has moved from provisioning to active and that its memory architecture has been generated and applied. Do not start production traffic on an Instance that is still provisioning.

Instance status is active and ready to accept traffic

Sensitive Data

Synap detects sensitive values in the content you send and applies the policy you set. Until somebody reviews and approves that policy, your account is watching only: values are counted and reported, and nothing is changed. Watching is a reasonable place to start, but it should be a decision rather than an oversight.

Detection findings reviewed against real traffic

Open Sensitive data in the Dashboard and read the What we found tab. It lists what has actually been detected in your traffic, by field type, with counts and how many of your users each appeared for.Do this before you set anything. The list tells you what decision you are actually making, and it routinely contains something the team did not expect to be there.

The findings list has been reviewed by someone who knows what the data should contain

Policy set, tested, and approved by a named person

Set a policy, either from a preset or row by row, then check it in the Try it tab with text that looks like your real content before you approve it. Nothing takes effect until approval, and approval records who did it and when.Confirm you know which of your choices affect your application. Keep it, Protect at rest, and Hide from the model all leave your reads unchanged. Do not store it and Protect from everyone do not.

A policy is approved (not left as a draft), and the approver is recorded

The team knows which chosen settings change what the application reads back, and the application has been tested against them

Policy scope matches your instance layout

The policy applies to the whole account by default. If one instance handles materially different data, such as a regulated workload alongside a general one, give that instance its own policy rather than making the account-wide setting stricter for everything.

Policy scope (whole account, or per instance) is a deliberate choice

Restricted keys issued where a tool does not need values

An API key’s grant can only narrow what your policy allows, never widen it. Internal dashboards, support tools, and analytics jobs usually need to read memories without reading values; give those a masked or none key rather than a full one.Allow up to about a minute for a grant change to take effect on live traffic.

Any key used by a tool that does not need real values is restricted

Audit export and erasure path tested once, before you need them

Export the Activity trail once and confirm the file opens in whatever your compliance team uses. Confirm the team knows that erasing a person is requested through [email protected] and is irreversible, and that the request needs an instance and a user_id or customer_id.

Activity export has been produced and opened at least once

The runbook names who requests an erasure, and what information the request must carry

Detection has limits worth knowing before you rely on it: names and street addresses are not detected, health and origin/belief data are not detected, and images, audio, and scanned documents are not covered. See Sensitive Data Protection.

Error Handling

Robust error handling ensures your application degrades gracefully when Synap encounters issues, rather than crashing or returning empty responses.

All SynapError subtypes caught appropriately

Handle transient and permanent errors differently:

from maximem_synap.errors import (
    SynapError,
    NetworkTimeoutError,
    RateLimitError,
    ServiceUnavailableError,
    InvalidInputError,
    AuthenticationError,
)

try:
    context = await sdk.conversation.context.fetch(
        conversation_id=conv_id,
        search_query=[query],
        mode="fast"
    )
except (NetworkTimeoutError, ServiceUnavailableError) as e:
    # Transient: retry or fall back to no-memory mode
    logger.warning(
        "Synap unavailable (transient), proceeding without memory: %s "
        "(correlation_id=%s)", e, e.correlation_id
    )
    context = None
except RateLimitError as e:
    # Transient: respect retry_after
    logger.warning(
        "Rate limited, retry after %s seconds (correlation_id=%s)",
        e.retry_after_seconds, e.correlation_id
    )
    context = None
except InvalidInputError as e:
    # Permanent: fix the request
    logger.error("Invalid request to Synap: %s", e)
    raise
except AuthenticationError as e:
    # Permanent: credentials issue
    logger.critical("Synap auth failed: %s", e)
    raise

Error handling distinguishes between transient and permanent errors

Transient errors logged with correlation_id

Every SynapError includes a correlation_id field. Always log it: this is the primary identifier Synap support uses to trace issues.

except SynapError as e:
    logger.error(
        "Synap error: %s (correlation_id=%s)",
        e, e.correlation_id
    )

All error logs include the correlation_id from the Synap error

Graceful degradation implemented

Your application should continue functioning when Synap is unavailable, just without memory context. This is the single most important resilience pattern.

async def get_memory_context(sdk, conversation_id, query):
    """Retrieve memory context, returning None if unavailable."""
    try:
        return await sdk.conversation.context.fetch(
            conversation_id=conversation_id,
            search_query=[query],
            max_results=5,
            mode="fast"
        )
    except SynapError as e:
        logger.warning(
            "Memory retrieval failed, proceeding without context: %s",
            e
        )
        return None

# In your chat handler:
context = await get_memory_context(sdk, conv_id, user_message)

if context and context.facts:
    # Build enriched prompt with memories
    system_prompt = build_prompt_with_memories(context)
else:
    # Fall back to generic prompt, your app still works
    system_prompt = build_generic_prompt()

Application continues working (without memory) when Synap is unavailable

Rate limit handling with retry_after

When you receive a RateLimitError, respect the retry_after_seconds field before retrying:

except RateLimitError as e:
    await asyncio.sleep(e.retry_after_seconds)
    # Retry the operation

Rate limit errors are handled with proper backoff using retry_after_seconds

Monitoring

Observability is critical for understanding how your Synap integration performs in production and catching issues before they impact users.

Dashboard analytics reviewed regularly

The Synap Dashboard provides real-time analytics for each instance:

API call volume and success rate
Memory counts by category and scope
Ingestion throughput and processing latency
Retrieval latency percentiles (P50, P95, P99)

Establish a regular review cadence (at least weekly).

Dashboard analytics overview showing API volume, memory counts, and latency — The Dashboard analytics page shows key metrics for your instance.

Dashboard analytics are reviewed on a regular schedule

Webhooks configured for critical events

Set up webhooks to receive notifications for important events:

ingestion.failed: ingestion pipeline errors
credential.expiring: credentials approaching expiration
config.applied: configuration changes
retention.cleanup: memory retention cleanup completed

See Dashboard Webhooks for setup instructions.

Webhooks are configured for critical operational events

P95 latency baseline established

Synap does not publish per-operation latency SLOs; real numbers depend on your MACA configuration, payload sizes, retrieval mode, network path, and traffic shape. Measure your own staging baseline and set alert thresholds from that baseline.Recommended approach:

Run a representative mix of memories.create(), context.fetch() (both fast and accurate), and memories.batch_create() against your staging Instance.
Record P50 / P95 / P99 for each operation over a representative window (at least 1 hour of realistic traffic).
Set production alert thresholds at a multiple of your staging P95 (e.g., 2-3× P95) so normal variance doesn’t page you.
Re-baseline after any MACA change, SDK upgrade, or significant traffic-pattern shift.

P95 latency baselines are established from your own staging measurements and alert thresholds are derived from those baselines

Error rate alerts configured

Set up alerts in your monitoring system (Datadog, PagerDuty, CloudWatch, etc.) for:

Synap API error rate exceeding 1% over 5 minutes
Authentication failures (any occurrence)
Rate limit hits exceeding your expected threshold
Retrieval returning zero results when memories are expected

Error rate alerts are configured in your monitoring platform

Cost tracking enabled

If your Synap plan includes usage-based pricing, track your usage against budget:

API call volume (ingestion + retrieval)
Storage usage (vector + graph)
Bandwidth usage

The Dashboard provides usage breakdowns on the billing page.

Usage and cost tracking is enabled and reviewed regularly

Performance

Optimization ensures your integration meets latency requirements and minimizes unnecessary resource usage.

Using fast mode for latency-sensitive paths

Use mode="fast" for any operation in the critical path of user-facing requests. Reserve mode="accurate" for background tasks, research queries, or paths where the user is willing to wait.

# Real-time chat: use fast mode
# fast = single-pass vector + graph search
context = await sdk.conversation.context.fetch(
    conversation_id=conv_id,
    search_query=[query],
    mode="fast"
)

# Background analysis: use accurate mode
# accurate = same vector + graph search, plus LLM subquery decomposition + reranking
context = await sdk.conversation.context.fetch(
    conversation_id=conv_id,
    search_query=[query],
    mode="accurate"
)

// Real-time chat: use fast mode
// fast = single-pass vector + graph search
let context = await sdk.conversation.context.fetch({
  conversation_id: conv_id,
  search_query: [query],
  mode: 'fast',
});

// Background analysis: use accurate mode
// accurate = same vector + graph search, plus LLM subquery decomposition + reranking
context = await sdk.conversation.context.fetch({
  conversation_id: conv_id,
  search_query: [query],
  mode: 'accurate',
});

// Real-time chat: use fast mode
// fast = single-pass vector + graph search
let context = await sdk.conversation.context.fetch({
  conversation_id: conv_id,
  search_query: [query],
  mode: 'fast',
});

// Background analysis: use accurate mode
// accurate = same vector + graph search, plus LLM subquery decomposition + reranking
context = await sdk.conversation.context.fetch({
  conversation_id: conv_id,
  search_query: [query],
  mode: 'accurate',
});

Fast mode is used for all latency-sensitive code paths

Batch ingestion for bulk operations

When ingesting multiple documents, use batch_create() instead of multiple create() calls:

from maximem_synap import CreateMemoryRequest

# Good: single batch call
await sdk.memories.batch_create(
    documents=[
        CreateMemoryRequest(document=doc1, document_type="document", user_id="user_1"),
        CreateMemoryRequest(document=doc2, document_type="email", user_id="user_1"),
        CreateMemoryRequest(document=doc3, document_type="pdf", user_id="user_2"),
    ],
    fail_fast=False    # Continue processing even if one document fails
)

# Avoid: N sequential calls
for doc in documents:
    await sdk.memories.create(document=doc, ...)  # Slower, more API calls

Batch ingestion is used for all bulk operations

Context compaction enabled for long conversations

For conversations that span many turns, use context compaction to keep the context within your LLM’s token budget:

result = await sdk.conversation.context.compact(
    conversation_id=conv_id,
    strategy="adaptive",      # Automatically adjusts compression level
    target_tokens=2000
)

compacted = await sdk.conversation.context.get_compacted(
    conversation_id=conv_id,
    format="structured"       # Also valid: "narrative", "bullet_points"
)

const result = await sdk.conversation.context.compact({
  conversation_id: conv_id,
  strategy: 'adaptive',  // Automatically adjusts compression level
  target_tokens: 2000,
});

const compacted = await sdk.conversation.context.get_compacted({
  conversation_id: conv_id,
  format: 'structured',  // Also valid: "narrative", "bullet_points"
});

const result = await sdk.conversation.context.compact({
  conversation_id: conv_id,
  strategy: 'adaptive',  // Automatically adjusts compression level
  target_tokens: 2000,
});

const compacted = await sdk.conversation.context.get_compacted({
  conversation_id: conv_id,
  format: 'structured',  // Also valid: "narrative", "bullet_points"
});

Strategy	Compression	Best For
`conservative`	Highest retention (approximate; varies by content)	Important conversations, legal/compliance
`balanced`	Moderate retention (approximate; varies by content)	General use
`aggressive`	Lowest retention (approximate; varies by content)	Very long conversations, cost optimization
`adaptive`	Variable	Recommended default, adjusts based on content

Context compaction is configured for conversations that may exceed token budgets

Cache is enabled

Verify the cache backend is active and functioning:

stats = sdk.cache.stats()
print(f"Cache entries: {stats['total_entries']}")
print(f"Cache size: {stats['total_bytes']} bytes")
print(f"Backends: {stats['backends']}")

const stats = sdk.cache.stats();
console.log(`Cache entries: ${stats['total_entries']}`);
console.log(`Cache size: ${stats['total_bytes']} bytes`);
console.log(`Backends: ${stats['backends']}`);

const stats = sdk.cache.stats();
console.log(`Cache entries: ${stats['total_entries']}`);
console.log(`Cache size: ${stats['total_bytes']} bytes`);
console.log(`Backends: ${stats['backends']}`);

cache.stats() is synchronous and returns a dict with enabled, client_id, base_path, total_entries, total_bytes, and per-backend stats under backends. If enabled is False or total_entries stays at 0 over time, your cache backend isn’t engaged; check SDKConfig.cache_backend.

Cache backend is enabled and accumulating entries

Operational Readiness

Beyond code and configuration, production readiness requires documented procedures and team alignment.

Team roles assigned appropriately

In the Synap Dashboard, assign roles based on the principle of least privilege:

Role	Capabilities	Assign To
Owner	Full access, billing, delete instance	Engineering lead, CTO
Admin	Config changes, key management, analytics	Senior engineers, DevOps
Developer	Read analytics, view config (no changes)	All developers
Viewer	Read-only Dashboard access	Product managers, support

Team members have appropriate roles (not everyone is Owner)

Credential rotation runbook documented

Document the step-by-step procedure for rotating API keys:

Generate new key in Dashboard
Update secrets manager with new key
Deploy application with updated secret reference
Verify new key is working (check Dashboard for API calls)
Revoke old key after grace period (48 hours)

Credential rotation runbook is documented and accessible to the operations team

Support channel documented

Ensure your team knows how to get help:

Synap Documentation: docs.maximem.ai
Community Discord: discord.gg/synap
GitHub Issues: github.com/maximem-ai/maximem_synap_sdk/issues
Email Support: [email protected] (include correlation_id in all reports)

Support channels are documented and the team knows how to report issues

Quick Summary

Use this condensed checklist for quick pre-deployment reviews:

Area	Item	Status
Security	API key in secrets manager
Security	Webhook signatures verified
Security	API key rotation scheduled
Security	Running processes pick up a rotated key before the old one is revoked
Security	`maximem-synap` ≥ 0.4.1 if any process uses more than one API key
SDK	Log level set to WARNING/ERROR
SDK	Timeouts match SLA
SDK	Cache enabled (sqlite)
Memory	Use-case file matches the production agent
Memory	Retrieval quality validated on representative queries
Memory	Instance status is `active`
Sensitive data	Detection findings reviewed against real traffic
Sensitive data	Policy approved by a named person, not left as a draft
Sensitive data	App tested against any setting that changes what it reads back
Sensitive data	Restricted keys issued to tools that do not need real values
Sensitive data	Activity export produced once, erasure path documented
Errors	Transient vs permanent handling
Errors	Graceful degradation
Errors	correlation_id in logs
Monitoring	Dashboard reviewed regularly
Monitoring	Webhooks for critical events
Monitoring	Latency alerts configured
Performance	Fast mode for user-facing paths
Performance	Batch ingestion for bulk ops
Operations	Roles assigned (least privilege)
Operations	Rotation + rollback runbooks

Next Steps

Migrate from Competitors

Mapping your existing memory system (Mem0, Zep, Letta, SuperMemory) to Synap.

Monitoring and Analytics

Deep dive into Dashboard analytics and monitoring capabilities.

Error Handling

Complete reference for all Synap error types and handling patterns.

Webhooks

Configure webhooks for real-time event notifications.

Guides

Patterns

Cookbook

Authentication and Security

SDK Configuration

Memory Architecture

Sensitive Data

Error Handling

Monitoring

Performance

Operational Readiness

Quick Summary

Next Steps

Migrate from Competitors

Monitoring and Analytics

Error Handling

Webhooks

​Authentication and Security

​SDK Configuration

​Memory Architecture

​Sensitive Data

​Error Handling

​Monitoring

​Performance

​Operational Readiness

​Quick Summary

​Next Steps

Migrate from Competitors

Monitoring and Analytics

Error Handling

Webhooks

Authentication and Security

SDK Configuration

Memory Architecture

Sensitive Data

Error Handling

Monitoring

Performance

Operational Readiness

Quick Summary

Next Steps