Skip to main content
Endpoints

Memory API Endpoints

VoltAgent exposes memory endpoints under /api/memory/* for managing conversations, messages, working memory, and semantic search results.

Auth: Protected by default (see Authentication).

Common Parameters​

  • agentId (query/body): Optional. Required when multiple agents are registered or no global memory is configured.
  • resourceId (query/body): Optional. Defaults to the agent ID when agentId is provided.
  • userId (query/body): Required for creating conversations and saving/deleting messages.
  • conversationId (path/body): Conversation identifier. It can be generated by the server if omitted when creating a conversation.

List Conversations​

Endpoint: GET /api/memory/conversations

Query Parameters: agentId, resourceId, userId, limit, offset, orderBy, orderDirection

curl "http://localhost:3141/api/memory/conversations?userId=user-123&limit=20"

Response​

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "conv-001",
        "resourceId": "assistant",
        "userId": "user-123",
        "title": "Support Chat",
        "metadata": {},
        "createdAt": "2025-01-01T12:00:00.000Z",
        "updatedAt": "2025-01-01T12:05:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Get Conversation​

Endpoint: GET /api/memory/conversations/:conversationId

curl "http://localhost:3141/api/memory/conversations/conv-001"

Create Conversation​

Endpoint: POST /api/memory/conversations

Request Body​

{
  "userId": "user-123",
  "resourceId": "assistant",
  "title": "New Chat",
  "metadata": { "source": "web" }
}

Update Conversation​

Endpoint: PATCH /api/memory/conversations/:conversationId

Request Body​

{
  "title": "Updated Title",
  "metadata": { "priority": "high" }
}

Delete Conversation​

Endpoint: DELETE /api/memory/conversations/:conversationId

curl -X DELETE "http://localhost:3141/api/memory/conversations/conv-001"

Clone Conversation​

Endpoint: POST /api/memory/conversations/:conversationId/clone

Request Body​

{
  "newConversationId": "conv-002",
  "title": "Clone of Support Chat",
  "includeMessages": true
}

List Messages​

Endpoint: GET /api/memory/conversations/:conversationId/messages

Query Parameters: agentId, limit, before, after, roles, userId

curl "http://localhost:3141/api/memory/conversations/conv-001/messages?limit=50"

Notes:

  • roles accepts a comma-separated list (e.g. user,assistant,tool).
  • before and after expect ISO 8601 timestamps.

Save Messages​

Endpoint: POST /api/memory/save-messages

Request Body​

{
  "userId": "user-123",
  "conversationId": "conv-001",
  "messages": [
    {
      "role": "user",
      "content": "Hi there"
    },
    {
      "message": {
        "role": "assistant",
        "content": "Hello!"
      }
    }
  ]
}

Notes:

  • Each message must include userId and conversationId, either on the message entry or in the request body.
  • Message IDs are generated when omitted.

Delete Messages​

Endpoint: POST /api/memory/messages/delete

Request Body​

{
  "userId": "user-123",
  "conversationId": "conv-001",
  "messageIds": ["msg-1", "msg-2"]
}

Get Working Memory​

Endpoint: GET /api/memory/conversations/:conversationId/working-memory

Query Parameters: agentId, scope, userId

curl "http://localhost:3141/api/memory/conversations/conv-001/working-memory?scope=conversation"

Notes:

  • scope=user requires userId in the query.

Update Working Memory​

Endpoint: POST /api/memory/conversations/:conversationId/working-memory

Request Body​

{
  "content": "Customer prefers email follow-ups.",
  "mode": "append"
}

Notes:

  • userId is optional, but if provided it must match the conversation owner.
  • content can be a string or a JSON object when working memory is schema-based.

Search Memory​

Endpoint: GET /api/memory/search

Query Parameters: searchQuery, conversationId, userId, limit, threshold, agentId

curl "http://localhost:3141/api/memory/search?searchQuery=refund%20policy&limit=5"

Notes:

  • Requires embedding and vector adapters; otherwise the endpoint returns 400.

Table of Contents