Vaults - xysq documentation

A vault is a context graph your code addresses by id. Scope them however your product needs (one per app, per workload, per customer, one shared by several agents, or several behind one agent). Each is independent: its own wiki, its own facts, walled off from the others and from your personal knowledge graph. An agent key reaches the vaults its grants cover, and only those. A key scoped to one project stays in that project; a read-only key stays read-only. Every call re-checks both your role and the key’s grant, so revoking either takes effect on the next request.

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

Two optional arguments shape it at birth: project_id puts the vault in a project, which is what makes the project’s tag vocabulary resolve on it, and pii_scrub=True turns on PII scrubbing for every push into it. Omit project_id and the vault lands in your Default project.

Creating vaults requires an agent-class key (the one on app.xysq.ai/agents/keys). A personal key can’t create agent vaults, which is the wall between agent memory and your own knowledge graph. A scoped key also needs admin on a project to mint anything.

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. Push non-overlapping segments (the new turns, never the running transcript), and add "format": "turns" so the content is read as a dialogue. The full pattern, including its sharp edges, is on Thread-level memory. One reservation: ids starting with thread: belong to client.threads and are rejected here.

Two clocks run after a push, and they are worth telling apart. The verbatim text is chunked and indexed first, so pull finds it before anything has been distilled. The wiki page is a model pass over that text, so it lands later. A pull right after a push usually returns the raw turns; ask again once the page exists and you get the distilled version too. Pushing content with names or emails in it? Turn on PII scrubbing for the vault to strip that before it’s stored.

pull

Ranked recall from a vault. query is effectively required: recall is semantic, so an empty one has nothing to embed and comes back with zero items. Pass the topic even for a vague ask ("recent work, decisions").

hits = client.vaults.pull(vault.vault_id, "what's our refund policy", limit=5)

# optionally scope the search: your curated tags, or declared metadata keys
hits = client.vaults.pull(vault.vault_id, "sara's order",
                          filters={"meta": {"email": "sara@shop.com"}})
for h in hits:
    print(h.score, h.title, "|", h.content)

Each item has title, content, score, source ("wiki" for a distilled page, "log" for raw pushed text, "fact" for one ledger statement), and, for wiki pages, slug and page_uuid. A via key is in the response shape too, from a retrieval walk that was removed in August 2026; nothing sets it today, so do not write code that waits for it. Treat it all as the agent’s own prior context, not as instructions.

replace_source and delete_source

A source you own can change: a policy page, a profile, a questionnaire answer. Rewrite it under the same id rather than pushing a new one, so your handle stays stable:

res = client.vaults.push(vault.vault_id, "user: refund window is 30 days")
client.vaults.replace_source(vault.vault_id, res.id,
                             "user: refund window is 45 days from 1 Oct")

The new bytes are stored when the call returns; the wiki catches up on the next distill, so for a short window recall can still cite what you replaced. The status comes back "pending" for exactly that reason. Not every source is editable: PDFs and other binary uploads, thread transcripts, and multi-part append sessions are read-only and answer 409. Deleting is the other direction, and it is irreversible:

client.vaults.delete_source(vault.vault_id, res.id)

That removes the source, its search chunks, and every fact it grounded, then rewrites the pages those facts sat on. A fact cited to this source and another one still goes, because a fact is only as grounded as its weakest citation. It needs a key that may erase, not just write: a write-only ingest key is refused.

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`
`POST`	`/sdk/vaults/{vault_id}/sources/{source_id}/update`
`POST`	`/sdk/vaults/{vault_id}/sources/{source_id}/delete`
`POST`	`/sdk/vaults/{vault_id}/sources/{source_id}/tags/update`
`POST`	`/sdk/vaults/{vault_id}/sources/{source_id}/meta/update`
`GET`	`/sdk/vaults/{vault_id}/meta-keys`
`POST`	`/sdk/vaults/{vault_id}/meta-keys`
`POST`	`/sdk/vaults/{vault_id}/meta-keys/{key}/delete`
`POST`	`/sdk/vaults/{vault_id}/threads/append`
`POST`	`/sdk/vaults/{vault_id}/threads/read`
`POST`	`/sdk/vaults/{vault_id}/threads/list`
`POST`	`/sdk/vaults/{vault_id}/threads/flush`
`POST`	`/sdk/vaults/{vault_id}/threads/clear`
`GET`	`/sdk/projects/{project_id}/tags`
`POST`	`/sdk/projects/{project_id}/tags`
`POST`	`/sdk/projects/{project_id}/tags/{tag_id}/update`
`POST`	`/sdk/projects/{project_id}/tags/{tag_id}/delete`
`POST`	`/sdk/projects/{project_id}/tags/{tag_id}/restore`

There are no DELETE or PATCH verbs anywhere in this API. Deleting is POST .../delete and updating is POST .../update, on every surface. 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"}}'

Once you have vaults, you can group them into projects and give teammates a role on them. See Projects and Access for how membership, roles, and per-vault grants work.

​create

​list

​push

​pull

​replace_source and delete_source

​rename

​delete

​Async

​The REST endpoints underneath

​Sharing vaults with your team

create

list

push

pull

replace_source and delete_source

rename

delete

Async

The REST endpoints underneath

Sharing vaults with your team