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)

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

curl https://api.memhq.ai/v1/memhq/add \
  -H "Authorization: Bearer $MEMHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_42",
    "messages": [
      {"role": "user", "content": "I am a vegetarian."},
      {"role": "assistant", "content": "Noted — I will keep that in mind."}
    ],
    "metadata": {"channel": "support_chat"}
  }'

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: