# memory

> Read, add and delete what your agent remembers about each user.

See and change what Bash remembers about each of your users: their preferences, the people in their life, and things they told it once. You can read what it knows, tell it a new fact, or make it forget.

## TypeScript

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

// Add a fact. Tell Bash something once, and it remembers it.
await traveller.memory.add('Prefers a window seat, and never a red-eye.');

// Search what Bash remembers. Ask a question in plain words.
const { found, text } = await traveller.memory.search('Which seat does she like?');
console.log(found, text);

// List and forget memories. Read the written profile and each memory, newest first. Then forget one, or
// everything.
const all = await traveller.memory.list();
console.log(all.profile?.markdown);
const first = all.data[0];
if (first) await traveller.memory.forget(first.id);
await traveller.memory.forgetAll();
```

## Python

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

# Add a fact. Tell Bash something once, and it remembers it.
traveller.memory.add("Prefers a window seat, and never a red-eye.")

# Search what Bash remembers. Ask a question in plain words.
found = traveller.memory.search("Which seat does she like?")
print(found.found, found.text)

# List and forget memories. Read the written profile and each memory, newest first. Then forget one, or
# everything.
everything = traveller.memory.list()
print(everything.profile)
if everything.data:
    traveller.memory.forget(everything.data[0].id)
traveller.memory.forget_all()
```

## CLI

```bash
# Add a fact. Tell Bash something once, and it remembers it.
vestra memory add "Prefers a window seat, and never a red-eye." --kind preference --user traveller-42

# Search what Bash remembers. Ask a question in plain words.
vestra memory search "Which seat does she like?" --user traveller-42

# List and forget memories. Read the profile and each memory, then forget one, or everything.
vestra memory --user traveller-42
vestra memory forget mem_4kx --user traveller-42
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?" }
  }
}
```

## Good to know

### Listing and searching

`list` returns a written profile and each memory, newest first. `search` answers a question in plain words, and returns `{ found, text }`.

### Forgetting

Forget one memory by its id, or everything Bash knows about a user at once.

### Your company's memory

Leave the user out to read and add to the memory of your company's own Bash, the one that works for your company rather than for a user.

### Showing memory in your app

A session opened with `memory: true` shows your user what Bash remembers about them, and lets them make it forget. Turn this on for your company first, with `PATCH /v1/org` and `memory_panel: true`.

## The routes behind memory

- `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. Key scope: `runtime` (or `all`).
- `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. Key scope: `runtime` (or `all`).
- `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. Key scope: `runtime` (or `all`).
- `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. Key scope: `runtime` (or `all`).
- `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. Key scope: `runtime` (or `all`).

Next: [`embed`](https://vestra.ai/developers/embed.md)