Skip to main content
The memory namespace is the episodic layer of xysq — it stores captures from conversations, decisions, and preferences, 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
ParameterTypeDefaultDescription
contentstrrequiredThe memory text to store
contextstrNoneFree-text context (session, task, source)
tagslist[str]NoneTags for filtering and organisation
significancestr"normal""low" | "normal" | "high"
scopestr"permanent""permanent" | "session"
document_idstrNoneOmit 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.
metadatadictNoneArbitrary key-value metadata
timestampstrNoneISO 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
ParameterTypeDefaultDescription
querystrrequiredNatural language search query
budgetstr"mid""low" | "mid" | "high" — controls recall depth
typeslist[str]NoneFilter by memory type
intentstrNoneHint about query intent
domainstrNoneDomain scope hint
scopestrNoneScope filter
agent_filterstrNoneFilter 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
ParameterTypeDefaultDescription
querystrrequiredThe question to answer from memory
budgetstr"mid""low" | "mid" | "high"
response_schemadictNoneJSON Schema to shape the response
write_backboolFalseIf 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
ParameterTypeDefaultDescription
limitint20Number of memories to return
agent_filterstrNoneFilter 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
ParameterTypeDescription
document_idstrThe 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
ParameterTypeDefaultDescription
document_idstrrequiredDocument to poll
timeoutfloat30.0Maximum seconds to wait
intervalfloat0.5Poll 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?")

Knowledge Base

Index external sources — they surface through memory automatically

Team Vaults

Scope memory to a shared team vault