The Short-Term Memory API

Creating and managing sessions

A session corresponds to one conversation. Create one before adding messages:

async with MemoryClient(settings) as memory:
    # One session per user / conversation
    session = await memory.add_session("user_123")

    # Add messages as the conversation progresses
    await memory.add_message(
        session.id,
        role="user",
        content="Review Jessica Norris account for credit limit increase"
    )
    await memory.add_message(
        session.id,
        role="assistant",
        content="I will retrieve Jessica's full profile now."
    )

    # Remove a session and all its messages when done
    await memory.delete_session(session.id)

This creates a session for user_123, stores two messages in sequence, then removes the session and all its linked message nodes when the conversation ends.

Retrieving and searching messages

To retrieve recent messages for context injection, or search message history by semantic similarity:

async with MemoryClient(settings) as memory:
    # Get the N most recent messages (for context injection)
    recent = await memory.get_recent_messages(session.id, limit=5)

    # Semantic search over message history
    results = await memory.search_messages(
        query="credit limit increase",
        session_id=session.id,
        limit=10
    )

get_recent_messages() returns messages in reverse chronological order — the most recent first. search_messages() uses vector similarity on the embedding property of each Message node.

Understanding the Cypher behind get_recent_messages

To understand what the library does, write the equivalent query manually:

MATCH (c:Conversation {id: $session_id})-[:FIRST_MESSAGE]->(m:Message)
  CALL {
    WITH m
    MATCH (m)-[:NEXT_MESSAGE*0..]->(msg:Message)
    RETURN msg ORDER BY msg.timestamp DESC LIMIT 5
  }
RETURN msg.role, msg.content, msg.timestamp

Following NEXT_MESSAGE relationships traverses the linked list in order. This traversal is structurally impossible in a flat table without a sort column — and the pattern becomes more capable when combined with entity lookups in Module 3.

Listing sessions and retrieving summaries

Use list_sessions() to retrieve all sessions for a user and get_conversation_summary() to generate a summary of what was discussed:

async with MemoryClient(settings) as memory:
    # List all sessions for this user
    sessions = await memory.list_sessions()

    # Auto-generate a plain-English summary of the conversation
    summary = await memory.get_conversation_summary(session.id)

list_sessions() returns all Conversation nodes, useful for building session history views in a UI. get_conversation_summary() uses the stored messages to produce a concise summary of the conversation — useful for creating long-term memory from short-term context.

Short-term memory API reference