Configure

Python SDK ​

Full API reference for the configure-memory package.

Installation ​

bash
pip install configure-memory

Requirements ​

  • Python 3.8+
  • httpx >= 0.24.0

MemoryClient ​

Main entry point for the SDK. Provides sync API.

python
from configure_memory import MemoryClient

client = MemoryClient(
    api_key: str,
    base_url: str = "https://api.configure.dev",
    timeout: float = 30.0
)

Context Manager ​

python
with MemoryClient("your-api-key") as client:
    # Use client
    pass

Manual Close ​

python
client = MemoryClient("your-api-key")
# ... use client
client.close()

AsyncMemoryClient ​

Async version of the client.

python
import asyncio
from configure_memory import AsyncMemoryClient

async def main():
    async with AsyncMemoryClient("your-api-key") as client:
        await client.auth.send_otp("+14155551234")
        result = await client.auth.verify_otp("+14155551234", "123456")
        profile = await client.memory.get_profile(result.token, result.user_id)

asyncio.run(main())

Authentication (client.auth) ​

send_otp ​

Send OTP to a phone number.

python
client.auth.send_otp(phone: str) -> OtpStartResponse

Parameters:

  • phone - Phone number in E.164 format (e.g., "+14155551234")

Example:

python
client.auth.send_otp("+14155551234")

verify_otp ​

Verify OTP and get auth token.

python
client.auth.verify_otp(phone: str, code: str) -> OtpVerifyResponse

Returns:

  • token - JWT token valid for 30 days
  • user_id - Unique user identifier (UUID)

Example:

python
result = client.auth.verify_otp("+14155551234", "123456")
print(f"Token: {result.token}")
print(f"User ID: {result.user_id}")

get_demo ​

Get a demo token for development.

python
client.auth.get_demo() -> str

Memory (client.memory) ​

get_profile ​

Get the user's Memory Profile.

python
client.memory.get_profile(
    token: str,
    user_id: str,
    path: str = None,
    app_scope: str = None
) -> MemoryProfile

Parameters:

  • token - JWT token from authentication
  • user_id - User ID
  • path - Dot-notation path (e.g., "user", "apps.myapp")
  • app_scope - Filter to data relevant for this app

Example:

python
# Get full profile
profile = client.memory.get_profile(token, user_id)
print(profile.get("user", {}).get("name"))

# Get specific path
user_data = client.memory.get_profile(token, user_id, path="user")

# Get app-scoped data
app_data = client.memory.get_profile(token, user_id, app_scope="my-travel-app")

get_memories ​

Get user's memories.

python
client.memory.get_memories(
    token: str,
    user_id: str = None
) -> MemoriesResponse

remember ​

Save a memory to the user's profile.

python
client.memory.remember(
    token: str,
    user_id: str,
    key: str,
    value: str
) -> RememberResponse

Example:

python
client.memory.remember(token, user_id, "dietary_restrictions", "vegetarian")
client.memory.remember(token, user_id, "preferred_language", "Spanish")

ingest ​

Evaluate a message for memory extraction.

python
from configure_memory import ConversationMessage

client.memory.ingest(
    token: str,
    user_id: str,
    message: ConversationMessage,
    memory_criteria: str
) -> IngestResponse

Example:

python
from configure_memory import ConversationMessage

result = client.memory.ingest(
    token,
    user_id,
    ConversationMessage(role="user", content="I always prefer aisle seats on flights"),
    "Travel preferences, dietary restrictions, scheduling preferences"
)

if result.relevant:
    print(f"Memories extracted: {result.memories_written}")

sync_tools ​

Sync connected tools.

python
client.memory.sync_tools(
    token: str,
    user_id: str,
    tools: List[str] = None
) -> dict

Tools (client.tools) ​

list ​

List available tools and their connection status.

python
client.tools.list(token: str) -> ListToolsResponse

Example:

python
tools = client.tools.list(token)
for tool in tools.tools:
    status = "Connected" if tool.connected else "Not connected"
    print(f"{tool.name}: {status}")

connect ​

Start OAuth flow to connect a tool.

python
client.tools.connect(
    token: str,
    tool: str,
    callback_url: str = None
) -> ConnectToolResponse

Parameters:

  • token - JWT token
  • tool - Tool type: "gmail", "calendar", "drive", "notion"
  • callback_url - URL to redirect after OAuth

Returns:

  • auth_url - OAuth URL to redirect user to
  • connection_request_id - ID to use in confirm endpoint

Example:

python
result = client.tools.connect(token, "gmail", "https://myapp.com/callback")
print(f"Redirect user to: {result.auth_url}")
# Store result.connection_request_id for the confirm step

confirm ​

Confirm tool connection after OAuth callback.

python
client.tools.confirm(
    token: str,
    tool: str,
    connection_request_id: str
) -> ConfirmToolResponse

sync ​

Manually sync a connected tool.

python
client.tools.sync(token: str, tool: str) -> SyncToolResponse

disconnect ​

Disconnect a tool.

python
client.tools.disconnect(token: str, tool: str) -> None

disconnect_all ​

Disconnect all tools.

python
client.tools.disconnect_all(token: str) -> None

search_emails ​

Search user's Gmail.

python
client.tools.search_emails(
    token: str,
    user_id: str,
    query: str,
    max_results: int = 10
) -> SearchEmailsResponse

Example:

python
emails = client.tools.search_emails(token, user_id, "from:boss@company.com")
for email in emails.emails:
    print(f"- {email.subject}")

