memoria
← All docsRead as markdown

REST API

Memoria's REST API is the lowest-level interface — the SDK and MCP server both call it under the hood. Use it when you want full control, or when you're integrating from a language that doesn't have an official SDK yet.

Base URL: https://api.memoria.premex.se

OpenAPI 3 spec: api.memoria.premex.se/openapi.yaml

Authentication

Send your API key as a Bearer token:

curl https://api.memoria.premex.se/v1/recall \
  -H "Authorization: Bearer mem_live_…" \
  -H "Content-Type: application/json" \
  -d '{"query": "Where does Stefan work?"}'

API keys are brain-scoped: each key authorizes operations against exactly one brain. To work across brains, create one key per brain.

Common conventions

  • All endpoints return JSON. UTF-8 throughout.
  • Timestamps are ISO-8601 with timezone (2026-05-28T10:00:00Z).
  • Errors return {"error": "...", "details": ...} with appropriate 4xx/5xx codes.
  • Pagination is cursor-based: pass ?cursor=<opaque> from the previous response's next field.

Endpoints

POST /v1/episodes — store a memory

{
  "content": "Stefan joined Premex as a Senior Engineer in 2023.",
  "metadata": { "source": "onboarding-notes" }
}

Returns the created episode and kicks off the extraction pipeline. Extraction is async — entities and edges appear in subsequent recalls once the pipeline completes (typically <2s).

POST /v1/recall — retrieve facts

{
  "query": "Where does Stefan work?",
  "asOf": "2026-01-01",
  "limit": 10
}

Returns:

{
  "context": "Stefan is a Senior Engineer at Premex …",
  "edges": [ … bi-temporal edges with scores … ],
  "episodes": [ … source episodes for citation … ]
}

asOf is optional. Omit it to query "as of right now."

GET /v1/entities/:id — entity details

Returns the entity plus the most recent valid edges it participates in.

GET /v1/edges/:id — edge details

Returns the full edge including both time ranges (tValid/tInvalid, tIngested/tExpired) and the source episode.

POST /v1/edges/:id/invalidate — mark a fact superseded

Doesn't delete the edge — sets tInvalid to the current time and marks why. The edge stays queryable with asOf time-travel.

GET /v1/playbooks/:slug — fetch a playbook

Playbooks are agent-readable summaries derived from memories. See Playbooks (coming soon).

Rate limits

  • Free tier: 1,000 successful calls / day per brain
  • Soft-fail with 429 Too Many Requests once exceeded; resets at midnight UTC.

Paid plans are launching soon — check pricing for current quotas.

SDK or raw?

Most agents should use the SDK or MCP server — they handle retries, request signing, and pagination for you. Drop to raw REST when you need a language not yet supported or want to debug the wire format.