Skip to main content

​
Prerequisites

1

Install the SDK

Install the Synap SDK from PyPI:
pip install maximem-synap
Verify the installation:
python -c "import maximem_synap; print(maximem_synap.__version__)"
2

Set Up Your Client

A Client is your organization’s top-level account in Synap. Every instance belongs to a Client. You have two options:Create a new Client
  1. Log in to the Synap Dashboard
  2. Click Create Client, enter your organization name, and confirm
  3. Copy the Client ID — it will look like cli_a3f8b1c2d4e5f678
Join an existing ClientIf your team already has a Synap account, ask your administrator to invite you. Once added, log in and you’ll see the shared Client and its instances in your Dashboard.
Skipping this step is not possible — every instance must belong to a Client. If you are unsure whether your organization already has one, check with your team before creating a new Client.
3

Create an Instance

An instance is an isolated memory environment for your agent. Each instance has its own storage, configuration, and scope hierarchy.
  1. In the Dashboard, navigate to Instances in the sidebar
  2. Click Create Instance
  3. Fill in the instance form:
    • Name (required): A human-readable label, e.g. "My First Agent"
    • Agent Type (required): Choose the type that best describes your agent (e.g. B2B Customer Support, B2C Companion, Workflow Agent)
    • Description (optional): A short description of what this instance is for
    • Use-Case Markdown (optional but recommended): Upload a .md file describing your agent’s use case — see below
  4. Copy the Instance ID — it will look like inst_a1b2c3d4e5f67890
Creating a new instance in the Synap Dashboard

​
Use-Case Markdown

The Use-Case Markdown file tells Synap what your agent does, who it serves, and what it should remember. Synap uses it to generate an optimized Memory Architecture Configuration (MACA) for your instance — so the more detail you provide, the better your memory extraction and retrieval will be from day one.To create your use-case file:
  1. Click Download Template in the Create Instance form, or copy the structure below
  2. Fill in at minimum the three required sections
  3. Upload the file (.md, .markdown, or .txt — max 512 KB) in the form before clicking Create
# Use-Case Description

## Agent Objective (required)
What does your agent do? Describe its core purpose and the problem it solves.

## Target Users (required)
Who interacts with this agent? Describe their roles, technical level, and interaction patterns.

## Task Examples (required)
Provide 3–5 representative examples of tasks the agent handles.

## Behavioral Guidelines (optional)
What should the agent always do? What should it never do?

## Role Descriptions (optional)
Clarify who Client, Customer, and User are in your setup.

## Compliance & Data Sensitivity (optional)
List regulatory frameworks, data handling requirements, or privacy constraints.

## Memory Priorities (optional)
Which types of information matter most? What should the agent prioritize remembering?

## Additional Context (optional)
Business context, integrations, technical constraints, deployment environment, etc.
You can upload or update the use-case file at any time after instance creation via Instance Settings in the Dashboard. Synap will re-evaluate and update the MACA when a new file is submitted.
4

Generate a Bootstrap Key

Bootstrap keys are single-use credentials that authenticate your SDK’s first connection to Synap Cloud. After the initial bootstrap, the SDK automatically manages credential rotation.
  1. In the Dashboard, go to your newly created instance
  2. Open the Credentials section on the instance detail page
  3. Click Generate Bootstrap Key
  4. Copy the key immediately
The bootstrap key is displayed only once. Store it securely — in a secrets manager, environment variable, or encrypted configuration file. If you lose it, you’ll need to generate a new one.
5

Initialize the SDK

Create a new Python file and initialize the SDK with your instance ID and bootstrap key:
main.py
import asyncio
from maximem_synap import MaximemSynapSDK

async def main():
    # Initialize the SDK with your instance credentials
    sdk = MaximemSynapSDK(
        instance_id="inst_a1b2c3d4e5f67890",
        bootstrap_token="your-bootstrap-key"
    )
    await sdk.initialize()

    print("Synap SDK initialized successfully!")

    # Your code goes here...

    # Always shut down cleanly
    await sdk.shutdown()

if __name__ == "__main__":
    asyncio.run(main())
For production applications, use environment variables instead of hardcoded credentials:
import os

sdk = MaximemSynapSDK(
    instance_id=os.environ["SYNAP_INSTANCE_ID"],
    bootstrap_token=os.environ["SYNAP_BOOTSTRAP_TOKEN"]
)
Run the script to verify the connection:
python main.py
You should see Synap SDK initialized successfully! printed to the console. The SDK has now bootstrapped with Synap Cloud, obtained its initial credentials, and is ready to ingest and retrieve memories.
6

