Memory Model

Real Examples

Real wire shapes for the most common operations. These are the schemas the API actually validates against — copy them as-is, not from blog posts.

The smallest add request that works

JSON

{
  "text": "Alice decided to adopt a microservices architecture for the Q2 roadmap."
}

The extraction pipeline classifies this as a decision, scores its importance, fills in a default importance of 0.5, an empty metadata, an empty tags list, and stores the row.

A rich add request

JSON

{
  "text": "Budget approved: $50K for infrastructure upgrades",
  "metadata": {
    "file_type": "pdf",
    "department": "finance",
    "fiscal_year": "2026"
  },
  "source": "email",
  "event_type": "financial_decision",
  "tags": ["budget", "urgent"],
  "importance": 0.9,
  "ttl_minutes": 10080
}

ttl_minutes: 10080 is seven days — retention_expires_at is set to one week from now and the lifecycle timeline shifts accordingly.

The shape the API returns

JSON

{
  "id": 42,
  "user_id": 10,
  "text": "Budget approved: $50K for infrastructure upgrades",
  "summary": "Finance approved $50K for infrastructure",
  "created_at": "2026-05-05T14:22:00+00:00",
  "updated_at": "2026-05-05T14:22:00+00:00",
  "metadata": { "file_type": "pdf", "department": "finance", "fiscal_year": "2026" },
  "tags": ["budget", "urgent"],
  "source": "email",
  "event_type": "financial_decision",
  "tier": "hot",
  "importance": 0.9,
  "is_summary": false,
  "expires_at": "2026-05-12T14:22:00+00:00",
  "key_points": ["Budget approved", "$50K allocation"],
  "quality_score": 0.87,
  "memory_type": "financial_decision"
}

A recall query

JSON

{
  "query": "What budgets were approved for infrastructure?",
  "k": 5,
  "filters": {
    "sources": ["email"],
    "tags": ["budget"],
    "since": "2026-04-01T00:00:00+00:00",
    "until": "2026-05-31T23:59:59+00:00",
    "include_summaries": true,
    "tier": "hot"
  },
  "weights": {
    "semantic": 0.5,
    "recency": 0.3,
    "importance": 0.2
  },
  "session_id": "sess_abc123"
}

k is clamped server-side to [1, 50]. The weights dict is normalised so its values sum to 1.

A forget (delete) request

JSON

{
  "memory_ids": [42, 43, 44],
  "reason": "User data subject request under GDPR Article 17"
}

The reason is recorded on the audit log and the deletion method is set to gdpr_request. Hard deletion proceeds after the seven-day soft-delete grace.

An internal extraction candidate (for reference)

JSON

{
  "extracted_text": "Alice decided microservices",
  "category": "decision",
  "importance_score": 0.87,
  "confidence": 0.92,
  "decision": "created",
  "memory_id": 42,
  "created_at": "2026-05-05T14:22:00+00:00"
}

This is the row the extraction pipeline writes to its own table; you cannot create one directly through the public API. It exists so the platform can answer "why was this memory created?" months later.

Common field conflations to avoid

importance (caller hint, [0, 1]) is not the same as importance_score (platform score, [0, 100]).
summary on a MemoryResponse is the model-produced one-line summary, not the multi-row cluster summary you get from the summarizer.
memory_type in the response is a high-level tag set by analysis, not extracted_type.

← Previous

Memory Types

Common Mistakes