Skip to main content
The knowledge namespace indexes external sources into your vault’s structured knowledge layer. Once indexed, sources are automatically included in memory.surface() and memory.synthesize() results — no separate query required. 
from xysq import Xysq

with Xysq() as client:
    client.knowledge.add(type="link", url="https://...")
    client.knowledge.list()
Knowledge sources and memories are linked layers. Sources you index here become part of the same vault your memories live in — everything surfaces together.

​
add

Add a knowledge source for indexing. 
# Index a URL
source = client.knowledge.add(
    type="link",
    url="https://docs.python.org/3/library/typing.html",
    title="Python typing module",
    session_context="Researching type annotation patterns",
)
print(source.source_id)
print(source.status)  # "pending" initially

# Add a code snippet
source = client.knowledge.add(
    type="code",
    content="""\
def retry(fn, max_attempts=3, backoff=1.0):
    for attempt in range(max_attempts):
        try:
            return fn()
        except Exception:
            if attempt == max_attempts - 1:
                raise
            time.sleep(backoff * (2 ** attempt))""",
    title="Retry utility pattern",
    confidence="high",
)

# Add a text quote or decision record
source = client.knowledge.add(
    type="quote",
    content=(
        "ADR-12: All new services must expose /healthz (liveness) "
        "and /readyz (readiness) endpoints. Checks must complete in <200ms."
    ),
    title="ADR-12: Health Check Standards",
    confidence="high",
)
Parameters
ParameterTypeDefaultDescription
typestrrequired"link" | "code" | "quote"
contentstrNoneText content (required for code and quote)
urlstrNoneURL to fetch and index (required for link)
titlestrNoneHuman-readable title
locationstrNoneSource location reference
session_contextstrNoneContext about why this source was added
confidencestr"medium""low" | "medium" | "high"
Returns: KnowledgeSource — source_id, type, title, status, url, location

​
list

List knowledge sources in your vault. 
sources = client.knowledge.list(limit=20, status="indexed")

for s in sources:
    print(f"[{s.source_id}] {s.type}: {s.title or '(no title)'} — {s.status}")
Parameters
ParameterTypeDefaultDescription
limitint20Number of sources to return
offsetint0Pagination offset
statusstrNoneFilter: "pending" | "processing" | "indexed" | "failed"
typestrNoneFilter by source type
Returns: list[KnowledgeSource]

​
status

Check the indexing status of a source. 
status = client.knowledge.status(source.source_id)
print(status.status)  # "pending" | "processing" | "indexed" | "failed"

​
wait

Block until a source finishes indexing (or fails) or the timeout elapses. 
final = client.knowledge.wait(
    source.source_id,
    timeout=60.0,
    interval=1.0,
)

if final.status == "indexed":
    # Source is now searchable via memory.surface() and memory.synthesize()
    memories = client.memory.surface("health check standards")
Use wait() in tests or pipelines where you need the source to be searchable before continuing. Parameters
ParameterTypeDefaultDescription
source_idstrrequiredSource to poll
timeoutfloat30.0Maximum seconds to wait
intervalfloat0.5Poll interval in seconds

​
Full example

import time
from xysq import Xysq

with Xysq() as client:
    # Add sources
    link = client.knowledge.add(
        type="link",
        url="https://docs.python.org/3/library/typing.html",
        title="Python typing module",
    )
    snippet = client.knowledge.add(
        type="code",
        content="from typing import TypeVar\nT = TypeVar('T')",
        title="TypeVar usage",
        confidence="high",
    )

    # Wait for indexing
    client.knowledge.wait(link.source_id, timeout=60.0)
    client.knowledge.wait(snippet.source_id, timeout=60.0)

    # Surface from memory — knowledge sources are included automatically
    memories = client.memory.surface("Python type annotations")
    for m in memories:
        print(m.text[:80])

    # Synthesize from knowledge
    result = client.memory.synthesize("How should I use TypeVar?")
    print(result.answer)

Memory

Memory and knowledge share the same vault — surface and synthesize query both

Knowledge Base feature

Overview of the knowledge base and how indexing works