Ingest Your First Memory

Now let’s send a conversation to Synap. The ingestion pipeline will automatically extract structured knowledge — facts, preferences, entities, and more.
# Ingest a sample conversation
response = await sdk.memories.create(
    document=(
        "User: What's the weather like?\n"
        "Assistant: It's sunny and 72°F in San Francisco today.\n"
        "User: Nice! I love warm weather. I'm planning a trip to Japan next month.\n"
        "Assistant: That sounds exciting! Japan in spring is beautiful."
    ),
    document_type="ai-chat-conversation",
    user_id="user_123"
)

print(f"Ingestion ID: {response.ingestion_id}")
print(f"Status: {response.status}")
The SDK returns immediately with an ingestion ID. The pipeline processes the content asynchronously, extracting:
  • Fact: User is located in San Francisco
  • Preference: User loves warm weather
  • Temporal event: User is planning a trip to Japan next month
  • Entities: San Francisco, Japan (resolved and linked in the knowledge graph)
Ingestion is asynchronous by design. The memories.create() call returns as soon as the content is accepted by Synap Cloud. Processing typically completes within a few seconds, but complex documents may take longer.
7

Retrieve Context

Once memories are ingested and processed, you can retrieve relevant context for any conversation. Synap searches across both vector and graph storage, ranks results by relevance, and respects scope boundaries.
# Retrieve relevant context for a new conversation
context = await sdk.conversation.context.fetch(
    conversation_id="conv_456",
    search_query=["weather preferences", "travel plans"],
    max_results=5
)

# Print retrieved facts
print(f"Retrieved {len(context.facts)} facts:")
for fact in context.facts:
    print(f"  - {fact.content} (confidence: {fact.confidence})")

# Print retrieved preferences
print(f"\nRetrieved {len(context.preferences)} preferences:")
for pref in context.preferences:
    print(f"  - {pref.content}")

# Print retrieved entities
print(f"\nRetrieved {len(context.entities)} entities:")
for entity in context.entities:
    print(f"  - {entity.canonical_name} ({entity.type})")
Example output:
Retrieved 1 facts:
  - User is located in San Francisco (confidence: 0.92)

Retrieved 1 preferences:
  - User loves warm weather

Retrieved 2 entities:
  - San Francisco (location)
  - Japan (location)
You can now inject this context into your LLM’s system prompt or conversation history to create a personalized, context-aware experience.
8

Clean Up

Always shut down the SDK cleanly to flush any pending operations and release resources:
await sdk.shutdown()
The complete script looks like this:
main.py
import asyncio
from maximem_synap import MaximemSynapSDK

async def main():
    sdk = MaximemSynapSDK(
        instance_id="inst_a1b2c3d4e5f67890",
        bootstrap_token="your-bootstrap-key"
    )
    await sdk.initialize()

    # Ingest a conversation
    response = await sdk.memories.create(
        document=(
            "User: What's the weather like?\n"
            "Assistant: It's sunny and 72°F in San Francisco today.\n"
            "User: Nice! I love warm weather. I'm planning a trip to Japan next month.\n"
            "Assistant: That sounds exciting! Japan in spring is beautiful."
        ),
        document_type="ai-chat-conversation",
        user_id="user_123"
    )
    print(f"Ingested: {response.ingestion_id}")

    # Wait briefly for processing (in production, use webhooks instead)
    await asyncio.sleep(3)

    # Retrieve context
    context = await sdk.conversation.context.fetch(
        conversation_id="conv_456",
        search_query=["weather preferences"],
        max_results=5
    )
    for fact in context.facts:
        print(f"  {fact.content} (confidence: {fact.confidence})")

    await sdk.shutdown()

if __name__ == "__main__":
    asyncio.run(main())

​
What’s next?

You’ve successfully ingested your first memory and retrieved context. Here’s where to go from here:

Core Concepts

Understand the full Synap architecture — scopes, memory types, entity resolution, and the ingestion pipeline.

SDK Configuration

Configure the SDK for your production environment — timeouts, retries, logging, and credential management.

Memory Architecture

Learn how to configure what gets extracted, how it’s stored, and how retrieval ranking works.

Production Checklist

Security, performance, monitoring, and reliability best practices before going live.