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.

​
Prerequisites

1

Install the SDK

Install the Synap SDK from PyPI:
pip install maximem-synap
gRPC streaming is enabled by default — no extra install needed.
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
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
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 an API Key

  1. In the Dashboard, go to your newly created instance
  2. Open the API Keys section on the instance detail page
  3. Click Generate API Key
  4. Give it a label (e.g., “development”) and click Generate
  5. Copy the key immediately — it starts with synap_
The API key is displayed only once. Copy it now and store it securely. If you lose it, revoke it from the dashboard and generate a new one.
5

Initialize the SDK

Set your API key as an environment variable:
export SYNAP_API_KEY=synap_your_key_here
Create a new Python file:
main.py
import asyncio
from maximem_synap import MaximemSynapSDK

async def main():
    sdk = MaximemSynapSDK()
    await sdk.initialize()

    print("Synap SDK initialized successfully!")

    # Your code goes here...

    await sdk.shutdown()

if __name__ == "__main__":
    asyncio.run(main())
That’s it. The SDK reads SYNAP_API_KEY from your environment automatically.
You can also pass the API key directly if you prefer:
sdk = MaximemSynapSDK(api_key="synap_your_key_here")
Run the script:
python main.py
You should see Synap SDK initialized successfully!
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 episodes
print(f"\nRetrieved {len(context.episodes)} episodes:")
for episode in context.episodes:
    print(f"  - {episode.summary}")
Example output:
Retrieved 1 facts:
  - User is located in San Francisco (confidence: 0.92)

Retrieved 1 preferences:
  - User loves warm weather

Retrieved 1 episodes:
  - User is planning a trip to Japan next month
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():
    # Reads SYNAP_API_KEY from environment; instance ID resolved server-side
    sdk = MaximemSynapSDK()
    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.