API

Hosted mem9 API reference

Use the hosted mem9 API to provision a space, write or search memory, import existing files, and inspect captured session messages.

Prefer `v1alpha2` for day-to-day usage. `v1alpha1` stays available for key provisioning and tenant-scoped compatibility.

Base URL & authentication

Hosted base URL

Use `https://api.mem9.ai`. For normal client traffic, send requests to `https://api.mem9.ai/v1alpha2/mem9s/...`.

Primary auth header

Send your mem9 API key in `X-API-Key`. This is the default hosted auth model for `v1alpha2`.

Optional agent identity

Send `X-Mnemo-Agent-Id` when you want writes and imports attributed to a specific agent. Legacy tenant-scoped routes still exist under `v1alpha1`.

Quick start

A minimal hosted flow is: provision a key, export it into your shell, then create and search memories.

  1. Provision a new API key with `POST /v1alpha1/mem9s`.
  2. Export that key as `API_KEY` and set `API=https://api.mem9.ai/v1alpha2/mem9s`.
  3. Create a memory with `POST /memories`.
  4. Search it back with `GET /memories?q=...`.

Provision key

curl -sX POST https://api.mem9.ai/v1alpha1/mem9s

Export env vars

export API_KEY="your-api-key"
export API="https://api.mem9.ai/v1alpha2/mem9s"

Create memory

curl -sX POST "$API/memories" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Mnemo-Agent-Id: openclaw-main" \
  -d '{"content":"Project uses PostgreSQL 15","tags":["tech","database"],"metadata":{"source":"setup-note"}}'

Search memories

curl -s -H "X-API-Key: $API_KEY" "$API/memories?q=postgres&limit=5"

Provisioning

Create the initial key you will reuse for hosted mem9 access.

POST /v1alpha1/mem9s

Provision a new mem9 API key.

No auth or request body is required. The hosted service returns `201` with an `id` field, and that `id` is the key you store and reuse.

Response

id Required
The newly provisioned mem9 API key / space identifier.

Examples

Provision key

curl -sX POST https://api.mem9.ai/v1alpha1/mem9s

Memories

Create, search, read, update, and delete stored memories in your mem9 space.

POST /v1alpha2/mem9s/memories

Create a memory or ingest messages.

Use `content` for direct writes or `messages` for ingest-driven writes. Do not send both in the same request.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
Content-Type Required
Set to `application/json` for JSON request bodies.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.

Body

content
Plain memory content for direct writes.
messages
Conversation messages for ingest-based writes.
agent_id
Optional agent id to store with the write.
session_id
Optional session id for ingest or attribution.
tags
Optional string tags stored on the memory.
metadata
Optional JSON metadata payload.
mode
Ingest mode such as `smart` or `raw` when using `messages`.
sync
When true, wait for completion before returning.

Response

status Required
Handler result such as `ok` or `accepted`.

Examples

Create memory

curl -sX POST "$API/memories" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Mnemo-Agent-Id: openclaw-main" \
  -d '{"content":"Project uses PostgreSQL 15","tags":["tech","database"],"metadata":{"source":"setup-note"}}'
GET /v1alpha2/mem9s/memories

List or search memories.

When `q` is present, the handler runs recall search. Without `q`, the endpoint behaves like a filtered list API.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.

Query Params

q
Semantic / keyword search query.
tags
Comma-separated tag filter.
source
Filter by stored source value.
state
Filter by lifecycle state such as `active` or `archived`.
memory_type
Filter by `insight`, `pinned`, or `session`.
agent_id
Filter by agent id.
session_id
Filter by session id.
limit
Page size. The handler caps large values.
offset
Offset for pagination.

Response

memories Required
Array of memory objects for the current page.
total Required
Total matched rows before pagination.
limit Required
Applied page size.
offset Required
Applied page offset.

Examples

Search memories

curl -s -H "X-API-Key: $API_KEY" "$API/memories?q=postgres&limit=5"

Filter by tags / source

curl -s -H "X-API-Key: $API_KEY" "$API/memories?tags=tech&source=openclaw-main&limit=10"
GET /v1alpha2/mem9s/memories/{id}

Read one memory by id.

Fetch a single stored memory object from the hosted service.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.

Response

id Required
Memory id.
content Required
Stored memory content.
memory_type Required
Memory type such as `insight`, `pinned`, or `session`.
state Required
Lifecycle state.
version Required
Current integer version.
created_at Required
Creation timestamp.
updated_at Required
Last update timestamp.

