Quickstart

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

# 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}")

# Retrieve relevant context at user scope (matches the ingestion above).
# B2C: customer_id is auto-resolved from user_id, so omit it.
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}")

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

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