POST/memory/read

Read Memory

Read memories with policy enforcement. The API automatically merges multiple memories and returns a unified result with a revocation token.

Authentication

All requests require authentication via the X-API-Key header.

Policy Enforcement

This endpoint enforces the policy matrix. If the requested purpose is not allowed for the scope, the request will be denied with a 403 Forbidden response. See Policy Enforcement for details.

Request Body

Request Schema

{
  "user_id": "string (required)",
  "scope": "string (required) - One of: preferences, constraints, communication, accessibility, schedule, attention",
  "domain": "string (optional) - Filter by domain",
  "purpose": "string (required) - Purpose for accessing the memory (e.g., 'generate food recommendations')",
  "max_age_days": "number (optional) - Only return memories created within this many days. Default: null (no limit)"
}

Field Descriptions

user_id - Unique identifier for the user.
scope - The scope category to read from.
domain - Optional domain filter. If provided, only memories with this domain are returned.
purpose - A descriptive string explaining why you're accessing the memory. This is normalized to a purpose class and checked against the policy matrix.
max_age_days - Optional filter to only return memories created within the specified number of days. Useful for excluding stale data.

Example Request

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",
    max_age_days=30
)

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

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

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

print(f"Revocation token: {result.revocation_token}")
# Revocation token: rev_xyz789...

Response

Status Code: 200 OK

Success Response

{
  "summary_text": "Likes: 2, Dislikes: 1, Settings: 0",
  "summary_struct": {
    "likes": [
      "pizza",
      "sushi"
    ],
    "dislikes": [
      "broccoli"
    ],
    "settings": {}
  },
  "confidence": 0.85,
  "revocation_token": "rev_xyz789...",
  "expires_at": "2026-01-28T10:15:24Z"
}

Response Fields

summary_text - A human-readable summary string of the merged memories.
summary_struct - A structured JSON object containing the merged memory values, ready for use in your application.
confidence - A confidence score between 0 and 1 indicating how reliable the merged result is.
revocation_token - A token that can be used to revoke access to the data that was read. See Revocation Tokens for details.
expires_at - When the revocation token expires (typically 24 hours from creation).

Policy Denial Example

Policy Violation

When a purpose is not allowed for a scope, the API returns a 403 Forbidden response with no data.

Policy Denial Example

from memory_scope import MemoryScopeClient

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

# 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"
    )
except Exception as e:
    print(f"Error: {e}")
    # Error: Purpose class 'task_execution' not allowed for scope 'preferences'

Error Responses

400 Bad Request

Invalid request body or missing required fields.

{
  "detail": "Field 'user_id' is required"
}

401 Unauthorized

Invalid or missing API key.

{
  "detail": "Invalid API key"
}

403 Forbidden

Policy violation - the requested purpose is not allowed for the scope.

{
  "detail": "Purpose class 'task_execution' not allowed for scope 'preferences'"
}

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.

The confidence score indicates how reliable the merged result is. Higher scores (0.8+) indicate multiple consistent memories, while lower scores may indicate incomplete or conflicting data.

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 in your application code.
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 so users can revoke access if needed.
Check Confidence Scores: Consider the confidence score when making decisions based on merged results.
Use summary_struct: Prefer the structured format for programmatic access over the text summary.