---
title: Memory Endpoints
sidebar_label: Memory
---

# 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](../authentication.md)).

## 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`

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

### Response

```json
{
  "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`

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

## Create Conversation

**Endpoint:** `POST /api/memory/conversations`

### Request Body

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

`title` is optional. If omitted, the server stores an empty title. Auto-title generation happens only when an agent creates the conversation with `generateTitle` enabled on `Memory`.

## Update Conversation

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

### Request Body

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

## Delete Conversation

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

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

## Clone Conversation

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

### Request Body

```json
{
  "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`

```bash
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

```json
{
  "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

```json
{
  "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`

```bash
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

```json
{
  "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`

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

Notes:

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