API Reference

Memory API

Five core endpoints: add, query, summarize, forget, export. All require an API key with memory:* scopes and an X-Project-ID header.

Authentication

Send the API key as Authorization: Bearer ms_live_… or X-API-Key: ms_live_…. The key is environment-bound; the environment is attached to all requests automatically.

Common headers

Header	Required	Description
Authorization	yes (or X-API-Key)	Bearer ms_live_…
X-Project-ID	recommended	prj_xxx — defaults to org default project
X-End-User-ID	optional	For B2B: pin memory to your end user
Idempotency-Key	optional	Replay-safe writes
Content-Type	yes	application/json

Add memory

POST/memory/add

Request

JSON

{
  "text": "Customer 8821 reported login failures after MFA reset.",  // or "content"
  "source": "support_ticket",
  "event_type": "incident_resolved",
  "tags": ["mfa", "incident"],
  "importance": 0.6,
  "ttl_minutes": 43200,
  "metadata": { "ticket_id": "ZD-9128" },
  "deduplicate": true
}

Response · 201 Created

JSON

{
  "id": 18420,
  "user_id": 1042,
  "text": "Customer 8821 reported login failures after MFA reset.",
  "tier": "hot",
  "importance": 0.6,
  "tags": ["mfa", "incident"],
  "created_at": "2026-05-04T11:42:01Z"
}

Note

When your organisation is over its monthly write quota, the route silently returns 200 with { "status": "ok" } and the memory is not stored. No error is surfaced to the caller.

Query memories

POST/memory/query

Request

JSON

{
  "query": "What did we decide about MFA enforcement?",
  "k": 5,
  "filters": {
    "sources": ["support_ticket", "slack"],
    "tags": ["decision"],
    "since": "2026-04-01T00:00:00Z",
    "tier": "hot",
    "include_summaries": true
  },
  "weights": {
    "semantic": 0.5, "recency": 0.2, "importance": 0.15,
    "quality": 0.05, "decay": 0.0, "usage": 0.05, "graph": 0.05
  },
  "traversal_depth": 2,
  "session_id": "ses_01HMRT…",
  "computation_tier": "medium"
}

Response · 200

JSON

{
  "memories": [
    {
      "id": 18420,
      "text": "Customer 8821 reported login failures after MFA reset.",
      "summary": null,
      "tier": "hot",
      "score": 0.91,
      "scores": { "semantic": 0.88, "recency": 1.0, "importance": 0.6 },
      "explain": ["matched topic 'authentication'"],
      "tags": ["mfa", "incident"],
      "memory_type": "event"
    }
  ],
  "computation_tier": "medium",
  "session_id": "ses_01HMRT…",
  "filter_relaxed": false,
  "latency_ms": 28
}

Summarize

POST/memory/summarize

JSON

{
  "memory_ids": [18420, 18411, 18399, 18372],
  "lossless": false
}

Returns the new summary memory with is_summary: true. With lossless: true the originals are preserved; otherwise they are tiered to cold.

Forget

DELETE/memory/forget

JSON

{
  "memory_ids": [18420],
  "reason": "GDPR erasure ER-2841"
}

Returns the list of deleted ids. An audit row is written first; PII-tagged memories require a reason.

Export

GET/memory/export

Returns a JSON bundle of all memories owned by the authenticated user, ready for compliance handoff. Pagination via ?cursor=…&limit=500.

Errors

Status	Code	Meaning
400	invalid_payload	Schema or constraint violation
401	unauthorized	Missing or invalid API key
403	scope_required	Key lacks required scope
404	memory_not_found	On forget/summarize for unknown id
422	min_length	Text shorter than 10 characters
429	rate_limited	Per-IP/route rate limit exceeded (not billing)
503	embedding_unavailable	All providers failed including local

Rate limits

Free: 60 requests / minute / project.
Starter: 600 / minute.
Scale: 6,000 / minute.
Enterprise: configurable; default 30,000 / minute.

Limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

← Previous

Pagination & Filters

Add Memory