Memory API

Three endpoints cover most agent use cases. They share the same authentication, the same identity model (user_id / group_id), and the same error envelope.

For the complete request and response schemas, see the interactive API reference.

Authentication

All three endpoints accept a project API key as a bearer token:

Authorization: Bearer mhq_live_...

Project keys are scoped to a single project and grant read and write access to memory. Use the dashboard's Settings → API Keys to create and rotate keys.

POST /v1/memhq/add

Ingest one or more messages into a per-user or group graph. Returns immediately with an episode_id; the actual extraction and indexing runs asynchronously (typically completing within 2-6 seconds — see Ingestion pipeline).

Request

Example

episode = client.add(
    user_id="user_42",
    messages=[
        {"role": "user", "content": "I'm a vegetarian."},
        {"role": "assistant", "content": "Noted — I'll keep that in mind."},
    ],
    metadata={"channel": "support_chat"},
)
print(episode.id)

POST /v1/memhq/search

Hybrid (vector + lexical) retrieval over the project's memory.

Request

You can pass both user_id and group_id in the same call to search a user's private memory together with shared group context.

Response

{
  "memories": [
    {
      "id": "mem_01HZ...",
      "content": "Vegetarian.",
      "score": 0.91,
      "entities": [{ "id": "ent_user_42", "name": "User 42" }],
      "source_episode_id": "epi_01HZ...",
      "created_at": "2026-05-12T14:33:02Z",
      "status": "active"
    }
  ],
  "query_id": "qry_01HZ..."
}

POST /v1/memhq/ask

Retrieve, synthesize, and return an answer with citations. Use this when you want MemHQ to do the prompt engineering for you; use search when you want raw memories to feed into your own prompt.

Request

Response

{
  "text": "They prefer dark roast, no sugar.",
  "sources": [
    {
      "memory_id": "mem_01HZ...",
      "content": "Prefers dark roast coffee, no sugar.",
      "score": 0.94
    }
  ],
  "query_id": "qry_01HZ..."
}

Errors

All endpoints share a single error envelope:

{
  "error": "user_id_or_group_id_required",
  "code": 400,
  "correlationId": "req_01HZ..."
}

Common errors: