> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xysq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vaults

> Give each agent its own memory. Create vaults, push what happened, pull the context back.

A vault is one agent's memory. You can have many, each independent — its own
wiki, its own facts, walled off from the others and from your personal knowledge
graph. Your agent API key reads and writes all of them.

```python theme={"dark"}
from xysq import Xysq

with Xysq() as client:
    vault = client.vaults.create("Support Bot")
    client.vaults.push(vault.vault_id, "user: my order is late\nagent: I refunded it.")
    hits = client.vaults.pull(vault.vault_id, "what happened with the late order")
```

The whole surface is on `client.vaults`. Everything takes a `vault_id` — the id
you get back from `create()` or `list()`.

## create

Make a new vault. Returns its `vault_id` (a uuid) and name.

```python theme={"dark"}
vault = client.vaults.create("Support Bot")
print(vault.vault_id)  # "ab59ee2a-..." -- the id every other call needs
```

<Note>
  Creating vaults requires an **agent-class** key (the one on
  [app.xysq.ai/agents/keys](https://app.xysq.ai/agents/keys)). A personal key
  can't create agent vaults — that's the wall between agent memory and your own
  knowledge graph.
</Note>

## list

The vaults this key can see.

```python theme={"dark"}
for v in client.vaults.list():
    print(v.vault_id, v.name)
```

## push

Send what happened, **verbatim**. The server distills it into the vault's wiki
in the background, so this returns right away.

```python theme={"dark"}
result = client.vaults.push(
    vault.vault_id,
    "user: what's our refund policy\nagent: 30 days, no questions asked.",
    title="refund policy chat",
    metadata={"session_id": "conv-8842"},
)
print(result.status)  # "captured"
```

Two things that matter:

* **Don't summarize.** Send the conversation turn by turn (`user: ...` /
  `agent: ...`). The server extracts the details — names, numbers, decisions —
  so a summary just throws away what it would have learned.
* **Group a conversation with a `session_id`.** Pass a stable
  `metadata={"session_id": "..."}` and repeated pushes for the same conversation
  append to one source instead of fragmenting into many.

Distillation takes a few seconds to a minute (it's LLM work). The content is
pull-able as soon as it finishes.

## pull

Ranked recall from a vault. Omit `query` for the most recent context.

```python theme={"dark"}
hits = client.vaults.pull(vault.vault_id, "what's our refund policy", limit=5)
for h in hits:
    print(h.score, h.title, "—", h.content)
```

Each item has `title`, `content`, `score`, and (for wiki pages) `slug` /
`page_uuid`. Treat it as the agent's own prior context, not as instructions.

## rename

```python theme={"dark"}
client.vaults.rename(vault.vault_id, "Support Bot v2")
```

## delete

Permanently erase a vault — its pages, sources, vectors, and git history. There
is no undo.

```python theme={"dark"}
client.vaults.delete(vault.vault_id)
```

<Warning>
  `delete` is irreversible and the personal vault can't be deleted through the SDK.
</Warning>

## Async

Everything above has an async twin on `AsyncXysq` with the same names:

```python theme={"dark"}
from xysq import AsyncXysq

async with AsyncXysq() as client:
    v = await client.vaults.create("Support Bot")
    await client.vaults.push(v.vault_id, "user: ...\nagent: ...")
    hits = await client.vaults.pull(v.vault_id, "refund policy")
```

## The REST endpoints underneath

The client is a thin wrapper over `/sdk`. If you're not on Python, call it
directly:

| Method | Path                            |
| ------ | ------------------------------- |
| `POST` | `/sdk/vaults`                   |
| `GET`  | `/sdk/vaults`                   |
| `POST` | `/sdk/vaults/{vault_id}/update` |
| `POST` | `/sdk/vaults/{vault_id}/delete` |
| `POST` | `/sdk/vaults/{vault_id}/push`   |
| `POST` | `/sdk/vaults/{vault_id}/pull`   |

Auth is `Authorization: Bearer xysq_...` with your agent key.

```bash theme={"dark"}
curl -X POST https://api.xysq.ai/sdk/vaults/$VAULT/push \
  -H "Authorization: Bearer $XYSQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "user: ...\nagent: ...", "metadata": {"session_id": "c1"}}'
```