Quickstart

pip install maximem-synap

poetry add maximem-synap

uv add maximem-synap
# pip-compatible (existing venv): uv pip install maximem-synap

npm install @maximem/synap-js-sdk

pnpm add @maximem/synap-js-sdk

yarn add @maximem/synap-js-sdk

python -c "import maximem_synap; print(maximem_synap.__version__)"

node -e "import('@maximem/synap-js-sdk').then(m => console.log(m.SDK_VERSION))"

export SYNAP_API_KEY="synap_your_key_here"
export SYNAP_INSTANCE_ID="inst_your_instance_id"

$env:SYNAP_API_KEY = "synap_your_key_here"
$env:SYNAP_INSTANCE_ID = "inst_your_instance_id"

[System.Environment]::SetEnvironmentVariable("SYNAP_API_KEY", "synap_your_key_here", "User")
[System.Environment]::SetEnvironmentVariable("SYNAP_INSTANCE_ID", "inst_your_instance_id", "User")

# Python: load with python-dotenv. Node 20.6+: `node --env-file=.env`
SYNAP_API_KEY=synap_your_key_here
SYNAP_INSTANCE_ID=inst_your_instance_id

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())

import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient();
await sdk.initialize();

console.log('Synap SDK initialized successfully!');

// Your code goes here...

await sdk.shutdown();

import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient();
await sdk.initialize();

console.log('Synap SDK initialized successfully!');

// Your code goes here...

await sdk.shutdown();

python main.py

py main.py

node main.mjs

npx tsx main.ts

