Skip to main content

​
Install

pip install synap-livekit-agents

​
What’s included

ExportPurpose
preload_synap_contextInjects long-term memory into a ChatContext before the session starts
attach_synap_recordingRecords every committed turn back to Synap during a session
synap_search_toolLLM-callable function tool for on-demand memory search
synap_store_toolLLM-callable function tool for on-demand memory storage

​
Quick start

from livekit.agents import Agent, AgentSession, RoomInputOptions
from livekit.agents.llm import ChatContext
from synap_livekit_agents import (
    preload_synap_context,
    attach_synap_recording,
    synap_search_tool,
    synap_store_tool,
)

async def entrypoint(ctx: JobContext):
    await ctx.connect()

    # Preload long-term memory into the chat context
    chat_ctx = ChatContext()
    await preload_synap_context(
        chat_ctx=chat_ctx,
        sdk=sdk,
        user_id="alice",
        customer_id="acme",
        max_results=8,
    )

    agent = Agent(
        instructions="You are a voice assistant with long-term memory.",
        chat_ctx=chat_ctx,
        tools=[
            synap_search_tool(sdk=sdk, user_id="alice"),
            synap_store_tool(sdk=sdk, user_id="alice"),
        ],
    )

    session = AgentSession(...)

    # Attach recording — every committed turn is sent to Synap
    conversation_id = attach_synap_recording(
        session=session,
        sdk=sdk,
        user_id="alice",
        customer_id="acme",
    )

    await session.start(agent=agent, room=ctx.room)

​
preload_synap_context

Loads the user’s long-term memories as system messages in the ChatContext before the session starts. This gives the LLM awareness of the user’s history from the first turn — no tool call needed. 
await preload_synap_context(
    chat_ctx=chat_ctx,
    sdk=sdk,
    user_id="alice",
    customer_id="acme",    # optional
    max_results=8,
    mode="fast",           # "fast" or "accurate"
)
Failures degrade gracefully — the session starts with empty context rather than raising.

​
attach_synap_recording

Subscribes to the AgentSession’s turn commit events and ingests each turn into Synap asynchronously. Returns the conversation_id for the session. 
conversation_id = attach_synap_recording(
    session=session,
    sdk=sdk,
    user_id="alice",
    customer_id="acme",
    conversation_id="call-001",   # optional; auto-generated if omitted
)

​
Function tools

Give the agent explicit memory tools for mid-conversation lookup or storage: 
tools = [
    synap_search_tool(sdk=sdk, user_id="alice", max_results=5),
    synap_store_tool(sdk=sdk, user_id="alice"),
]
The tools are @llm.ai_callable decorated functions that the LiveKit LLM bridge will expose to the model as function calls.

​
Next steps

Pipecat

Frame processors for Pipecat voice pipelines.

Claude Agent SDK

Hooks and MCP server for the Claude Agent SDK.