Optimize User Memories

Database and user

Use a registered memory-capable database, such as the SQLite database in the example API server. Supply db_id when several database IDs are available. A table selector requires db_id and selects a configured adapter; it does not create arbitrary storage.

Scoped identity overrides a supplied user_id. JWT user isolation is opt-in; non-admin service-account PAT callers always self-scope. When authorization is enforced, use the appropriate memories:read, memories:write or memories:delete scope.

Preview before applying

Optimization calls a model. Install the chosen provider's SDK and configure its credentials. Supply the user and database, then start with a preview:

{"user_id":"example-user","model":"openai:gpt-5.4-mini","apply":false}

For this explicit OpenAI example, install openai and set OPENAI_API_KEY; use a model your account can access. Omitting model uses the current source default, gpt-4o. No matching memories returns 404.

apply defaults to true. Applying replaces the user's memory set with the generated summary and new memory IDs. Summarization does not guarantee fewer tokens or preservation of every fact.

On current main, a longer summary can produce negative reduction statistics that fail response validation with 500. With apply=true, the memories may already have been replaced before that response fails. Reread stored memories before retrying an applied optimization. A failed apply=false preview leaves the originals unchanged.

POST/optimize-memories

Optimize all memories for a given user using the default summarize strategy. This operation combines all memories into a single comprehensive summary, achieving maximum token reduction while preserving all key information. To use a custom model, specify the model parameter in 'provider:model_id' format (e.g., 'openai:gpt-4o-mini', 'anthropic:claude-3-5-sonnet-20241022'). If not specified, uses MemoryManager's default model (gpt-4o). Set apply=false to preview optimization results without saving to database.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

db_id?|

Database ID to use for optimization

table?|

Table to use for optimization

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Schema for memory optimization request

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request POST 'https://example.com/optimize-memories' \  --header 'Content-Type: application/json' \  --data-raw '{"user_id":"string"}'
{  "memories": [    {      "memory_id": "f9361a69-2997-40c7-ae4e-a5861d434047",      "memory": "User has a 3-year-old golden retriever named Max who loves fetch and walks. Lives in San Francisco's Mission district, works as a product manager in tech. Enjoys hiking Bay Area trails, trying new restaurants (especially Japanese, Thai, Mexican), and learning piano for 1.5 years.",      "topics": [        "pets",        "location",        "work",        "hobbies",        "food_preferences"      ],      "user_id": "user2",      "updated_at": "2025-11-18T10:30:00Z"    }  ],  "memories_before": 4,  "memories_after": 1,  "tokens_before": 450,  "tokens_after": 180,  "tokens_saved": 270,  "reduction_percentage": 60}