v1

Add Memory

Store a memory for an end user (user_id), an agent (agent_id) or a run (run_id).

The call returns once the memory is stored. Its typed facts are extracted by a model after that, so the reply says status: processing with facts: []; a server run with WRITE_ASYNC=false extracts before answering and returns the facts inline. Poll GET /v1/events or read the memory again to see them.

timestamp is when the events happened, not when you send them: the facts take it as valid_from, so reads with as_of answer about the right date. An unreadable one is a 422, never a silent "now".

post/v1/memories

Request

  • Base URL: https://api.korely.ai
  • URL: https://api.korely.ai/v1/memories
  • Auth: HTTP bearer

Headers

X-Korely-Clientstring nullable

The tool writing, e.g. claude-code: kept on the memory as client. Not a namespace and not counted in the agent cap.

Request body

contentstring required
user_idstring nullable

The end user this memory belongs to. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users/<user_id>/memories and DELETE /v1/agents/<agent_id> address as one URL path segment.

agent_idstring nullable

Agent namespace. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users/<user_id>/memories and DELETE /v1/agents/<agent_id> address as one URL path segment.

run_idstring nullable
metadataobject nullable
kind'note' | 'session'

What the text is: note (the default), what somebody said or decided; session, the log of a work session (what a coding assistant's hooks save). A read may leave the sessions out, their facts with them (exclude_sessions).

timestampstring nullable

ISO date/datetime the memory's events occurred (defaults to now). Facts extracted inherit it as valid_from, so as_of point-in-time queries reflect when things were true, not when they were ingested.

Response

Successful Response

idstring required
contentstring required
user_idstring nullable required
agent_idstring nullable required
run_idstring nullable required
clientstring nullable

The tool that wrote it: the X-Korely-Client header of the write, or the name an MCP client gave when it connected. A label, not a namespace: no read is scoped by it and the agent cap does not count it.

kindstring

note, or session for the log of a work session (kind of the write).

metadataobject required
statusstring

Whether this memory's typed facts are queryable yet: 'processing', 'ready', or 'error'. Extraction runs after the write returns, so a read taken immediately can legitimately find no facts. Poll GET /v1/events or read the memory again: no webhook says that extraction finished (memory.created is sent when the memory is stored, before its facts).

created_atstring nullable required
updated_atstring nullable required
factsobject[]

Changes

No recorded changes to this operation across all 1 revision of this API.