Memory RAG — MDDB API

Conversational memory system for RAG — session management, message storage, semantic/hybrid recall, summarization

Create a new memory session #

POST /v1/memory/session

Start a new conversation session for storing and recalling messages.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
userId (required)	string	User identifier
scenario	string	Session context/scenario
title	string	Human-readable title
meta	object
ttl	integer	TTL in seconds (default 30 days)

{
  "scenario": "string",
  "title": "string",
  "ttl": 0,
  "userId": "string"
}

Responses #

Status	Description	Body
200	Session created	object (application/json)
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)
503	Not now: the search concurrency limit is reached, the subsystem is disabled, or a write meets the database while its freelist is rebuilt (#333; the body then adds phase and progress). Retry after Retry-After seconds.	ErrorResponse (application/json)
507	(v2.18.9+) Refused by a collection quota or the disk reserve / vector RAM limit; nothing was written (GO-043)	QuotaExceeded (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

413 example (application/json)

{
  "error": "request body too large"
}

Add a message to a session #

POST /v1/memory/message

Store a message in a memory session. Messages are auto-embedded for semantic recall.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
sessionId (required)	string
role (required)	string	One of "user", "assistant", "system", "tool".
content (required)	string
meta	object

{
  "content": "string",
  "role": "user",
  "sessionId": "string"
}

Responses #

Status	Description	Body
200	Message added	object (application/json)
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)
503	Not now: the search concurrency limit is reached, the subsystem is disabled, or a write meets the database while its freelist is rebuilt (#333; the body then adds phase and progress). Retry after Retry-After seconds.	ErrorResponse (application/json)
507	(v2.18.9+) Refused by a collection quota or the disk reserve / vector RAM limit; nothing was written (GO-043)	QuotaExceeded (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

413 example (application/json)

{
  "error": "request body too large"
}

Recall relevant messages #

POST /v1/memory/recall

Semantically recall relevant messages from past conversations using hybrid search (vector + keyword).

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
query (required)	string
userId	string
sessionId	string
role	string
topK	integer	Default 10.
threshold	number
strategy	string	One of "hybrid", "semantic", "keyword". Default "hybrid".
alpha	number
includeContent	boolean
filterMeta	object

{
  "alpha": 0,
  "includeContent": false,
  "query": "string",
  "role": "string",
  "sessionId": "string",
  "strategy": "hybrid",
  "threshold": 0,
  "topK": 10,
  "userId": "string"
}

Responses #

Status	Description	Body
200	Recall results	object (application/json)
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

413 example (application/json)

{
  "error": "request body too large"
}

Summarize a session #

POST /v1/memory/summarize

Generate and store a summary of a session's conversation.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
sessionId (required)	string
userId	string

{
  "sessionId": "string",
  "userId": "string"
}

Responses #

Status	Description	Body
200	Summary generated	object (application/json)
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)
503	Not now: the search concurrency limit is reached, the subsystem is disabled, or a write meets the database while its freelist is rebuilt (#333; the body then adds phase and progress). Retry after Retry-After seconds.	ErrorResponse (application/json)
507	(v2.18.9+) Refused by a collection quota or the disk reserve / vector RAM limit; nothing was written (GO-043)	QuotaExceeded (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

413 example (application/json)

{
  "error": "request body too large"
}

List memory sessions #

POST /v1/memory/sessions

List sessions with optional user/scenario filtering and pagination.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Content type application/json: object

Property	Type	Description
userId	string
scenario	string
limit	integer	Default 50.
offset	integer
sort	string	One of "createdAt", "updatedAt". Default "createdAt".
asc	boolean

{
  "asc": false,
  "limit": 50,
  "offset": 0,
  "scenario": "string",
  "sort": "createdAt",
  "userId": "string"
}

Responses #

Status	Description	Body
200	Session list	object (application/json)
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

413 example (application/json)

{
  "error": "request body too large"
}

Get session message history #

POST /v1/memory/history

Retrieve chronologically ordered message history for a session.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
sessionId (required)	string
limit	integer	Default 100.
offset	integer

{
  "limit": 100,
  "offset": 0,
  "sessionId": "string"
}

Responses #

Status	Description	Body
200	Message history	object (application/json)
400	The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which.	ErrorResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

400 example (application/json)

{
  "error": "missing collection"
}

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

413 example (application/json)

{
  "error": "request body too large"
}