> ## 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.
# Memory
> Capture, surface, synthesize, list, and delete memories from your xysq vault.
The `memory` namespace is the core of the xysq SDK. It stores captures from conversations, decisions, preferences, and external sources, and makes them retrievable across sessions, agents, and time.
```python theme={"dark"}
from xysq import Xysq
with Xysq() as client:
client.memory.capture("...")
client.memory.surface("...")
client.memory.synthesize("...")
```
## capture
Store a memory permanently.
```python theme={"dark"}
result = client.memory.capture(
content="Team decided to use PostgreSQL for the main database",
context="Architecture review — 2026-04-15",
tags=["architecture", "database"],
significance="high",
)
print(result.document_id) # cluster ID — echo on subsequent captures in same topic
print(result.status) # "processing" | "completed"
print(result.applied_tags)
print(result.available_tags)
```
**Parameters**
| Parameter | Type | Default | Description |
| -------------- | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `str` | required | The memory text to store |
| `context` | `str` | `None` | Free-text context (session, task, source) |
| `tags` | `list[str]` | `None` | Tags for filtering and organisation |
| `significance` | `str` | `"normal"` | `"low"` \| `"normal"` \| `"high"` |
| `scope` | `str` | `"permanent"` | `"permanent"` \| `"session"` |
| `document_id` | `str` | `None` | Omit on first capture in a conversation; the server mints and returns one. Echo it on subsequent captures in the same topic to cluster them. Omit again on topic drift to start a fresh document. |
| `metadata` | `dict` | `None` | Arbitrary key-value metadata |
| `timestamp` | `str` | `None` | ISO 8601 timestamp override |
**Returns:** `CaptureResult` — `document_id`, `status`, `applied_tags`, `dropped_tags`, `available_tags`
## surface
Retrieve the most relevant memories for a query. Uses semantic search over your vault.
```python theme={"dark"}
memories = client.memory.surface(
"coding preferences and style",
budget="mid",
)
for m in memories:
print(f"[{m.id}] {m.text}")
print(f" tags: {m.tags}")
print(f" occurred_at: {m.occurred_at}")
```
**Parameters**
| Parameter | Type | Default | Description |
| -------------- | ----------- | -------- | ------------------------------------------------------ |
| `query` | `str` | required | Natural language search query |
| `budget` | `str` | `"mid"` | `"low"` \| `"mid"` \| `"high"` — controls recall depth |
| `types` | `list[str]` | `None` | Filter by memory type |
| `intent` | `str` | `None` | Hint about query intent |
| `domain` | `str` | `None` | Domain scope hint |
| `scope` | `str` | `None` | Scope filter |
| `agent_filter` | `str` | `None` | Filter to a specific agent's captures |
**Returns:** `list[MemoryItem]` — `id`, `text`, `tags`, `metadata`, `occurred_at`
## synthesize
Answer a natural language question from your memory bank. Uses your stored memories as the source of truth.
```python theme={"dark"}
result = client.memory.synthesize(
"What are the team's engineering standards?",
budget="mid",
write_back=False,
)
print(result.answer)
print(result.confidence) # "high" | "medium" | "low"
print(result.sources) # list of memory IDs used
```
**Parameters**
| Parameter | Type | Default | Description |
| ----------------- | ------ | -------- | ---------------------------------------------- |
| `query` | `str` | required | The question to answer from memory |
| `budget` | `str` | `"mid"` | `"low"` \| `"mid"` \| `"high"` |
| `response_schema` | `dict` | `None` | JSON Schema to shape the response |
| `write_back` | `bool` | `False` | If `True`, saves the synthesis as a new memory |
**Returns:** `SynthesizeResult` — `answer`, `confidence`, `sources`
Use `budget="low"` in chatbot loops where latency matters. Use `budget="high"` for one-shot synthesis where comprehensiveness is critical.
## list
List stored memories, most recent first.
```python theme={"dark"}
memories = client.memory.list(limit=20)
for m in memories:
tags_str = ", ".join(m.tags) if m.tags else "none"
print(f"[{m.id}] {m.text[:60]} — tags: {tags_str}")
```
**Parameters**
| Parameter | Type | Default | Description |
| -------------- | ----- | ------- | ------------------------------------- |
| `limit` | `int` | `20` | Number of memories to return |
| `agent_filter` | `str` | `None` | Filter to a specific agent's captures |
**Returns:** `list[MemoryItem]`
## delete
Delete a memory document (the whole cluster, every unit) by ID.
```python theme={"dark"}
client.memory.delete("doc_abc123")
```
**Parameters**
| Parameter | Type | Description |
| ------------- | ----- | -------------------------------------------------------------------------- |
| `document_id` | `str` | The document ID to delete (from a prior capture response or recall result) |
## status
Check the indexing status of a memory document.
```python theme={"dark"}
status = client.memory.status(result.document_id)
print(status.status) # "processing" | "completed" | "failed" | "not_found"
```
## wait
Block until a document reaches a terminal status (completed or failed) or the timeout elapses.
```python theme={"dark"}
final = client.memory.wait(
result.document_id,
timeout=30.0,
interval=0.5,
)
if final.status == "completed":
print("Document is indexed and searchable")
else:
print(f"Failed: {final.error_msg}")
```
Use `wait()` when you need a captured document to be immediately searchable — for example in tests or deterministic pipelines.
**Parameters**
| Parameter | Type | Default | Description |
| ------------- | ------- | -------- | ------------------------ |
| `document_id` | `str` | required | Document to poll |
| `timeout` | `float` | `30.0` | Maximum seconds to wait |
| `interval` | `float` | `0.5` | Poll interval in seconds |
**Returns:** `StatusResult` — `status`, `document_id`, `error_msg`
***
## Async usage
Every method has an async equivalent on `AsyncXysq`:
```python theme={"dark"}
from xysq import AsyncXysq
async with AsyncXysq() as client:
await client.memory.capture("async-captured memory")
memories = await client.memory.surface("async patterns")
result = await client.memory.synthesize("What do I know about async?")
```
***
## Related
Upload files; their contents surface through memory automatically
Scope memory to a shared team vault