Get started

Quickstart

View as Markdown

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 and generate an API key from Settings → API Keys, or call:

$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:

$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:

1{
2  "results": [
3    {
4      "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
5      "event": "ADD",
6      "data": { "memory": "User moved to Austin." }
7    },
8    {
9      "id": "mem_02KG9AT5Z1S1TQN24S6S7I43DK",
10      "event": "ADD",
11      "data": { "memory": "User prefers dark mode in all tools." }
12    }
13  ]
14}

3. Search memories

Retrieve relevant memories with a natural-language query:

$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?"
>  }'
1{
2  "results": [
3    {
4      "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
5      "memory": "User moved to Austin.",
6      "score": 0.94
7    }
8  ]
9}

4. Update a memory

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

$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

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

What’s next