Getting Started - xysq documentation

The xysq Python SDK gives your agents memory over a plain API, no MCP server required. Context lives in vaults, the context graphs your code addresses by id: push what happened, pull the context back, and it’s remembered across sessions. Scope vaults however your product needs (per app, per workload, per customer); each one is walled off from the others.

Installation

pip install git+https://github.com/xysq-ai/sdk_python_xysq.git

Install optional extras for LiteLLM or Anthropic integrations:

pip install 'xysq[agent] @ git+https://github.com/xysq-ai/sdk_python_xysq.git'
pip install 'xysq[claude] @ git+https://github.com/xysq-ai/sdk_python_xysq.git'
pip install 'xysq[all] @ git+https://github.com/xysq-ai/sdk_python_xysq.git'

Requires Python 3.11+

Get an agent key

Mint your agent key at app.xysq.ai/agents/keys. It starts with xysq_.

The agent key is separate from your personal key, and the wall between them is by key class, not by configuration. An agent key reaches agent vaults and can never touch your personal or team memory. That is the whole point: an agent you hand a key to can’t reach into your own memory.Your personal key also works against /sdk, but only on your own personal and team vaults, and it cannot create anything. Creating vaults is agent-key-only.

Add it to a .env file in your project:

XYSQ_API_KEY=xysq_...

Or pass it directly when constructing the client:

from xysq import Xysq

client = Xysq(api_key="xysq_...")

Your first vault

from dotenv import load_dotenv
from xysq import Xysq

load_dotenv()

with Xysq() as client:
    # a vault: a context scope your code addresses by id
    vault = client.vaults.create("Support Bot")

    # push what happened, verbatim (turn by turn -- don't summarize)
    client.vaults.push(
        vault.vault_id,
        "user: what's our refund policy\nagent: 30 days, no questions asked.",
        metadata={"session_id": "conv-1"},
    )

    # pull it back later, ranked
    for hit in client.vaults.pull(vault.vault_id, "refund policy"):
        print(hit.score, hit.content)

Core concepts

The memory surface is on client.vaults:

Method	What it does
`create(name)`	Make a new vault, returns its `vault_id`
`list()`	The vaults this key can see
`push(vault_id, content)`	Send verbatim content; distilled server-side
`pull(vault_id, query)`	Ranked recall from a vault
`rename(vault_id, name)`	Rename a vault
`delete(vault_id)`	Permanently erase a vault
`replace_source(vault_id, source_id, content)`	Rewrite one source under the same id
`delete_source(vault_id, source_id)`	Remove one source and everything it grounded
`declare_meta_key` / `list_meta_keys` / `remove_meta_key`	The vault’s filterable metadata registry
`update_source_meta(vault_id, source_id, set=..., remove=...)`	Set declared metadata on an existing source

There are two more namespaces beside vaults: client.threads for a live conversation’s turns (threads) and client.tags for a project’s tag vocabulary (tags). Two rules make memory good: push verbatim (turn by turn, no summarizing, so the server can extract the details), and group a conversation with a stable metadata={"session_id": "..."} so repeated pushes append to one source. Full detail on the Vaults page.

Source code

The SDK is open source on GitHub: xysq-ai/sdk_python_xysq Includes examples, community contributions, and the full source. Issues and PRs welcome.

What to explore next

Vaults

Full reference for create, list, push, pull, rename, and delete

XysqAgent & Integrations

Memory-aware agent wrapper with configurable context strategies and tool calling

​Installation

​Get an agent key

​Your first vault

​Core concepts

​Source code

​What to explore next

Vaults

XysqAgent & Integrations

Installation

Get an agent key

Your first vault

Core concepts

Source code

What to explore next