# Memory API

> What Bash remembers about each user: read it, search it, add to it, forget it.

Send `Authorization: Bearer vk_test_...` on every call.

## `GET /v1/memory`

Its own page: [GET /v1/memory](https://vestra.ai/developers/reference/api/memory/get-v1-memory.md)

What Bash remembers about one user (user_id), or the company's own Bash: the profile and the memories, newest first.

Your API key, or a session's token, scope `runtime` or `all`. On the card: [`memory`](https://vestra.ai/developers/memory.md). Every call here is a checked sample.

### Request

Query:

- `limit` (`integer`): How many items per page, 1 to 100. Default 20.
- `cursor` (`string`): Where to go on from: the `next_cursor` of the page before, unchanged. Absent: the first page.
- `user_id` (`string`): Whose memory, by your id for them. Absent: your company's own Bash's.

### Answers 200

- `profile` (`object | null`): What Bash knows about the user, written up as one profile; null until it has one.
  - `markdown` (`string`): The profile, as Markdown.
  - `updated_at` (`string | null`): When it last changed, as an ISO 8601 time; null when unknown.
- `data` (`object[]`): The memories, one page of them.
  - `id` (`string`): The memory (mem_...).
  - `text` (`string`): What Bash remembers, in plain words. Example: `Prefers a window seat.`.
  - `kind` (`string`): What kind of fact it is, such as preference or identity.
  - `source` (`string`): How Bash learned it: user_direct (you or your user said so), tool_observed (seen in an app), upload, screen, or agent_inferred (worked out from the conversation).
  - `observed_at` (`string`): When Bash learned it, as an ISO 8601 time.
- `next_cursor` (`string | null`): Send it as cursor for the next page; null on the last.

### Code

**TypeScript**

```ts
const memory = await vestra.user('traveller-42').memory.list();
```

**Python**

```python
memory = vestra.user("traveller-42").memory.list()
```

**CLI**

```bash
vestra memory --user traveller-42
```

**HTTP**

```bash
# Add a fact. Tell Bash something once, and it remembers it.
curl "$VESTRA_BASE_URL/v1/memory" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "text": "Prefers a window seat, and never a red-eye." }'

# Search what Bash remembers. Ask a question in plain words.
curl "$VESTRA_BASE_URL/v1/memory/search?user_id=traveller-42&q=Which%20seat%20does%20she%20like" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# List and forget memories. Read the profile and every memory, newest first. Then forget one, or everything.
curl "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory/mem_4ka?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": { "user": "traveller-42", "q": "Which seat does she like?" }
  }
}
```

## `POST /v1/memory`

Its own page: [POST /v1/memory](https://vestra.ai/developers/reference/api/memory/post-v1-memory.md)

Tell Bash a fact once, for example 'prefers window seats', for one user (user_id) or the company's own Bash.

Your API key, scope `runtime` or `all`. On the card: [`memory`](https://vestra.ai/developers/memory.md). Every call here is a checked sample.

### Request

Headers:

- `Idempotency-Key` (`string`): Send the same key to retry this call safely for 24 hours.

Body:

- `user_id` (`string`): Whose memory, by your id for them. Absent: your company's own Bash's. Example: `traveller-42`.
- `text` (`string`, required): The fact, in plain words: at most 1,000 characters. Limits: 1 to 1000 characters. Example: `Prefers a window seat.`.
- `kind` (`"identity" | "relationship" | "commitment" | "preference" | "project_state" | "other"`): What kind of fact it is: who they are (identity), who they know (relationship), what they promised (commitment), what they like (preference), where a piece of work stands (project_state), or other. Default: `other`.

### Answers 201

- `id` (`string`): The memory (mem_...).
- `text` (`string`): What Bash remembers, in plain words. Example: `Prefers a window seat.`.
- `kind` (`string`): What kind of fact it is, such as preference or identity.
- `source` (`string`): How Bash learned it: user_direct (you or your user said so), tool_observed (seen in an app), upload, screen, or agent_inferred (worked out from the conversation).
- `observed_at` (`string`): When Bash learned it, as an ISO 8601 time.

### Code

**TypeScript**

```ts
await vestra.user('traveller-42').memory.add('Prefers a window seat.');
```

**Python**

```python
vestra.user("traveller-42").memory.add("Prefers a window seat.")
```

**CLI**

```bash
vestra memory add "Prefers a window seat." --user traveller-42
```

**HTTP**

```bash
# Add a fact. Tell Bash something once, and it remembers it.
curl "$VESTRA_BASE_URL/v1/memory" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "text": "Prefers a window seat, and never a red-eye." }'

# Search what Bash remembers. Ask a question in plain words.
curl "$VESTRA_BASE_URL/v1/memory/search?user_id=traveller-42&q=Which%20seat%20does%20she%20like" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# List and forget memories. Read the profile and every memory, newest first. Then forget one, or everything.
curl "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory/mem_4ka?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": { "user": "traveller-42", "q": "Which seat does she like?" }
  }
}
```

## `DELETE /v1/memory`

Its own page: [DELETE /v1/memory](https://vestra.ai/developers/reference/api/memory/delete-v1-memory.md)

Forget everything about one user (user_id), or the company's own Bash.

Your API key, or a session's token, scope `runtime` or `all`. On the card: [`memory`](https://vestra.ai/developers/memory.md). Every call here is a checked sample.

### Request

Query:

- `user_id` (`string`): Whose memory, by your id for them. Absent: your company's own Bash's.

### Answers 200

- `user_id` (`string | null`): Whose memory it was, by your id for them; null for your company's own Bash.
- `deleted` (`true`): Always true: Bash no longer remembers any of it.
- `memories_deleted` (`integer`): How many memories were forgotten.

### Code

**TypeScript**

```ts
await vestra.user('traveller-42').memory.forgetAll();
```

**Python**

```python
vestra.user("traveller-42").memory.forget_all()
```

**CLI**

```bash
vestra memory forget --all --user traveller-42 --yes
```

**HTTP**

```bash
# Add a fact. Tell Bash something once, and it remembers it.
curl "$VESTRA_BASE_URL/v1/memory" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "text": "Prefers a window seat, and never a red-eye." }'

# Search what Bash remembers. Ask a question in plain words.
curl "$VESTRA_BASE_URL/v1/memory/search?user_id=traveller-42&q=Which%20seat%20does%20she%20like" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# List and forget memories. Read the profile and every memory, newest first. Then forget one, or everything.
curl "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory/mem_4ka?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": { "user": "traveller-42", "q": "Which seat does she like?" }
  }
}
```

## `GET /v1/memory/search`

Its own page: [GET /v1/memory/search](https://vestra.ai/developers/reference/api/memory/get-v1-memory-search.md)

Ask the memory a question (q), for one user (user_id) or the company's own Bash.

Your API key, scope `runtime` or `all`. On the card: [`memory`](https://vestra.ai/developers/memory.md). Every call here is a checked sample.

### Request

Query:

- `user_id` (`string`): Whose memory, by your id for them. Absent: your company's own Bash's.
- `q` (`string`, required): What to ask the memory, in at most 500 characters.

### Answers 200

- `query` (`string`): What you asked.
- `found` (`boolean`): Whether the memory had an answer.
- `text` (`string | null`): The answer, in plain words; null when nothing was found.

### Code

**TypeScript**

```ts
const found = await vestra.user('traveller-42').memory.search('Which seat does she like?');
```

**Python**

```python
found = vestra.user("traveller-42").memory.search("Which seat does she like?")
```

**CLI**

```bash
vestra memory search "Which seat does she like?" --user traveller-42
```

**HTTP**

```bash
# Add a fact. Tell Bash something once, and it remembers it.
curl "$VESTRA_BASE_URL/v1/memory" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "text": "Prefers a window seat, and never a red-eye." }'

# Search what Bash remembers. Ask a question in plain words.
curl "$VESTRA_BASE_URL/v1/memory/search?user_id=traveller-42&q=Which%20seat%20does%20she%20like" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# List and forget memories. Read the profile and every memory, newest first. Then forget one, or everything.
curl "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory/mem_4ka?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": { "user": "traveller-42", "q": "Which seat does she like?" }
  }
}
```

## `DELETE /v1/memory/{memory_id}`

Its own page: [DELETE /v1/memory/{memory_id}](https://vestra.ai/developers/reference/api/memory/delete-v1-memory-memory-id.md)

Forget one thing. user_id names whose memory it is.

Your API key, or a session's token, scope `runtime` or `all`. On the card: [`memory`](https://vestra.ai/developers/memory.md). Every call here is a checked sample.

### Request

Path:

- `memory_id` (`string`, required): The memory's id (`mem_...`).

Query:

- `user_id` (`string`): Whose memory, by your id for them. Absent: your company's own Bash's.

### Answers 200

- `id` (`string`): The memory (mem_...).
- `deleted` (`true`): Always true: Bash no longer remembers it.

### Code

**TypeScript**

```ts
await vestra.user('traveller-42').memory.forget('mem_4ka');
```

**Python**

```python
vestra.user("traveller-42").memory.forget("mem_4ka")
```

**CLI**

```bash
vestra memory forget mem_4ka --user traveller-42
```

**HTTP**

```bash
# Add a fact. Tell Bash something once, and it remembers it.
curl "$VESTRA_BASE_URL/v1/memory" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "text": "Prefers a window seat, and never a red-eye." }'

# Search what Bash remembers. Ask a question in plain words.
curl "$VESTRA_BASE_URL/v1/memory/search?user_id=traveller-42&q=Which%20seat%20does%20she%20like" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# List and forget memories. Read the profile and every memory, newest first. Then forget one, or everything.
curl "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory/mem_4ka?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

curl -X DELETE "$VESTRA_BASE_URL/v1/memory?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": { "user": "traveller-42", "q": "Which seat does she like?" }
  }
}
```