> ## 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.

# Getting Started

> Install the xysq Python SDK and start adding persistent memory to your AI agents in minutes.

The xysq Python SDK gives you direct API access to your memory vault — no MCP server required. Capture memories (including links, code snippets, and quoted passages — all tagged for source), surface relevant context, and build agents that remember across sessions.

## Installation

```bash theme={"dark"}
pip install git+https://github.com/xysq-ai/sdk_python_xysq.git
```

Install optional extras for LiteLLM or Anthropic integrations:

```bash theme={"dark"}
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 API key

Get your API key at [app.xysq.ai/connect](https://app.xysq.ai/connect). It starts with `xysq_`.

Add it to a `.env` file in your project:

```
XYSQ_API_KEY=xysq_...
```

Or pass it directly when constructing the client:

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

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

## Your first memory

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

load_dotenv()

with Xysq() as client:
    # Store a memory
    client.memory.capture(
        content="User prefers type hints in all Python code",
        tags=["coding-style", "python"],
    )

    # Retrieve relevant memories
    memories = client.memory.surface("Python coding preferences")
    for m in memories:
        print(m.text)

    # Ask a question answered from memory
    result = client.memory.synthesize("What are the user's coding preferences?")
    print(result.answer)
```

## Core concepts

The SDK exposes two namespaces on every client:

| Namespace         | Purpose                                                                                                                |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `client.memory`   | All persistent memory — conversational facts, decisions, preferences, plus source-tagged links / quotes / code / chats |
| `client.organise` | Folders + uploaded files (PDFs, images, long documents)                                                                |

The three core memory operations:

| Method              | What it does                                             |
| ------------------- | -------------------------------------------------------- |
| `capture(content)`  | Store a memory permanently                               |
| `surface(query)`    | Retrieve the most relevant memories for a query          |
| `synthesize(query)` | Answer a natural language question from your memory bank |

For external sources (URLs, quotes, code snippets, chat transcripts), use `capture()` with `tags=["source:knowledge", "source_type:link"]` (or `quote`/`code`/`chat`) and put type-specific fields (`url`, `title`, `location`, `language`) in `metadata`. They surface alongside regular memories in `surface()` and `synthesize()`.

## Source code

The SDK is open source on GitHub: **[xysq-ai/sdk\_python\_xysq](https://github.com/xysq-ai/sdk_python_xysq)**

Includes examples, community contributions, and the full source. Issues and PRs welcome.

## What to explore next

<CardGroup cols={2}>
  <Card title="Memory operations" icon="brain" href="/sdk/memory">
    Full reference for capture, surface, synthesize, list, delete, and status
  </Card>

  <Card title="Organise — folders & files" icon="folder-open" href="/sdk/organise">
    Upload PDFs, images, and long documents into a browsable folder tree
  </Card>

  <Card title="Team Vaults" icon="users" href="/sdk/teams">
    Share memory across your entire team
  </Card>

  <Card title="XysqAgent & Integrations" icon="robot" href="/sdk/agent">
    Memory-aware agent wrapper with configurable context strategies and tool calling
  </Card>
</CardGroup>