POST/memory

Create Memory

Create a new memory with a scope, domain, and value. The API will validate, normalize, and deduplicate your data automatically.

Authentication

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

Request Body

Request Schema

{
  "user_id": "string (required)",
  "scope": "string (required) - One of: preferences, constraints, communication, accessibility, schedule, attention",
  "domain": "string (optional) - Sub-category within the scope",
  "source": "string (required) - Source of the memory (e.g., 'explicit_user_input', 'inferred', 'system')",
  "ttl_days": "number (optional) - Time-to-live in days. Default: null (no expiration)",
  "value_json": "object (required) - The memory data as JSON"
}

Field Descriptions

user_id - Unique identifier for the user. This should be consistent across all operations for the same user.
scope - The scope category. Must be one of the 6 predefined scopes.
domain - Optional sub-category. Useful for organizing memories within a scope (e.g., "food" within "preferences").
source - Indicates where the memory came from. Common values: "explicit_user_input", "inferred", "system".
ttl_days - Optional expiration time. If set, the memory will automatically expire after this many days.
value_json - The actual memory data. Structure depends on the scope. Will be normalized and deduplicated automatically.

Example Request

from memory_scope import MemoryScopeClient

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

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

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

Response

Status Code: 201 Created

Success Response

{
  "id": "mem_abc123...",
  "user_id": "user123",
  "scope": "preferences",
  "domain": "food",
  "created_at": "2026-01-27T10:15:23Z",
  "expires_at": "2026-02-26T10:15:23Z"
}

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"
}

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.

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. See the Scopes documentation for guidance.
Set TTL When Appropriate: Use ttl_days for temporary memories that should expire automatically.
Use Domains for Organization: Domains help organize memories within a scope (e.g., "food", "music", "movies" within "preferences").
Include Source Information: The source field helps track where memories came from, which is useful for debugging and compliance.