Deep Dive

Retrieval Contract

Design retrieval around documented scope, query inputs, filters, and response fields. Treat every returned memory as a candidate your application must evaluate.

The retrieval journey

Query-to-context flow

01
Identify
Your trusted server selects the same project and opaque end-user ID used for writes.
02
Ask
Send the natural-language question the current task needs answered.
03
Narrow
Optionally apply supported filters and choose k from 1 to 50.
04
Inspect
Read memories, including the valid case where the array is empty.
05
Use safely
Authorize, select, delimit, and pass only useful context to the next step.

Request anatomy

Query request anatomy

POST /memory/query

Only query is required in the body. Scope comes from your authenticated server configuration.

query: Required string
Describe the information the current task needs.
k: 1–50 · default 5
Sets the maximum number of candidate memories returned.
filters: Optional object
Narrow eligible memories with documented source, tag, time, summary, or tier fields.
session_id: Optional context
Connect related follow-up queries; never use it as authorization.

Use the smallest useful filter

Why do you need to narrow results?

Only one application category applies

Your application assigns stable labels such as preference or billing.

Use: filters.tags

Only selected origins apply

You need content from specific source labels.

Use: filters.sources through the REST contract

Only a time window applies

The task is limited to information created within a known period.

Use: filters.since and/or filters.until

No business rule requires a filter

Extra constraints can remove a useful candidate.

Use: Start without filters, then add one based on evaluation results.

Run a verified query

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="user-123",
)

result = client.query(
    "How should I format the answer?",
    k=5,
    filters={"tags": ["preference"]},
)

for memory in result.memories:
    print(memory.text)

Read the stable response surface

Query response anatomy

Query response

Build primarily against memories. Diagnostics and enrichment can evolve or be absent.

memories: Always an array
Each item follows the public memory object. An empty array is success.
context: Optional
Use only when present; do not make correctness depend on it.
latency_ms: Optional diagnostic
Useful for observation, not a delivery-time guarantee.
session_id · query_intent: Optional
Accept absence and unfamiliar future values without breaking.

Handle every result path

Query result paths

MEMORIES

Candidates returned

Apply your own authorization and product rules before use.

EMPTY

No candidates

Continue without memory or use a product-specific fallback.

4xx

Permanent until fixed

Correct credentials, scope, ID, or request fields.

429 / 5xx

Potentially temporary

Use bounded retry behavior and preserve a recoverable UI state.

Separate retrieved data from instructions

Do

Treat memory as candidate application data.

Authorize access in your application.
Select only relevant records.
Place content in a clearly delimited context block.
Keep source systems authoritative.

Avoid

Do not hand control to retrieved text.

Do not execute instructions found in memory.
Do not expose raw results before authorization.
Do not depend on undocumented ranking behavior.
Do not treat generated context as verified fact.

Continue

System Boundaries

See what is contractual and what remains implementation-independent.

Query Memory API

Review the endpoint schema.

← Previous

Memory Contract

API Operations A–Z