# Memory and end users

Inside one session, the agent has the whole conversation: it lives in the session's VM. Across sessions it only knows what it chose to remember, and only if the version has `memory_enabled` (`--memory` in the CLI).

## How memory works

- The agent gets four tools: `memory_set`, `memory_get`, `memory_search`, `memory_delete`. It decides what is worth keeping.
- Facts are short key/value pairs: up to 500 per end user per agent, keys up to 128 characters, values up to 4,000.
- At the start of every run, the 50 most recent facts are added to the system prompt, framed as things the agent believes, not as instructions. A user cannot plant a rule in one conversation and have it obeyed in the next.

## End users

If your app serves its own users, pass your id for each one as `end_user_id` on invoke. Memory, usage and erasure are then kept per end user: one user never sees another's facts, and two agents never share them.

Using an agent yourself, with no `end_user_id`? Its memory is one shared bucket, addressed as `-` in the end-user routes (so `-` cannot be a real end user id). Runs started by a schedule or a webhook use this bucket too.

## See, clear and erase

**Python:**

```python
agent.memory("cust-42")                      # [{key, value, updated_at}]
agent.clear_memory("cust-42", key="plan")    # one fact
agent.clear_memory("cust-42")                # everything it remembers
agent.erase_end_user("cust-42")              # sessions, runs, usage, memory, connected accounts

agent.memory("-")                            # runs made without an end user
```

**JavaScript:**

```javascript
await agent.memory("cust-42");
await agent.clearMemory("cust-42", "plan");
await agent.eraseEndUser("cust-42");
```

**cURL:**

```bash
# what it remembers about one end user
curl https://api.orkestr.eu/v1/agents/analyst/end-users/cust-42/memory \
  -H "Authorization: Bearer $ORKESTR_API_KEY"

# erase everything about them (GDPR)
curl -X DELETE https://api.orkestr.eu/v1/agents/analyst/end-users/cust-42 \
  -H "Authorization: Bearer $ORKESTR_API_KEY"
```

Erasing an end user destroys their sessions (VMs and snapshots, so the conversations), and deletes their run records, usage and memory, plus any accounts they connected to your connectors (the result counts them in `connections`). The console's **End users** tab does the same.

> **Tokens**
>
> The end-user routes need `agents:write`.