Conversations

Conversations provide session-based message tracking with automatic memory extraction. The SDK has two classes:

• ConversationsResource — CRUD for conversation sessions (create, list, get, delete)
• ConversationClient — Operations within a specific conversation (add messages, recall, etc.)

Quick Start

user = client.for_user("user-123")
 
# Create a conversation via the shortcut
conv = user.conversation()
 
# Add messages
conv.add("user", "I just moved to Portland")
conv.add("assistant", "Welcome to Portland! How do you like it?")
 
# Recall with conversation context + long-term memory
result = conv.recall("Where does the user live?")
print(result.context)

ConversationsResource

Accessed via user.conversations. Manages conversation sessions.

create(**kwargs)

Create a new conversation session.

conv = user.conversations.create(
    external_id="session-123",  # Optional client-provided ID
    title="Support Chat",       # Optional title
    metadata={"channel": "web"},
)
print(conv.id)

Returns: Conversation

list(**kwargs)

List conversations for the current user.

conversations = user.conversations.list(limit=10)
for c in conversations.conversations:
    print(f"{c.title}: {c.message_count} messages")

Returns: ConversationList with count and conversations list

get(conversation_id)

Get a conversation by ID.

conv = user.conversations.get("conversation-uuid")

Returns: Conversation

delete(conversation_id)

Soft-delete a conversation.

user.conversations.delete("conversation-uuid")

client(conversation_id)

Get a ConversationClient scoped to a specific conversation.

conv_client = user.conversations.client("conversation-uuid")

Returns: ConversationClient

ConversationClient

Returned by user.conversation() or user.conversations.client(). All operations are scoped to the conversation.

id

Property returning the conversation ID.

print(conv.id)  # "conversation-uuid"

add(role, content, **kwargs)

Add a message to the conversation. Messages are automatically processed for memory extraction.

msg = conv.add("user", "I prefer Python over JavaScript")
print(msg.id)
print(msg.created_at)

Returns: Message

add_batch(messages, **kwargs)

Add multiple messages at once.

result = conv.add_batch([
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"},
])
print(f"Added {result.count} messages")

Returns: MessageList

messages(**kwargs)

Get messages in the conversation (oldest first).

msgs = conv.messages(limit=20)
for m in msgs.messages:
    print(f"[{m.role}]: {m.content}")

Returns: MessageList with count and messages list

recall(query, **kwargs)

Query combining recent conversation messages (short-term) with semantic memory search (long-term).

result = conv.recall("What programming languages does the user know?")
 
# Combined context for LLM prompt
print(result.context)
 
# Recent messages
for msg in result.conversation_context:
    print(f"[{msg.role}]: {msg.content}")
 
# Semantic search results
for r in result.results:
    print(f"{r.content} (score: {r.relevance_score})")

Returns: ConversationRecallResponse with fields:

• conversation_context — List of recent ConversationContext messages
• results — List of QueryResult from semantic search
• context — Combined context string for LLM prompts
• timing — Optional TimingBreakdown

get()

Get the conversation details.

conv_details = conv.get()
print(conv_details.title)
print(conv_details.message_count)

Returns: Conversation

update(**kwargs)

Update conversation title or metadata.

conv.update(title="Renamed Chat", metadata={"priority": "high"})

Returns: Updated Conversation

delete()

Soft-delete the conversation.

conv.delete()