The Short-Term Memory API

Adding messages and managing sessions

A session corresponds to one conversation. You choose the session ID — any string works. The library creates the Conversation node automatically the first time you call add_message() with that ID:

async with MemoryClient(settings) as memory:
    # Add messages — the session is created automatically on first use
    await memory.short_term.add_message(
        session_id="user_123",
        role="user",
        content="Review Jessica Norris account for credit limit increase"
    )
    await memory.short_term.add_message(
        session_id="user_123",
        role="assistant",
        content="I will retrieve Jessica's full profile now."
    )

    # Remove a session and all its messages when done
    await memory.short_term.clear_session("user_123")

Calling add_message() with a new session_id creates the Conversation node automatically. clear_session() removes the session and all its linked Message nodes when the conversation ends.

Retrieving and searching messages

To retrieve a conversation and its messages, or search message history by semantic similarity:

async with MemoryClient(settings) as memory:
    # Retrieve the full conversation and its messages
    conversation = await memory.short_term.get_conversation("user_123")
    for msg in conversation.messages:
        print(msg.role, msg.content)

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

get_conversation() returns the Conversation object with all linked messages in order. search_messages() uses vector similarity on the embedding property of each Message node.

Understanding the message traversal query

To understand the linked-list structure the library builds, 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 and get_conversation_summary() to generate a summary of what was discussed:

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

    # Auto-generate a plain-English summary of the conversation
    summary = await memory.short_term.get_conversation_summary("user_123")

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

All methods are on memory.short_term. Sessions are created automatically by add_message().