Policy Enforcement

The Memory Scope API uses a policy matrix to ensure memories are only accessed for allowed purposes. This fail-closed system protects user data by default.

What is Policy Enforcement?

Policy enforcement is a core security feature of the Memory Scope API. Every read operation must specify a purpose that describes why you're accessing the memory. The API then checks this purpose against a policy matrix to determine if access is allowed.

The policy system is fail-closed, meaning:

If a purpose is not explicitly allowed for a scope, access is automatically denied
No data is returned when access is denied
All policy violations are logged in the audit trail
This protects user data even if your application code has bugs

Policy Matrix

Each scope defines which purpose classes are allowed for accessing memories. The API enforces this matrix and denies access for any purpose not explicitly allowed (fail-closed).

Scope / Purpose	content generation	recommendation	scheduling	task execution	notification delivery	ui rendering
preferences
constraints
communication
accessibility
schedule
attention

Fail-Closed Behavior: If a purpose class is not explicitly allowed for a scope, the API will return a 403 Forbidden response. This ensures user data is protected by default.

Purpose Normalization: The API automatically normalizes purpose strings to purpose classes. For example, "generate food recommendations" maps to recommendation.

Purpose Classes

The API normalizes purpose strings into purpose classes. This allows flexible purpose descriptions while maintaining consistent policy enforcement.

content_generation

Generate personalized content based on user preferences

Examples:

"generate food recommendations"
"create personalized email"

recommendation

Provide recommendations and suggestions

Examples:

"recommend restaurants"
"suggest products"

scheduling

Schedule events and manage availability

Examples:

"schedule meeting"
"check availability"

task_execution

Execute tasks on behalf of the user

Examples:

"auto-order lunch"
"book appointment"

notification_delivery

Deliver notifications according to user preferences

Examples:

"send notification"
"deliver alert"

ui_rendering

Render UI elements based on user preferences

Examples:

"render dashboard"
"display settings"

How Policy Enforcement Works

Request with Purpose: Your application makes a read request with a purpose string describing why you need the memory.
Purpose Normalization: The API normalizes your purpose string to a purpose class (e.g., "generate food recommendations" → "recommendation").
Policy Check: The API checks if the purpose class is allowed for the requested scope in the policy matrix.
Access Decision:
- Allowed: Memory is returned with merged results and a revocation token.
- Denied: 403 Forbidden response with no data returned. Event is logged in audit trail.

Example: Allowed Access

Allowed Access Example

from memory_scope import MemoryScopeClient

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

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

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

Example: Denied Access

Policy Violation

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

Denied Access 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'

Best Practices

Be Specific: Use clear, descriptive purpose strings that accurately describe why you're accessing the memory.
Handle Denials: Always handle 403 responses gracefully in your application code.
Check Policy Matrix: Before making a read request, verify that your purpose is allowed for the scope you're accessing.
Audit Logs: Review audit logs regularly to identify any unexpected policy denials.
Fail Gracefully: If access is denied, provide a user-friendly message or fallback behavior rather than showing an error.