PythonAvailable

Python SDK

Official Python SDK with full type hints, async support, and comprehensive error handling.

Installation

# Install using pip
pip install memory-scope

# Or with pipenv
pipenv install memory-scope

# Or with poetry
poetry add memory-scope

Requirements

Python 3.8 or higher
pip 20.0 or higher

Quick Start

from memory_scope import MemoryScopeClient

# Initialize the client
client = MemoryScopeClient(api_key="your-api-key")

# Store a memory
memory = client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={
        "likes": ["pizza", "sushi"],
        "dislikes": ["broccoli"]
    }
)

# Read memories
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
)

print(result.summary_struct)
# {"likes": ["pizza", "sushi"], "dislikes": ["broccoli"]}

# Revoke access
client.revoke_memory(revocation_token=result.revocation_token)

Authentication

The SDK supports multiple ways to provide your API key:

Authentication Methods

from memory_scope import MemoryScopeClient
import os

# Method 1: Direct initialization
client = MemoryScopeClient(api_key="sk_test_...")

# Method 2: Environment variable (recommended)
client = MemoryScopeClient(api_key=os.getenv("MEMORY_SCOPE_API_KEY"))

# Method 3: The SDK will automatically check MEMORY_SCOPE_API_KEY env var
client = MemoryScopeClient()  # Uses MEMORY_SCOPE_API_KEY from environment

API Methods

create_memory()

Create a new memory with a scope, domain, and value.

create_memory

memory = client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    ttl_days=30,  # Optional
    value_json={
        "likes": ["pizza", "sushi"],
        "dislikes": ["broccoli"]
    }
)

# Returns: MemoryCreateResponse
print(memory.id)
print(memory.expires_at)

Parameters

user_id (str, required) - User identifier
scope (str, required) - Scope category
domain (str, optional) - Domain sub-category
source (str, required) - Source of the memory
ttl_days (int, optional) - Time-to-live in days
value_json (dict, required) - Memory data as JSON

read_memory()

Read memories with policy enforcement. Returns merged results and a revocation token.

read_memory

result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations",
    max_age_days=30  # Optional
)

# Returns: MemoryReadResponse
print(result.summary_text)
print(result.summary_struct)
print(result.confidence)
print(result.revocation_token)

read_memory_continue()

Continue reading memories using an existing revocation token.

read_memory_continue

result = client.read_memory_continue(
    revocation_token="rev_xyz789..."
)

# Returns: MemoryReadResponse (same format as read_memory)

revoke_memory()

Revoke access to memories using a revocation token.

revoke_memory

response = client.revoke_memory(
    revocation_token="rev_xyz789..."
)

# Returns: MemoryRevokeResponse
print(response.revoked)
print(response.revoked_at)

Error Handling

The SDK provides typed exceptions for different error types:

Error Handling

from memory_scope import MemoryScopeClient
from memory_scope.exceptions import (
    PolicyDeniedError,
    InvalidRequestError,
    AuthenticationError,
    NotFoundError,
    RateLimitError
)

try:
    result = client.read_memory(...)
except PolicyDeniedError as e:
    print(f"Policy denied: {e.message}")
except RateLimitError as e:
    print(f"Rate limit: {e.message}")
    # Implement retry logic
except AuthenticationError as e:
    print(f"Auth error: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Type Hints

The SDK includes full type hints for better IDE support and type checking:

Type Hints

from memory_scope import MemoryScopeClient
from memory_scope.models import MemoryCreateRequest, MemoryReadResponse

client = MemoryScopeClient(api_key="...")

# Type hints are available for all methods
memory: MemoryCreateResponse = client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"likes": ["pizza"]}
)

result: MemoryReadResponse = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate recommendations"
)

Configuration

Configure the client with custom settings:

Configuration

from memory_scope import MemoryScopeClient

client = MemoryScopeClient(
    api_key="your-api-key",
    base_url="https://api.memoryscope.dev",  # Optional, defaults to production
    timeout=30,  # Request timeout in seconds
    max_retries=3  # Number of retries for failed requests
)

Async Support

The SDK also supports async/await for asynchronous operations. Use AsyncMemoryScopeClient for async operations.