Storing Memories

Learn how to store user memories with proper scoping, domains, and data organization.

Overview

Storing memories is the first step in using the Memory Scope API. When you create a memory, you specify:

Scope: The category of memory (preferences, constraints, etc.)
Domain: Optional sub-category for organization
Value: The actual memory data as JSON
Source: Where the memory came from
TTL: Optional expiration time

Basic Example

from memory_scope import MemoryScopeClient

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

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

print(f"Created memory: {memory.id}")

Choosing the Right Scope

The scope determines the category and policy rules for your memory. Choose the scope that best fits your use case:

preferencesUser likes, dislikes, and general preferences

Example: Food preferences, music taste, favorite colors

constraintsRules, boundaries, and limitations

Example: Dietary restrictions, budget limits, availability windows

communicationCommunication style and tone preferences

Example: Preferred tone, emoji usage, formality level

accessibilityAccessibility requirements and preferences

Example: High contrast mode, font size, screen reader preferences

scheduleTime-based availability and scheduling

Example: Work hours, meeting preferences, timezone

attentionFocus and attention-related preferences

Example: Do not disturb settings, focus mode, notification preferences

See Scopes documentation for detailed information about each scope.

Using Domains

Domains are optional sub-categories that help organize memories within a scope. They allow you to group related memories together.

Domain Examples

# Store food preferences
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",  # Domain for food-related preferences
    source="explicit_user_input",
    value_json={"likes": ["pizza", "sushi"]}
)

# Store music preferences
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="music",  # Domain for music-related preferences
    source="explicit_user_input",
    value_json={"likes": ["jazz", "classical"]}
)

# Both are in the "preferences" scope but different domains

Setting TTL (Time-to-Live)

You can set an expiration time for memories using the ttl_days parameter. Memories will automatically expire after the specified number of days.

TTL Examples

# Store a temporary preference that expires in 7 days
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    ttl_days=7,  # Expires in 7 days
    value_json={"likes": ["seasonal_special"]}
)

# Store a long-term preference (no expiration)
client.create_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    source="explicit_user_input",
    # ttl_days not specified - no expiration
    value_json={"likes": ["pizza"]}
)

Data Normalization

The API automatically normalizes and deduplicates values when creating memories. For example, duplicate items in arrays are removed, and values are normalized according to scope-specific rules. You don't need to worry about cleaning your data before sending it.

Source Field

The source field indicates where the memory came from. Common values include:

explicit_user_input - User directly provided this information
inferred - Information was inferred from user behavior
system - System-generated or default value
import - Imported from another system

The source field is useful for debugging, compliance, and understanding data provenance.

Best Practices

Use Consistent user_id: Always use the same user_id format across all operations for the same user.
Choose Appropriate Scope: Select the scope that best fits your use case. This affects policy enforcement and merging behavior.
Use Domains for Organization: Domains help organize memories within a scope. Use them to group related memories together.
Set TTL for Temporary Data: Use ttl_days for temporary memories that should expire automatically (e.g., seasonal preferences, temporary constraints).
Include Source Information: Always include accurate source information for compliance and debugging.
Don't Worry About Duplicates: The API handles normalization and deduplication automatically. You can create multiple memories and they'll be merged when read.
Use Structured Data: Store data in a structured format (JSON) that makes sense for your use case. The API will handle the merging logic.

Next Steps

Reading Memories →API Reference →