***

title: Quickstart
description: Add your first memory and search it back in under 5 minutes.
-------------------------------------------------------------------------

# Quickstart

Get up and running with the XTrace Memory API. By the end of this guide you'll have stored a memory and retrieved it with a semantic search.

## 1. Get your API key

Sign in at [mem.xtrace.ai](https://app.xtrace.ai) and generate an API key from **Settings → API Keys**, or call:

```bash
curl -X POST https://api.xtrace.ai/v1/auth/generate-xmem-key \
  -H "Authorization: Bearer YOUR_AUTH0_JWT"
```

Copy the returned key — you'll use it as a Bearer token for all API calls.

## 2. Add a memory

Send conversation turns and XTrace extracts beliefs, episodes, and artifacts automatically:

```bash
curl -X POST https://api.xtrace.ai/v1/memories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_alice",
    "messages": [
      { "role": "user", "content": "I just moved to Austin and I prefer dark mode in everything." },
      { "role": "assistant", "content": "Got it! I will remember that." }
    ]
  }'
```

The response contains the extracted memories:

```json
{
  "results": [
    {
      "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
      "event": "ADD",
      "data": { "memory": "User moved to Austin." }
    },
    {
      "id": "mem_02KG9AT5Z1S1TQN24S6S7I43DK",
      "event": "ADD",
      "data": { "memory": "User prefers dark mode in all tools." }
    }
  ]
}
```

## 3. Search memories

Retrieve relevant memories with a natural-language query:

```bash
curl -X POST https://api.xtrace.ai/v1/memories/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_alice",
    "query": "Where does the user live?"
  }'
```

```json
{
  "results": [
    {
      "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
      "memory": "User moved to Austin.",
      "score": 0.94
    }
  ]
}
```

## 4. Update a memory

When things change, update the belief — XTrace re-embeds and propagates:

```bash
curl -X PATCH https://api.xtrace.ai/v1/memories/mem_01JF8ZS4Y0R0SPM13R5R6H32CJ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "memory": "User lives in Austin, TX since March 2026." }'
```

## 5. Delete a memory

```bash
curl -X DELETE https://api.xtrace.ai/v1/memories/mem_01JF8ZS4Y0R0SPM13R5R6H32CJ \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## What's next

* [Core concepts](/docs/memory-types) — understand beliefs, episodes, and artifacts
* [API Reference](/api/overview) — full endpoint documentation