First Integration

pip install maximem-synap openai fastapi uvicorn

poetry add maximem-synap openai fastapi uvicorn

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

from maximem_synap import MaximemSynapSDK, SDKConfig
import os

sdk = MaximemSynapSDK(
    api_key=os.environ["SYNAP_API_KEY"],
    config=SDKConfig(
        cache_backend="sqlite",
        log_level="INFO"
    )
)

async def init():
    """Validate the API key, then open the real-time stream."""
    await sdk.initialize()
    await sdk.instance.listen(
        on_reconnect=lambda attempt: print(f"Synap stream reconnected ({attempt})"),
        on_disconnect=lambda reason: print(f"Synap stream lost: {reason}"),
    )

async def cleanup():
    """Close the stream, then flush pending operations."""
    await sdk.instance.stop_listening()
    await sdk.shutdown()

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

// No SDKConfig wrapper, and no cache_backend: the JS cache is in memory.
export const sdk = new SynapClient();   // reads SYNAP_API_KEY from the environment

export async function init() {
  // Validate the API key, then open the real-time stream.
  await sdk.initialize();
  await sdk.instance.listen({
    on_reconnect: (attempt) => console.log(`Synap stream reconnected (${attempt})`),
    on_disconnect: (reason) => console.log(`Synap stream lost: ${reason}`),
  });
}

export async function cleanup() {
  // Close the stream, then flush pending operations.
  await sdk.instance.stop_listening();
  await sdk.shutdown();
}

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

// No SDKConfig wrapper, and no cache_backend: the JS cache is in memory.
export const sdk = new SynapClient();   // reads SYNAP_API_KEY from the environment

export async function init(): Promise<void> {
  // Validate the API key, then open the real-time stream.
  await sdk.initialize();
  await sdk.instance.listen({
    on_reconnect: (attempt: number) => console.log(`Synap stream reconnected (${attempt})`),
    on_disconnect: (reason: string) => console.log(`Synap stream lost: ${reason}`),
  });
}

export async function cleanup(): Promise<void> {
  // Close the stream, then flush pending operations.
  await sdk.instance.stop_listening();
  await sdk.shutdown();
}

import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from pydantic import BaseModel
from openai import AsyncOpenAI
from startup import sdk, init, cleanup

# --- Lifespan Management ---

@asynccontextmanager
async def lifespan(app):
    """Initialize Synap and open the stream on startup; close both on exit."""
    await init()
    print("Synap SDK initialized and listening. Ready to serve requests.")
    yield
    await cleanup()
    print("Synap SDK shut down cleanly.")

app = FastAPI(
    title="Synap Chatbot",
    description="A memory-enabled chatbot powered by Synap",
    lifespan=lifespan
)
openai_client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

# --- Request/Response Models ---

class ChatRequest(BaseModel):
    message: str
    conversation_id: str
    user_id: str
    customer_id: str | None = None  # B2B instances only; leave unset on B2C

class ChatResponse(BaseModel):
    response: str
    memories_used: int

import express from 'express';
import OpenAI from 'openai';
import { sdk, init, cleanup } from './synap.mjs';

const app = express();
app.use(express.json());

const openaiClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// --- Lifecycle ---
// Express has no lifespan hook: initialize first, close on SIGTERM.
await init();
console.log('Synap SDK initialized and listening. Ready to serve requests.');

const server = app.listen(8000);

process.on('SIGTERM', async () => {
  server.close();
  await cleanup();
  console.log('Synap SDK shut down cleanly.');
  process.exit(0);
});

// Request shape: { message, conversation_id, user_id, customer_id? }
// customer_id is B2B only; leave it unset on B2C.

import express from 'express';
import OpenAI from 'openai';
import { sdk, init, cleanup } from './synap.js';

const app = express();
app.use(express.json());

const openaiClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

interface ChatRequest {
  message: string;
  conversation_id: string;
  user_id: string;
  /** B2B instances only; leave unset on B2C. */
  customer_id?: string;
}

interface ChatResponse {
  response: string;
  memories_used: number;
}

// --- Lifecycle ---
// Express has no lifespan hook: initialize first, close on SIGTERM.
await init();
console.log('Synap SDK initialized and listening. Ready to serve requests.');

const server = app.listen(8000);

process.on('SIGTERM', async () => {
  server.close();
  await cleanup();
  console.log('Synap SDK shut down cleanly.');
  process.exit(0);
});

