> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory API

> Store and retrieve key-value memory for agents

# Memory API

Store and retrieve persistent key-value data for your agents. All endpoints require session authentication. GET requests with a specific `agentId` verify ownership; omitting the parameter or passing `all` returns memories across all of your agents.

## Get memory

```http theme={"dark"}
GET /api/memory?agentId=agent_123
```

Retrieve memory for a specific agent, or for all of your agents at once.

### Query parameters

| Parameter | Type   | Required | Description                                                                                                                                              |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentId` | string | No       | ID of the agent. Pass `all` or omit to return memories across all of your agents. When a specific agent ID is provided, an ownership check is performed. |

### Response

When `agentId` is a specific agent ID:

```json theme={"dark"}
{
  "memory": {
    "preferences": { "theme": "dark" },
    "context": "Last conversation was about scheduling"
  },
  "agentId": "agent_123",
  "count": 2,
  "lastUpdated": "2026-03-19T00:00:00Z"
}
```

When `agentId` is `all` or omitted:

```json theme={"dark"}
{
  "memory": {
    "preferences": { "theme": "dark" },
    "context": "Last conversation was about scheduling",
    "other_agent_key": "value from another agent"
  },
  "agentId": null,
  "count": 3,
  "lastUpdated": "2026-03-19T00:00:00Z"
}
```

### Errors

| Code | Description                                                  |
| ---- | ------------------------------------------------------------ |
| 401  | Unauthorized                                                 |
| 404  | Agent not found (only when a specific `agentId` is provided) |
| 500  | Failed to fetch memory                                       |

## Store memory (single key)

```http theme={"dark"}
POST /api/memory
```

Write a single key-value pair to agent memory.

### Request body

| Field     | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `agentId` | string | Yes      | ID of the agent             |
| `key`     | string | Yes      | Memory key                  |
| `memory`  | any    | Yes      | Value to store (max 100 KB) |

### Response

```json theme={"dark"}
{
  "success": true,
  "agentId": "agent_123",
  "key": "preferences",
  "saved": "2026-03-19T00:00:00Z"
}
```

### Errors

| Code | Description                                                               |
| ---- | ------------------------------------------------------------------------- |
| 400  | `agentId` required, memory data required, or value too large (max 100 KB) |
| 401  | Unauthorized                                                              |
| 404  | Agent not found                                                           |
| 500  | Failed to save memory                                                     |

## Store memory (bulk)

```http theme={"dark"}
POST /api/memory
```

Write multiple key-value pairs in a single request.

### Request body

| Field     | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| `agentId` | string | Yes      | ID of the agent                                  |
| `memory`  | object | Yes      | Object of key-value pairs to store (max 50 keys) |

```json theme={"dark"}
{
  "agentId": "agent_123",
  "memory": {
    "preferences": { "theme": "dark" },
    "context": "Scheduling discussion"
  }
}
```

### Response

```json theme={"dark"}
{
  "success": true,
  "agentId": "agent_123",
  "keysUpdated": 2,
  "saved": "2026-03-19T00:00:00Z"
}
```

### Errors

| Code | Description                                                         |
| ---- | ------------------------------------------------------------------- |
| 400  | `agentId` required, memory data required, or too many keys (max 50) |
| 401  | Unauthorized                                                        |
| 404  | Agent not found                                                     |
| 500  | Failed to save memory                                               |