search_calendar ​

Get user's calendar events.

python
client.tools.search_calendar(
    token: str,
    user_id: str,
    range: str = "week"  # "today" | "tomorrow" | "week" | "month"
) -> SearchCalendarResponse

Example:

python
events = client.tools.search_calendar(token, user_id, "week")
for event in events.events:
    print(f"- {event.summary} at {event.start}")

search_files ​

Search user's Google Drive.

python
client.tools.search_files(
    token: str,
    user_id: str,
    query: str,
    max_results: int = 10
) -> SearchFilesResponse

search_notes ​

Search user's Notion.

python
client.tools.search_notes(
    token: str,
    user_id: str,
    query: str,
    max_results: int = 10
) -> SearchNotesResponse

Streaming (client.streaming) ​

chat_stream ​

Streaming chat with memory-aware AI.

python
from configure_memory import AppContext, StreamCallbacks

client.streaming.chat_stream(
    token: str,
    user_id: str,
    message: str,
    history: List[ConversationMessage],
    app_context: AppContext,
    callbacks: StreamCallbacks,
    options: StreamOptions = None
) -> None

Example:

python
from configure_memory import AppContext, StreamCallbacks

full_response = ""

def on_token(token: str):
    global full_response
    full_response += token
    print(token, end="", flush=True)

def on_done(tools_accessed):
    print("\n--- Done! ---")
    if tools_accessed:
        print(f"Tools used: {tools_accessed}")

client.streaming.chat_stream(
    token,
    user_id,
    "What meetings do I have today?",
    [],  # conversation history
    AppContext(
        app_name="MyAssistant",
        app_description="Personal productivity assistant"
    ),
    StreamCallbacks(
        on_token=on_token,
        on_done=on_done,
        on_error=lambda e: print(f"Error: {e}"),
    ),
)

chat_simple ​

Simple non-streaming chat.

python
client.streaming.chat_simple(
    token: str,
    user_id: str,
    message: str,
    history: List[ConversationMessage],
    app_context: AppContext
) -> dict

personalize ​

Get personalized content.

python
client.streaming.personalize(
    token: str,
    user_id: str,
    app_context: AppContext,
    options: PersonalizeOptions = None
) -> PersonalizeResponse

generate ​

Simple text generation without tool access.

python
client.streaming.generate(
    token: str,
    user_id: str,
    prompt: str,
    app_context: AppContext,
    options: GenerateOptions = None,
    callbacks: StreamCallbacks = None
) -> str

Types ​

AppContext ​

python
from configure_memory import AppContext

context = AppContext(
    app_name="MyApp",
    app_description="A helpful assistant"
)

ConversationMessage ​

python
from configure_memory import ConversationMessage

message = ConversationMessage(
    role="user",  # or "assistant"
    content="Hello!"
)

StreamCallbacks ​

python
from configure_memory import StreamCallbacks

callbacks = StreamCallbacks(
    on_token=lambda t: print(t, end=""),
    on_done=lambda tools: print(f"\nDone! Tools: {tools}"),
    on_memory_updated=lambda memories: print(f"Saved: {memories}"),
    on_error=lambda e: print(f"Error: {e}")
)

Session-Based Flows ​

For guided memory collection (modal/inline flows):

python
from configure_memory import AppContext, StartSessionOptions

# Start a session
session = client.start_session(
    AppContext(
        app_name="TravelBot",
        app_description="AI travel assistant",
        memory_criteria="Travel preferences, frequent destinations, loyalty programs"
    ),
    StartSessionOptions(mode="modal")
)

print(f"Session ID: {session.session_id}")
print(f"User status: {session.user_status}")  # 'new' or 'returning'
print(f"Message: {session.message}")

# Chat within the session
response = client.chat("I prefer window seats and vegetarian meals")
print(f"Response: {response.message}")
print(f"Memories written: {response.memories_written}")

# Check if session is complete
if response.session_complete:
    print("Session complete!")

# End session when done
client.end_session()

Error Handling ​

python
from configure_memory import MemoryClient

client = MemoryClient("your-api-key")

try:
    result = client.auth.verify_otp("+14155551234", "123456")
except Exception as e:
    error_msg = str(e)
    if "invalid_code" in error_msg:
        print("Wrong code, please try again")
    elif "code_expired" in error_msg:
        print("Code expired, request a new one")
    elif "rate_limited" in error_msg:
        print("Too many attempts, please wait")
    else:
        print(f"Error: {error_msg}")

Async Example ​

python
import asyncio
from configure_memory import AsyncMemoryClient, AppContext, StreamCallbacks

async def main():
    async with AsyncMemoryClient("your-api-key") as client:
        # Authenticate
        await client.auth.send_otp("+14155551234")
        result = await client.auth.verify_otp("+14155551234", "123456")
        
        # Get memory profile
        profile = await client.memory.get_profile(result.token, result.user_id)
        print(f"Welcome, {profile.get('user', {}).get('name', 'friend')}")
        
        # Save a memory
        await client.memory.remember(
            result.token,
            result.user_id,
            "favorite_color",
            "blue"
        )
        
        # Stream chat
        async def on_token(token):
            print(token, end="", flush=True)
        
        await client.streaming.chat_stream(
            result.token,
            result.user_id,
            "What do you know about me?",
            [],
            AppContext(app_name="MyApp", app_description="Assistant"),
            StreamCallbacks(on_token=on_token)
        )

asyncio.run(main())

AI Memory Infrastructure

Copyright © 2024-present Configure