@app.post("/chat", response_model=ChatResponse)
async def chat(req: ChatRequest):
    # customer_id is required on a B2B instance and not accepted on a
    # B2C one, so forward it only when the caller supplied it.
    scope = {"customer_id": req.customer_id} if req.customer_id else {}

    # -------------------------------------------------------
    # Step 1: Report the user's message (registers the conversation)
    # -------------------------------------------------------
    await sdk.instance.send_message(
        content=req.message,
        role="user",
        event_type="user_message",
        conversation_id=req.conversation_id,
        user_id=req.user_id,
        **scope,
    )

    # -------------------------------------------------------
    # Step 2: Retrieve relevant memories for this conversation
    # -------------------------------------------------------
    context = await sdk.conversation.context.fetch(
        conversation_id=req.conversation_id,
        search_query=[req.message],
        max_results=5,
        types=["facts", "preferences"],
        mode="fast"
    )

    # -------------------------------------------------------
    # Step 3: Build system prompt with memory context
    # -------------------------------------------------------
    memory_lines = []
    for fact in context.facts:
        memory_lines.append(
            f"- {fact.content} (confidence: {fact.confidence:.0%})"
        )
    for pref in context.preferences:
        memory_lines.append(f"- User preference: {pref.content}")

    memory_block = "\n".join(memory_lines) if memory_lines else (
        "No prior context available."
    )

    system_prompt = f"""You are a helpful assistant with memory.

Known information about this user:
{memory_block}

Use this context naturally in your responses. Do not explicitly mention
that you are reading from a memory system, just be naturally informed."""

    # -------------------------------------------------------
    # Step 4: Call the LLM
    # -------------------------------------------------------
    response = await openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": req.message}
        ],
        temperature=0.7,
        max_tokens=1024
    )
    assistant_message = response.choices[0].message.content

    # -------------------------------------------------------
    # Step 5: Report the assistant's reply
    # -------------------------------------------------------
    # This completes the turn in the conversation's history and is what
    # pre-warms anticipation for the NEXT turn. There is no ingestion
    # call: both reported turns become long-term memory when this
    # conversation compacts.
    await sdk.instance.send_message(
        content=assistant_message,
        role="assistant",
        event_type="assistant_message",
        conversation_id=req.conversation_id,
        user_id=req.user_id,
        **scope,
    )

    return ChatResponse(
        response=assistant_message,
        memories_used=len(memory_lines)
    )

app.post('/chat', async (req, res) => {
  const { message, conversation_id, user_id, customer_id } = req.body;

  // customer_id is required on a B2B instance and not accepted on a
  // B2C one, so forward it only when the caller supplied it.
  const scope = customer_id ? { customer_id } : {};

  // -------------------------------------------------------
  // Step 1: Report the user's message (registers the conversation)
  // -------------------------------------------------------
  await sdk.instance.send_message({
    content: message,
    role: 'user',
    event_type: 'user_message',
    conversation_id,
    user_id,
    ...scope,
  });

  // -------------------------------------------------------
  // Step 2: Retrieve relevant memories for this conversation
  // -------------------------------------------------------
  const context = await sdk.conversation.context.fetch({
    conversation_id,
    search_query: [message],
    max_results: 5,
    types: ['facts', 'preferences'],
    mode: 'fast',
  });

  // -------------------------------------------------------
  // Step 3: Build system prompt with memory context
  // -------------------------------------------------------
  // Each collection is optional on the raw response, so default it.
  const memoryLines = [];
  for (const fact of context.facts ?? []) {
    memoryLines.push(
      `- ${fact.content} (confidence: ${((fact.confidence ?? 0) * 100).toFixed(0)}%)`,
    );
  }
  for (const pref of context.preferences ?? []) {
    memoryLines.push(`- User preference: ${pref.content}`);
  }

  const memoryBlock = memoryLines.length
    ? memoryLines.join('\n')
    : 'No prior context available.';

  const systemPrompt = `You are a helpful assistant with memory.

Known information about this user:
${memoryBlock}

Use this context naturally in your responses. Do not explicitly mention
that you are reading from a memory system, just be naturally informed.`;

  // -------------------------------------------------------
  // Step 4: Call the LLM
  // -------------------------------------------------------
  const response = await openaiClient.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: message },
    ],
    temperature: 0.7,
    max_tokens: 1024,
  });
  const assistantMessage = response.choices[0]?.message.content ?? '';

  // -------------------------------------------------------
  // Step 5: Report the assistant's reply
  // -------------------------------------------------------
  // This completes the turn in the conversation's history and is what
  // pre-warms anticipation for the NEXT turn. There is no ingestion
  // call: both reported turns become long-term memory when this
  // conversation compacts.
  await sdk.instance.send_message({
    content: assistantMessage,
    role: 'assistant',
    event_type: 'assistant_message',
    conversation_id,
    user_id,
    ...scope,
  });

  res.json({ response: assistantMessage, memories_used: memoryLines.length });
});

