Reading Memories

Learn how to read memories with policy enforcement, handle merged results, and work with revocation tokens.

Overview

Reading memories is a core operation that involves:

Policy Enforcement: The API checks if your purpose is allowed for the requested scope
Memory Merging: Multiple memories are automatically merged into a single result
Revocation Token: Every read returns a token that can be used to revoke access

Basic Example

from memory_scope import MemoryScopeClient

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

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

# Access the merged result
print(result.summary_text)
# "Likes: 2, Dislikes: 1, Settings: 0"

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

# Check confidence score
print(f"Confidence: {result.confidence}")
# Confidence: 0.85

# Save revocation token for later
revocation_token = result.revocation_token

Policy Enforcement

Every read operation requires a purpose that describes why you're accessing the memory. The API enforces a policy matrix to ensure memories are only accessed for allowed purposes.

Fail-Closed Behavior

If your purpose is not allowed for the scope, the API will return a 403 Forbidden response with no data. This protects user data by default. See Policy Enforcement for details.

Policy Enforcement Examples

# This will succeed - "recommendation" is allowed for "preferences"
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"  # Maps to "recommendation" purpose class
)

# This will fail - "task_execution" is NOT allowed for "preferences"
try:
    result = client.read_memory(
        user_id="user123",
        scope="preferences",
        domain="food",
        purpose="execute task to auto-order lunch"  # Maps to "task_execution" purpose class
    )
except Exception as e:
    print(f"Error: {e}")
    # Error: Purpose class 'task_execution' not allowed for scope 'preferences'

Using max_age_days

The max_age_days parameter allows you to filter out stale memories. Only memories created within the specified number of days will be included in the result.

max_age_days Examples

# Only get memories from the last 7 days
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations",
    max_age_days=7  # Only include memories from last 7 days
)

# Get all memories (no age limit)
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
    # max_age_days not specified - no limit
)

Understanding the Response

summary_text

A human-readable summary string, useful for logging and debugging.

"Likes: 2, Dislikes: 1, Settings: 0"

summary_struct

A structured JSON object containing the merged memory values, ready for use in your application.

{
  "likes": [
    "pizza",
    "sushi"
  ],
  "dislikes": [
    "broccoli"
  ],
  "settings": {}
}

confidence

A score between 0 and 1 indicating how reliable the merged result is. Higher scores indicate more consistent data.

0.85

revocation_token

A token that can be used to revoke access to the data that was read. Store this securely and associate it with the user session.

rev_xyz789...

Memory Merging

When multiple memories exist for the same user, scope, and domain, the API automatically merges them into a single result. The merging process is deterministic and scope-specific.

See Memory Merging for detailed information about how merging works.

Handling Policy Denials

Always Handle Denials

Policy denials are expected in some cases. Always handle 403 responses gracefully in your application code.

Handling Policy Denials

from memory_scope import MemoryScopeClient
from memory_scope.exceptions import PolicyDeniedError

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

try:
    result = client.read_memory(
        user_id="user123",
        scope="preferences",
        domain="food",
        purpose="execute task to auto-order lunch"
    )
except PolicyDeniedError as e:
    # Handle policy denial gracefully
    print(f"Access denied: {e.message}")
    # Fallback behavior - maybe use default preferences or ask user
    result = {"likes": [], "dislikes": []}  # Empty result
except Exception as e:
    # Handle other errors
    print(f"Error: {e}")

Best Practices

Use Descriptive Purposes: Write clear, descriptive purpose strings that accurately explain why you're accessing the memory.
Check Policy Matrix: Before making a request, verify that your purpose is allowed for the scope you're accessing.
Handle Policy Denials: Always handle 403 responses gracefully. Don't treat them as errors - they're a security feature.
Use max_age_days: Filter out stale memories by setting max_age_days appropriately for your use case.
Store Revocation Tokens: Save the revocation token securely and associate it with the user session so users can revoke access if needed.
Check Confidence Scores: Consider the confidence score when making decisions based on merged results. Low confidence may indicate incomplete data.
Use summary_struct: Prefer the structured format for programmatic access over the text summary.
Handle Empty Results: If no memories exist, the API returns empty structures. Handle this case in your application logic.

Next Steps

Revoking Access →API Reference →Memory Merging →