Memory - xysq documentation

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.

from xysq import Xysq

with Xysq() as client:
    client.memory.capture("...")
    client.memory.surface("...")
    client.memory.synthesize("...")

capture

Store a memory permanently.

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.

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.

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.

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.

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.

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.

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:

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?")

Organise

Upload files; their contents surface through memory automatically

Team Vaults

Scope memory to a shared team vault

​capture

​surface

​synthesize

​list

​delete

​status

​wait

​Async usage

​Related

Organise

Team Vaults

capture

surface

synthesize

list

delete

status

wait

Async usage

Related