Examples

Get memory

curl -s -H "X-API-Key: $API_KEY" "$API/memories/{id}"
PUT /v1alpha2/mem9s/memories/{id}

Update one memory.

Update content, tags, or metadata. Send `If-Match` when you want optimistic version checks.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
Content-Type Required
Set to `application/json` for JSON request bodies.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.
If-Match
Optional version guard for optimistic updates.

Body

content
Updated memory content.
tags
Updated tag array.
metadata
Updated JSON metadata payload.

Response

id Required
Memory id.
content Required
Stored memory content.
memory_type Required
Memory type such as `insight`, `pinned`, or `session`.
state Required
Lifecycle state.
version Required
Current integer version.
created_at Required
Creation timestamp.
updated_at Required
Last update timestamp.

Examples

Update memory

curl -sX PUT "$API/memories/{id}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "If-Match: 3" \
  -d '{"content":"Project uses PostgreSQL 16","tags":["tech","database"]}'
DELETE /v1alpha2/mem9s/memories/{id}

Delete one memory.

Deletes the selected memory row and returns `204 No Content` on success.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.

Examples

Delete memory

curl -sX DELETE -H "X-API-Key: $API_KEY" "$API/memories/{id}"

Imports

Upload memory or session files and poll their background task status.

POST /v1alpha2/mem9s/imports

Create an import task.

Upload a file as `memory` or `session`. The handler queues asynchronous processing and returns a task id immediately.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
Content-Type Required
Your HTTP client sends this as `multipart/form-data`.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.

Body

file Required
Uploaded file payload.
file_type Required
Use `memory` or `session`.
agent_id
Optional agent id for attribution.
session_id
Required when uploading `session` files.

Response

id Required
Task id for polling.
status Required
Initial task status such as `pending`.

Examples

Import memory file

curl -sX POST "$API/imports" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@memory.json" \
  -F "file_type=memory" \
  -F "agent_id=openclaw-main"

Import session file

curl -sX POST "$API/imports" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@session.json" \
  -F "file_type=session" \
  -F "session_id=ses-001" \
  -F "agent_id=openclaw-main"
GET /v1alpha2/mem9s/imports

List import tasks.

Return all import tasks visible in the current mem9 space.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.

Response

status Required
Aggregate task status for the tenant.
tasks Required
Array of import task summaries.

Examples

List import tasks

curl -s -H "X-API-Key: $API_KEY" "$API/imports"
GET /v1alpha2/mem9s/imports/{id}

Read one import task.

Poll a single task until it becomes `done` or `failed`.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.

Response

id Required
Task id.
file Required
Uploaded file name.
status Required
Task status.
total Required
Total chunk count.
done Required
Completed chunk count.
error
Error message when the task fails.

Examples

Get import task

curl -s -H "X-API-Key: $API_KEY" "$API/imports/{id}"

Session Messages

Inspect raw captured conversation rows that were stored during ingest.

GET /v1alpha2/mem9s/session-messages

List session messages by session id.

Repeat `session_id` in the query string for each session you want to fetch. Use `limit_per_session` to cap rows per session.

Headers

X-API-Key Required
Hosted API key for your mem9 space.
X-Mnemo-Agent-Id
Optional agent identity header for attribution.

Query Params

session_id Required
Repeat this query param for each session to fetch.
limit_per_session
Optional per-session row limit.

Response

messages Required
Array of captured session message rows.
limit_per_session Required
Applied per-session limit.

Examples

Read session messages

curl -s -H "X-API-Key: $API_KEY" "$API/session-messages?session_id=ses-001&session_id=ses-002&limit_per_session=20"

Health & Compatibility

Use `/healthz` for liveness checks. Legacy tenant-scoped routes still exist under `/v1alpha1/mem9s/{tenantID}/...`, but hosted clients should prefer `v1alpha2` plus `X-API-Key`.

GET /healthz

Check service health.

Useful before onboarding or when debugging network reachability.

Response

status Required
Health status string. Hosted service returns `ok`.

Examples

Health check

curl -s https://api.mem9.ai/healthz

Next

Need the guided path instead?

If you are onboarding OpenClaw rather than building a direct integration, start from the public SKILL.md. Use the same API key later in Your Memory.

SKILL.md Your Memory GitHub