Suprflo Python SDK

Official Python client for Suprflo — the memory layer for AI agents.

Installation

pip install suprflo

With an optional framework integration (an "extra"):

pip install "suprflo[langchain]"

Optional integrations (extras)

agno, autogen, crewai, langchain, langgraph, livekit, llamaindex, openai-agents, pipecat, pydantic-ai.

Note: suprflo[pipecat] requires Python ≥ 3.11 — it pulls pipecat-ai >= 1, which dropped 3.9/3.10. On Python 3.9/3.10 the install fails to resolve; use Python 3.11+ for that extra. All other extras support 3.9+.

Quickstart

from suprflo import MemoryClient

client = MemoryClient(api_key="sk-...")  # base_url defaults to https://api.suprflo.com

# Add a memory (a string, a {role, content} dict, or a list of either)
client.add(
    [
        {"role": "user", "content": "I'm vegetarian and allergic to peanuts"},
        {"role": "assistant", "content": "Got it — I'll keep that in mind."},
    ],
    user_id="alice",
)

# Search for relevant memories
results = client.search("what can this person eat?", user_id="alice", top_k=5)
for m in results["results"]:
    print(m["memory"], m.get("score"))

client.close()

MemoryClient also works as a context manager:

with MemoryClient(api_key="sk-...") as client:
    client.add("Prefers window seats", user_id="alice")

Available methods

Non-2xx responses raise suprflo.APIError (with .status_code and .message); SuprfloError is the base exception class.

LangChain integration

from suprflo import MemoryClient
from suprflo.integrations.langchain import (
    SuprfloMemory,
    SuprfloRetriever,
    create_memory_tools,
)

client = MemoryClient(api_key="sk-...")

# 1. Drop-in conversational memory
memory = SuprfloMemory(client=client, user_id="alice", memory_key="history")

# 2. A retriever for RAG chains
retriever = SuprfloRetriever(client=client, user_id="alice", top_k=5)
docs = retriever.invoke("dietary restrictions")

# 3. Agent tools: save_memory + search_memory
tools = create_memory_tools(client, user_id="alice")

The integration imports langchain-core lazily — the base SDK works without it, and importing the integration without LangChain installed raises a clear ImportError telling you to pip install "suprflo[langchain]".

License

MIT