# Ingest a sample conversation (B2C: user_id only)
response = await sdk.memories.create(
    document=(
        "User: I'm in San Francisco, 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}")

// Ingest a sample conversation (B2C: user_id only)
const response = await sdk.memories.create({
  document: [
    "User: I'm in San Francisco, what's the weather like?",
    "Assistant: It's sunny and 72°F in San Francisco today.",
    "User: Nice! I love warm weather. I'm planning a trip to Japan next month.",
    'Assistant: That sounds exciting! Japan in spring is beautiful.',
  ].join('\n'),
  document_type: 'ai-chat-conversation',
  user_id: 'user_123',
});

console.log(`Ingestion ID: ${response.ingestion_id}`);
console.log(`Status: ${response.status}`);

// Ingest a sample conversation (B2C: user_id only)
const response = await sdk.memories.create({
  document: [
    "User: I'm in San Francisco, what's the weather like?",
    "Assistant: It's sunny and 72°F in San Francisco today.",
    "User: Nice! I love warm weather. I'm planning a trip to Japan next month.",
    'Assistant: That sounds exciting! Japan in spring is beautiful.',
  ].join('\n'),
  document_type: 'ai-chat-conversation',
  user_id: 'user_123',
});

console.log(`Ingestion ID: ${response.ingestion_id}`);
console.log(`Status: ${response.status}`);

# Retrieve relevant context at user scope (matches the ingestion above).
# B2C: user_id only. Passing customer_id here returns HTTP 400.
context = await sdk.user.context.fetch(
    user_id="user_123",
    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}")

// Retrieve relevant context at user scope (matches the ingestion above).
// B2C: user_id only. Passing customer_id here returns HTTP 400.
const context = await sdk.user.context.fetch({
  user_id: 'user_123',
  search_query: ['weather preferences', 'travel plans'],
  max_results: 5,
});

// The namespaced surface returns raw snake_case, and each collection is
// optional, so default it before reading .length.
const facts = context.facts ?? [];
const preferences = context.preferences ?? [];
const episodes = context.episodes ?? [];

console.log(`Retrieved ${facts.length} facts:`);
for (const fact of facts) {
  console.log(`  - ${fact.content} (confidence: ${fact.confidence})`);
}

console.log(`\nRetrieved ${preferences.length} preferences:`);
for (const pref of preferences) {
  console.log(`  - ${pref.content}`);
}

console.log(`\nRetrieved ${episodes.length} episodes:`);
for (const episode of episodes) {
  console.log(`  - ${episode.summary}`);
}

// Retrieve relevant context at user scope (matches the ingestion above).
// B2C: user_id only. Passing customer_id here returns HTTP 400.
const context = await sdk.user.context.fetch({
  user_id: 'user_123',
  search_query: ['weather preferences', 'travel plans'],
  max_results: 5,
});

// The namespaced surface returns raw snake_case, and each collection is
// optional, so default it before reading .length.
const facts = context.facts ?? [];
const preferences = context.preferences ?? [];
const episodes = context.episodes ?? [];

console.log(`Retrieved ${facts.length} facts:`);
for (const fact of facts) {
  console.log(`  - ${fact.content} (confidence: ${fact.confidence})`);
}

console.log(`\nRetrieved ${preferences.length} preferences:`);
for (const pref of preferences) {
  console.log(`  - ${pref.content}`);
}

console.log(`\nRetrieved ${episodes.length} episodes:`);
for (const episode of episodes) {
  console.log(`  - ${episode.summary}`);
}

await sdk.shutdown()

await sdk.shutdown();

await sdk.shutdown();

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 (B2C: user_id only)
    response = await sdk.memories.create(
        document=(
            "User: I'm in San Francisco, 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}")

    # Block until ingestion completes, instead of guessing with a fixed sleep.
    await sdk.memories.wait_for_completion(response.ingestion_id)

    # Retrieve context at the same scope used for ingestion (user).
    # B2C: user_id only. customer_id is not accepted on this instance.
    # (On a B2B instance, pass both user_id and customer_id here.)
    context = await sdk.user.context.fetch(
        user_id="user_123",
        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())

import { SynapClient } from '@maximem/synap-js-sdk';

// Reads SYNAP_API_KEY from environment; instance ID resolved server-side
const sdk = new SynapClient();
await sdk.initialize();

// Ingest a conversation (B2C: user_id only)
const response = await sdk.memories.create({
  document: [
    "User: I'm in San Francisco, what's the weather like?",
    "Assistant: It's sunny and 72°F in San Francisco today.",
    "User: Nice! I love warm weather. I'm planning a trip to Japan next month.",
    'Assistant: That sounds exciting! Japan in spring is beautiful.',
  ].join('\n'),
  document_type: 'ai-chat-conversation',
  user_id: 'user_123',
});
console.log(`Ingested: ${response.ingestion_id}`);

// Block until ingestion completes, instead of guessing with a fixed sleep.
await sdk.memories.wait_for_completion(response.ingestion_id);

// Retrieve context at the same scope used for ingestion (user).
// B2C: user_id only. customer_id is not accepted on this instance.
// (On a B2B instance, pass both user_id and customer_id here.)
const context = await sdk.user.context.fetch({
  user_id: 'user_123',
  search_query: ['weather preferences'],
  max_results: 5,
});
for (const fact of context.facts ?? []) {
  console.log(`  ${fact.content} (confidence: ${fact.confidence})`);
}

await sdk.shutdown();

import { SynapClient } from '@maximem/synap-js-sdk';

// Reads SYNAP_API_KEY from environment; instance ID resolved server-side
const sdk = new SynapClient();
await sdk.initialize();

// Ingest a conversation (B2C: user_id only)
const response = await sdk.memories.create({
  document: [
    "User: I'm in San Francisco, what's the weather like?",
    "Assistant: It's sunny and 72°F in San Francisco today.",
    "User: Nice! I love warm weather. I'm planning a trip to Japan next month.",
    'Assistant: That sounds exciting! Japan in spring is beautiful.',
  ].join('\n'),
  document_type: 'ai-chat-conversation',
  user_id: 'user_123',
});
console.log(`Ingested: ${response.ingestion_id}`);

// Block until ingestion completes, instead of guessing with a fixed sleep.
await sdk.memories.wait_for_completion(response.ingestion_id);

// Retrieve context at the same scope used for ingestion (user).
// B2C: user_id only. customer_id is not accepted on this instance.
// (On a B2B instance, pass both user_id and customer_id here.)
const context = await sdk.user.context.fetch({
  user_id: 'user_123',
  search_query: ['weather preferences'],
  max_results: 5,
});
for (const fact of context.facts ?? []) {
  console.log(`  ${fact.content} (confidence: ${fact.confidence})`);
}

await sdk.shutdown();

import uuid
from maximem_synap import MaximemSynapSDK
from openai import AsyncOpenAI

sdk = MaximemSynapSDK()
openai = AsyncOpenAI()

# One UUID per chat thread, reused across its turns.
conversation_id = str(uuid.uuid4())

async def turn(user_id: str, conversation_id: str, user_message: str) -> str:
    # 1. Record the user's message. record_message is what REGISTERS the
    #    conversation, creating the row that conversation.context.fetch needs
    #    to resolve scope on subsequent turns. (Passing conversation_id only
    #    as memories.create metadata would NOT register it; metadata is
    #    stored but not indexed for scope resolution.)
    await sdk.conversation.record_message(
        conversation_id=conversation_id,
        role="user",
        content=user_message,
        user_id=user_id,
    )

    # 2. Retrieve relevant memory context for this conversation
    ctx = await sdk.conversation.context.fetch(
        conversation_id=conversation_id,
        user_id=user_id,
        search_query=[user_message],
    )
    memories = "\n".join(f"- {f.content}" for f in ctx.facts[:5])

    # 3. Generate with the LLM, injecting memories into the system prompt
    completion = await openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"Known facts about the user:\n{memories}"},
            {"role": "user", "content": user_message},
        ],
    )
    reply = completion.choices[0].message.content

    # 4. Record the assistant reply, then persist the turn for long-term retrieval
    await sdk.conversation.record_message(
        conversation_id=conversation_id,
        role="assistant",
        content=reply,
        user_id=user_id,
    )
    await sdk.memories.create(
        document=f"User: {user_message}\nAssistant: {reply}",
        document_type="ai-chat-conversation",
        user_id=user_id,
        metadata={"conversation_id": conversation_id},
    )
    return reply

