Memory

/api/memory/* exposes Clone's hierarchical Memory layer. Four tiers (profile → facts → episodes → raw) plus the headline /context/ endpoint that bundles them for the Prediction layer. All endpoints are scoped to request.user.

Endpoints

Method	Path	Purpose
GET / POST	/api/memory/raw/	List or append RawMemory rows.
GET / DELETE	/api/memory/raw/<uuid>/	Single row.
GET / POST	/api/memory/episodes/	List or append EpisodicMemory rows.
GET / PATCH / DELETE	/api/memory/episodes/<uuid>/	Single episode.
GET / POST	/api/memory/facts/	List or append SemanticMemory facts.
GET / PATCH / DELETE	/api/memory/facts/<uuid>/	Single fact.
GET / POST / DELETE	/api/memory/profile/	Read, upsert, or delete the singleton UserProfile.
POST	/api/memory/context/	Assemble the layered bundle the Prediction layer consumes.
POST	/api/memory/sync/	Derive RawMemory rows from existing RecordingEvent rows. Idempotent.
GET	/api/memory/stats/	Counts and last-update timestamps per tier.
POST	/api/memory/promote/episodes/	Cluster recent un-summarized raw rows into episode drafts (LLM).
POST	/api/memory/promote/facts/	Distill fact rows from recent episodes (LLM).

The headline call — POST /context/

curl -sS -X POST https://api.clone.is/api/memory/context/ \
  -H "X-Clone-API-Key: $CLONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recency_minutes": 60,
    "max_facts": 20,
    "max_episodes": 10,
    "max_raw": 50
  }'

Body fields (all optional):

Field	Default	Range	Notes
goal	—	string	Substring filter on fact text.
tags	—	string[]	Facts must contain at least one tag.
recency_minutes	60	1–10080	Window for episodes and raw items.
max_facts	20	1–100	Cap on facts returned.
max_episodes	10	1–50	Cap on episodes returned.
max_raw	50	1–500	Cap on raw items returned.

Returns { profile, facts, episodes, raw, meta }. The Prediction layer calls this in-process, so client-issued requests get the same bundle the LLM would see.

Promotion pipeline

POST /api/memory/promote/episodes/ clusters recent un-summarized raw rows into draft episodes via Anthropic. POST /api/memory/promote/facts/ distills atomic facts from recent episodes. Both accept since, limit, model (overrides default claude-sonnet-4-6), and force (bypass the "already promoted" filter). Errors map the same way the Prediction layer does — 503 on missing/invalid Anthropic key, 429 on rate limit, 502 on upstream non-2xx.

Stats

curl -sS https://api.clone.is/api/memory/stats/ \
  -H "X-Clone-API-Key: $CLONE_API_TOKEN"

Returns counts and last-update timestamps per tier; takes optional ?since= to scope to a window. Used by the Web dashboard's Memory page.