---
title: "Replace or append to an AI Agent's Memory (v2)"
method: POST
path: "/v2/agents/{idOrAddress}/soul"
tags: ["Agents"]
---

# Replace or append to an AI Agent's Memory (v2)

`POST /v2/agents/{idOrAddress}/soul`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v2/agents/{idOrAddress}/soul`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Edits `soulMd`, the agent's long-lived notes, shown as "Memory" in the
admin UI. `soulMd` replaces the whole text; `append` adds a line to the
end. Send one of them (if both are sent, `soulMd` wins). Running bots
of this agent get the new text straight away.

Owner only. Supports `User JWT` and `B2B Server JWT`.

## Path parameters

- `idOrAddress` string, required

## Request body

- object
  - `soulMd` string: New Memory text (replaces the current one; "" clears it).
  - `append` string: Text added at the end, on a new line.

## Response `200`

```
{ ok: true, agent: Agent }   // soulMdUpdatedBy: 'operator'
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: ``` { error: 'Forbidden', code: 'FORBIDDEN' } ```
- `404`: ``` { error: 'Agent not found', code: 'AGENT_NOT_FOUND' } ```
- `422`: Neither `soulMd` nor `append` given. ``` { error: string, code: 'VALIDATION_ERROR' } ```
- `500`: Internal Server Error

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)