import { randomUUID } from 'node:crypto';
import { SynapClient } from '@maximem/synap-js-sdk';
import OpenAI from 'openai';

const sdk = new SynapClient();
const openai = new OpenAI();

// One UUID per chat thread, reused across its turns.
const conversationId = randomUUID();

async function turn(userId, conversationId, userMessage) {
  // 1. Record the user's message. record_message is what REGISTERS the
  //    conversation, creating the row that conversation.context.fetch needs
  //    to resolve scope on subsequent turns. (Passing conversation_id only
  //    as memories.create metadata would NOT register it; metadata is
  //    stored but not indexed for scope resolution.)
  await sdk.conversation.record_message({
    conversation_id: conversationId,
    role: 'user',
    content: userMessage,
    user_id: userId,
  });

  // 2. Retrieve relevant memory context for this conversation
  const ctx = await sdk.conversation.context.fetch({
    conversation_id: conversationId,
    user_id: userId,
    search_query: [userMessage],
  });
  const memories = (ctx.facts ?? [])
    .slice(0, 5)
    .map((f) => `- ${f.content}`)
    .join('\n');

  // 3. Generate with the LLM, injecting memories into the system prompt
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: `Known facts about the user:\n${memories}` },
      { role: 'user', content: userMessage },
    ],
  });
  const reply = completion.choices[0]?.message.content ?? '';

  // 4. Record the assistant reply, then persist the turn for long-term retrieval
  await sdk.conversation.record_message({
    conversation_id: conversationId,
    role: 'assistant',
    content: reply,
    user_id: userId,
  });
  await sdk.memories.create({
    document: `User: ${userMessage}\nAssistant: ${reply}`,
    document_type: 'ai-chat-conversation',
    user_id: userId,
    metadata: { conversation_id: conversationId },
  });
  return reply;
}

import { randomUUID } from 'node:crypto';
import { SynapClient } from '@maximem/synap-js-sdk';
import OpenAI from 'openai';

const sdk = new SynapClient();
const openai = new OpenAI();

// One UUID per chat thread, reused across its turns.
const conversationId = randomUUID();

async function turn(
  userId: string,
  conversationId: string,
  userMessage: string,
): Promise<string> {
  // 1. Record the user's message. record_message is what REGISTERS the
  //    conversation, creating the row that conversation.context.fetch needs
  //    to resolve scope on subsequent turns. (Passing conversation_id only
  //    as memories.create metadata would NOT register it; metadata is
  //    stored but not indexed for scope resolution.)
  await sdk.conversation.record_message({
    conversation_id: conversationId,
    role: 'user',
    content: userMessage,
    user_id: userId,
  });

  // 2. Retrieve relevant memory context for this conversation
  const ctx = await sdk.conversation.context.fetch({
    conversation_id: conversationId,
    user_id: userId,
    search_query: [userMessage],
  });
  const memories = (ctx.facts ?? [])
    .slice(0, 5)
    .map((f) => `- ${f.content}`)
    .join('\n');

  // 3. Generate with the LLM, injecting memories into the system prompt
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: `Known facts about the user:\n${memories}` },
      { role: 'user', content: userMessage },
    ],
  });
  const reply = completion.choices[0]?.message.content ?? '';

  // 4. Record the assistant reply, then persist the turn for long-term retrieval
  await sdk.conversation.record_message({
    conversation_id: conversationId,
    role: 'assistant',
    content: reply,
    user_id: userId,
  });
  await sdk.memories.create({
    document: `User: ${userMessage}\nAssistant: ${reply}`,
    document_type: 'ai-chat-conversation',
    user_id: userId,
    metadata: { conversation_id: conversationId },
  });
  return reply;
}