Memorax API Developer Documentation

user_id

string · required · at least 1 character

You can define user_id to identify the user who owns these memories. Use a stable business user ID such as demo-user, and use the same value in subsequent Search requests. Account and project permissions are determined by the API key.

messages

Message[] · required for ordinary message writes · default []

Messages to process, in conversation order. Submit a single user message or multiple user and assistant turns. Each item contains role, content, and timestamp. Expand the properties below. Ordinary message writes require at least one item.

Copy[
  {
    "role": "user",
    "content": "Retry a failed callback at most 3 times.",
    "timestamp": -1
  }
]

Copy[
  {
    "type": "input_text",
    "text": "Retry a failed callback at most 3 times."
  }
]

Copy{
  "type": "input_text",
  "text": "Retry a failed callback at most 3 times."
}

Copy{
  "type": "input_image",
  "image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC",
  "detail": "auto",
  "caption": "Sample pixel image"
}

Copy{
  "type": "file",
  "file": {
    "file_data": "data:text/plain;base64,UmV0cnkgdXAgdG8gMyB0aW1lcy4K",
    "filename": "retry-rules.txt"
  }
}

Copy{
  "file_data": "data:text/plain;base64,UmV0cnkgdXAgdG8gMyB0aW1lcy4K",
  "filename": "retry-rules.txt"
}

async_mode

boolean · optional · default true

Control whether the caller waits for processing. true returns HTTP 202 and a task ID, whose result is obtained through the status endpoint. false waits within the request and returns HTTP 200 on completion. Production environments require true. Synchronous writes are available in nonproduction environments that enable them.

mode

string · optional · default default

Select the input processing mode.

content_type

string · optional · default auto · enum code / work / auto / document

Select the content category and its validation and processing flow. Use code for coding conversations. Currently, session_id and metadata.source="memorax-code" are required. The requirement to provide metadata.source is planned to be removed soon; continue sending it until then. Submit documents through supported Responses-style file content parts with the required document content. The entry point determines the document type.

work: For work productivity scenarios.

auto: For mixed scenarios or when the specific scenario is uncertain; the server automatically determines the content type.

memory_output_language

string · optional · default zh · enum zh / en

Set the language of generated memories, zh for Chinese or en for English.

agent_id

string / null · optional · default null · at most 255 characters

Record the source Agent, such as coding-assistant. To restrict Search to that Agent, use an eq condition with the same value in filters. Omission leaves this source identifier unspecified.

app_id

string / null · optional · default null · at most 255 characters

Record the source application, such as desktop-client. A user may use several applications. Restrict Search to one application using an app_id condition in filters.

session_id

string / null · optional. required for code writes · default null · at most 255 characters

Associate the write with a conversation or coding session. Use the same ID across batches in one session, then filter by that session in Search. A session may contain multiple Add requests.

metadata

object / null · optional · default null

Attach source information and other metadata. Code scenarios currently require {"source":"memorax-code"}. The requirement to provide metadata.source is planned to be removed soon; continue sending it until then. Other attributes follow the deployment contract. Supported Search conditions are listed under filters.

Copy{
  "source": "memorax-code"
}

timestamp

integer / null · optional · default null · 13-digit Unix milliseconds or -1

Provide a request-level event time used for event_created_at metadata. This is useful when importing events with their original occurrence time. -1 leaves this event time unspecified. Each messages[] item still requires its own timestamp.

add_only

boolean / null · optional · default null

Control operation decisions after extraction during ordinary memory writes. true skips add/update/delete decisions for summaries and Facts and treats them as additions. With false, omission, or null, operation decisions are performed. This option does not skip extraction or embedding, does not control Bucket updates, and does not apply to raw writes.

code_extraction_instructions

string / null · optional · at most 12,000 characters · only for code + default

Provide guidance for code-memory extraction, such as retaining confirmed compatibility constraints and decision rationale. This field guides extraction, while messages contains the conversation. Whitespace-only input is normalized to null. Supported with code/default.

chunk

object / null · optional · default null · only for code + default

Identify which client-generated chunk this submission represents. The client splits the input and submits each chunk separately. Expand the properties below.

Copy{
  "group_id": "callback-session-001",
  "index": 0,
  "count": 2
}

window_context

object[] · optional · default []

Provide recent conversation context for Bucket topic routing, for example {"role":"user","content":"Continue discussing callback retries"}. Put content to store in messages. The service retains at most the last 50 entries, then removes older entries to meet a 10,000-character content budget. A sole remaining oversized entry is retained.

Copy[
  {
    "role": "user",
    "content": "We just discussed callback retries."
  }
]

user_id

string · required

Specify the user whose memories to retrieve. You can define user_id; use the same value as Add. The API key determines the account and project, and this field selects the memory subject within that authorized scope.

query

string / null · required for ordinary search · at most 1,024 characters

