Vaults - xysq documentation

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.

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.

vault = client.vaults.create("Support Bot")
print(vault.vault_id)  # "ab59ee2a-..." -- the id every other call needs

Creating vaults requires an agent-class key (the one on 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.

list

The vaults this key can see.

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.

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.

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

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.

client.vaults.delete(vault.vault_id)

delete is irreversible and the personal vault can’t be deleted through the SDK.

Async

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

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.

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"}}'

​create

​list

​push

​pull

​rename

​delete

​Async

​The REST endpoints underneath

create

list

push

pull

rename

delete

Async

The REST endpoints underneath