Basic Operations

Learn how to store, read, and revoke memories with the Memory Scope API. These examples cover the core operations you'll use in your applications.

Store User Preferences

Store user preferences with a scope, domain, and value. This example shows how to create a memory for food preferences.

Store User Preferences

from memory_scope import MemoryScopeClient

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

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

print(f"Memory created with ID: {memory.id}")
print(f"Expires at: {memory.expires_at}")

Expected Response

The API returns a memory object with an ID and expiration timestamp. If no TTL is specified, the memory doesn't expire.

Read with Policy Check

Read memories with policy enforcement. The API automatically checks if your purpose is allowed for the requested scope.

Read with Policy Check

from memory_scope import MemoryScopeClient
from memory_scope.exceptions import PolicyDeniedError

client = MemoryScopeClient(api_key="your-api-key")

try:
    # Read memories with a valid purpose
    result = client.read_memory(
        user_id="user123",
        scope="preferences",
        domain="food",
        purpose="generate food recommendations"
    )
    
    # Access merged results
    print("Summary text:", result.summary_text)
    print("Summary struct:", result.summary_struct)
    print("Confidence:", result.confidence)
    
    # Save revocation token
    revocation_token = result.revocation_token
    
except PolicyDeniedError as e:
    print(f"Policy denied: {e.message}")
    # Handle denial gracefully

Policy Enforcement

If the purpose is not allowed for the scope, the API returns a 403 Policy Denied error. Always handle this gracefully in your code.

Use the revocation token from a previous read to continue reading without creating a new grant. This is more efficient for related operations.

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

# Save the revocation token
revocation_token = result.revocation_token

# Later, continue reading with the same token
# This doesn't create a new grant
food_prefs = client.read_memory_continue(
    revocation_token=revocation_token
)

# You can continue reading multiple times with the same token
music_prefs = client.read_memory_continue(
    revocation_token=revocation_token
)

Revoke Access

Revoke access to memories using a revocation token. This gives users control over their data and is essential for privacy compliance.

Revoke Access

from memory_scope import MemoryScopeClient

client = MemoryScopeClient(api_key="your-api-key")

# Revoke access using a revocation token
response = client.revoke_memory(
    revocation_token="rev_xyz789..."
)

print(f"Revoked: {response.revoked}")
print(f"Revoked at: {response.revoked_at}")

User Control

Always provide users with a way to revoke access. Store revocation tokens securely and associate them with user sessions.

Complete Example: Store, Read, and Revoke

A complete example showing the full lifecycle: storing memories, reading them, and revoking access.

Complete Example

from memory_scope import MemoryScopeClient

client = MemoryScopeClient(api_key="your-api-key")

# 1. Store multiple memories
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"likes": ["pizza"]}
)

client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    value_json={"likes": ["sushi"]}
)

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

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

# 3. Save revocation token
revocation_token = result.revocation_token

# 4. Later, user revokes access
client.revoke_memory(revocation_token=revocation_token)
print("Access revoked successfully")