Describe the information to retrieve in natural language, such as callback retry rules. query must contain a non-whitespace character.

mode

string · optional · default fast · enum fast

fast directly retrieves stored memories. Results depend on the query and available memories.

output_mode

string · optional · deployment-defined default; default summary

Select result granularity. summary returns summaries, facts returns individual facts, raw requests original content. Document-only searches (sources=["document"]) default to facts when this field is omitted. See output modes and response structures below.

return_raw_text

boolean · optional · default false

Applies only to output_mode=summary; facts output ignores this parameter. When true, display original text when available. If it is missing, the service attempts to recover it from the original input; if still unavailable, it falls back to the summary and marks raw_text_missing. Returned content is subject to the server size limit, which defaults to 32 MiB. Exceeding the limit produces an error.

sources

string[] / null · optional · default null · 1–2 unique items when provided

Restrict retrieval by source, using dialogue and/or document. For documents only, use ["document"]. Omission uses the service's existing source scope.

Searching uploaded documents: Explicitly set sources: ["document"] to search content produced by file uploads. Document retrieval returns matching chunks: output_mode: "facts" returns original document chunks rather than extracted facts. Using summary, raw, or enabling return_raw_text does not guarantee the complete text of the entire document.

document_ids

string[] / null · optional · 1–100 items when provided

Restrict retrieval to specific documents and also set sources: ["document"]. For uploaded files, use the target file’s files[].parser_id from the task status as its document ID, not the Add task_id. Use the same project and user_id as the upload.

Copy{
  "sources": [
    "document"
  ],
  "document_ids": [
    "22222222-2222-4222-8222-222222222222"
  ]
}

filters

object / null · optional · default null

Filter by source Agent, application, session, memory type, or creation time. Combine supported operators in and and or arrays. Expand the properties below. Only documented filter fields are supported.

Copy{
  "and": [
    {
      "session_id": {
        "eq": "callback-session-001"
      }
    },
    {
      "created_at": {
        "gte": "2026-11-01T00:00:00Z",
        "lt": "2026-12-01T00:00:00Z"
      }
    }
  ]
}

Copy[
  {
    "session_id": {
      "eq": "callback-session-001"
    }
  },
  {
    "created_at": {
      "gte": "2026-11-01T00:00:00Z"
    }
  }
]

Copy{
  "eq": "agent-a"
}

Copy{
  "eq": "demo-app"
}

Copy{
  "eq": "callback-session-001"
}

Copy{
  "in": [
    "preference",
    "constraint"
  ]
}

Copy{
  "gte": "2026-11-01T00:00:00Z",
  "lt": "2026-12-01T00:00:00Z"
}

Copy[
  {
    "agent_id": {
      "eq": "agent-a"
    }
  },
  {
    "agent_id": {
      "eq": "agent-b"
    }
  }
]

Copy{
  "eq": "agent-a"
}

Copy{
  "eq": "demo-app"
}

Copy{
  "eq": "callback-session-001"
}

Copy{
  "in": [
    "preference",
    "constraint"
  ]
}

Copy{
  "gte": "2026-11-01T00:00:00Z",
  "lt": "2026-12-01T00:00:00Z"
}

top_k

integer · optional · default 10 · 1–50

Provide the default candidate count for both dense and sparse retrieval. When neither k_dense nor k_sparse is specified, each uses top_k, yielding up to 2 × top_k candidates across the two channels. This does not cap the final results at top_k. For example, top_k=5 alone requests 5 from each channel, for up to 10 in total.

An explicit k_dense or k_sparse overrides only its own channel; an unspecified channel still uses top_k. The combined candidate limit is the effective k_dense + k_sparse. Deduplication, filtering, available candidates, and subsequent result processing may reduce the actual number returned; a full count is not guaranteed.

k_dense

integer / null · optional · 0–50 · defaults to top_k

Set the dense retrieval candidate count to match similar meanings across different wording. If omitted, this uses top_k. An explicit value overrides only the dense channel and does not change k_sparse. Set 0 to disable dense retrieval. See top_k above for the relationship between the two channels and examples.

k_sparse

integer / null · optional · 0–50 · defaults to top_k

Set the sparse retrieval candidate count for keyword and terminology matches. If omitted, this uses top_k. An explicit value overrides only the sparse channel and does not change k_dense. Set 0 to disable sparse retrieval; for dense-only retrieval, set k_sparse to 0 and keep dense retrieval enabled. See top_k above for count relationships and examples.

min_semantic_similarity

number / null · optional · 0–1 · service threshold when omitted

Set the minimum semantic similarity for dense retrieval before fusion. A higher threshold may reduce irrelevant results and may also exclude useful memories.

window_context

object[] · optional · default []

Provide recent conversation context, including references to earlier discussion.

Copy[
  {
    "role": "user",
    "content": "We just discussed callback retries."
  }
]