app.post('/chat', async (req, res) => {
  const { message, conversation_id, user_id, customer_id } = req.body as ChatRequest;

  // customer_id is required on a B2B instance and not accepted on a
  // B2C one, so forward it only when the caller supplied it.
  const scope = customer_id ? { customer_id } : {};

  // -------------------------------------------------------
  // Step 1: Report the user's message (registers the conversation)
  // -------------------------------------------------------
  await sdk.instance.send_message({
    content: message,
    role: 'user',
    event_type: 'user_message',
    conversation_id,
    user_id,
    ...scope,
  });

  // -------------------------------------------------------
  // Step 2: Retrieve relevant memories for this conversation
  // -------------------------------------------------------
  const context = await sdk.conversation.context.fetch({
    conversation_id,
    search_query: [message],
    max_results: 5,
    types: ['facts', 'preferences'],
    mode: 'fast',
  });

  // -------------------------------------------------------
  // Step 3: Build system prompt with memory context
  // -------------------------------------------------------
  // Each collection is optional on the raw response, so default it.
  const memoryLines: string[] = [];
  for (const fact of context.facts ?? []) {
    memoryLines.push(
      `- ${fact.content} (confidence: ${((fact.confidence ?? 0) * 100).toFixed(0)}%)`,
    );
  }
  for (const pref of context.preferences ?? []) {
    memoryLines.push(`- User preference: ${pref.content}`);
  }

  const memoryBlock = memoryLines.length
    ? memoryLines.join('\n')
    : 'No prior context available.';

  const systemPrompt = `You are a helpful assistant with memory.

Known information about this user:
${memoryBlock}

Use this context naturally in your responses. Do not explicitly mention
that you are reading from a memory system, just be naturally informed.`;

  // -------------------------------------------------------
  // Step 4: Call the LLM
  // -------------------------------------------------------
  const response = await openaiClient.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: message },
    ],
    temperature: 0.7,
    max_tokens: 1024,
  });
  const assistantMessage = response.choices[0]?.message.content ?? '';

  // -------------------------------------------------------
  // Step 5: Report the assistant's reply
  // -------------------------------------------------------
  // This completes the turn in the conversation's history and is what
  // pre-warms anticipation for the NEXT turn. There is no ingestion
  // call: both reported turns become long-term memory when this
  // conversation compacts.
  await sdk.instance.send_message({
    content: assistantMessage,
    role: 'assistant',
    event_type: 'assistant_message',
    conversation_id,
    user_id,
    ...scope,
  });

  res.json({ response: assistantMessage, memories_used: memoryLines.length });
});

@app.get("/health")
async def health():
    try:
        stats = sdk.cache.stats()
        return {
            "status": "healthy",
            "synap_connected": True,
            "cache_entries": stats["total_entries"]
        }
    except Exception as e:
        return {
            "status": "degraded",
            "synap_connected": False,
            "error": str(e)
        }

app.get('/health', (req, res) => {
  try {
    // The JS cache reports { bundles, items }; Python's SQLite backend
    // reports { entry_count, total_bytes, ... }. Different shapes.
    const stats = sdk.cache.stats();
    res.json({
      status: 'healthy',
      synap_connected: true,
      cache_bundles: stats.bundles,
      cache_items: stats.items,
    });
  } catch (e) {
    res.json({
      status: 'degraded',
      synap_connected: false,
      error: String(e),
    });
  }
});

app.get('/health', (req, res) => {
  try {
    // The JS cache reports { bundles, items }; Python's SQLite backend
    // reports { entry_count, total_bytes, ... }. Different shapes.
    const stats = sdk.cache.stats();
    res.json({
      status: 'healthy',
      synap_connected: true,
      cache_bundles: stats.bundles,
      cache_items: stats.items,
    });
  } catch (e) {
    res.json({
      status: 'degraded',
      synap_connected: false,
      error: String(e),
    });
  }
});

# Load environment variables
export $(cat .env | xargs)

# Start the FastAPI server
uvicorn main:app --reload --port 8000

# Node 20.6+ reads the file directly; no dotenv needed
node --env-file=.env server.mjs

npx tsx --env-file=.env server.ts