AGENTS.md

Overview

This package adds persistent memory to Pipecat voice AI pipelines using Supermemory.

Tech Stack: Python >=3.10, Pipecat, Supermemory SDK

Commands

bash

pip install supermemory-pipecat

Integration Pattern

Place SupermemoryPipecatService between context aggregator and LLM in the pipeline:

python

from supermemory_pipecat import SupermemoryPipecatService

memory = SupermemoryPipecatService(
    user_id="user-123",       # Required: identifies the user
    session_id="session-456", # Optional: groups conversations
)

pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    memory,                    # <- Memory service here
    llm,
    tts,
    transport.output(),
    context_aggregator.assistant(),
])

Configuration

python

memory = SupermemoryPipecatService(
    api_key="...",             # Or use SUPERMEMORY_API_KEY env var
    user_id="user-123",
    session_id="session-456",
    params=SupermemoryPipecatService.InputParams(
        search_limit=10,       # Max memories to retrieve
        search_threshold=0.1,  # Similarity threshold 0.0-1.0
        mode="full",           # "profile" | "query" | "full"
        system_prompt="Based on previous conversations:\n\n",
    ),
)

Memory Modes

Mode	Retrieves	Use When
`"profile"`	User profile only	Personalization without search
`"query"`	Search results only	Finding relevant past context
`"full"`	Profile + search	Complete memory (default)

Environment Variables

SUPERMEMORY_API_KEY - Supermemory API key
OPENAI_API_KEY - For OpenAI services (STT/LLM/TTS)

Boundaries

Always place memory service after context_aggregator.user() and before llm
Always provide user_id - it's required
Never hardcode API keys in code - use environment variables