API Reference

Query Filters & Result Windows

Memory queries use a bounded k and optional filters instead of list-style page controls. Export is a separate operation that returns one scoped bundle.

Query controls

Field	Type	Contract
`query`	string	Required natural-language query.
`k`	integer	1–50; defaults to 5.
`filters.tags`	string[]	Restrict results to matching application tags.
`session_id` / `sessionId`	string	Optional query session identifier.
`traversal_depth` / `traversalDepth`	integer	Optional value from 1 to 3; defaults to 2.

Filter by tags

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="usr_7f3a9c2e",
)

result = client.query(
    "What interface preferences are known?",
    k=5,
    filters={"tags": ["preference", "ui"]},
)

Read the result window

Query result paths

MEMORIES

One or more matches

Read the memories array and apply application authorization before use.

EMPTY

No matches

An empty memories array is valid; continue without memory or use a product fallback.

4xx

Invalid filter or scope

Correct the query, k, tags, credentials, or scope.

200-response.json

{"memories":[],"context":null,"latency_ms":18.4,"session_id":null,"query_intent":null}

Filter safely

REST query filter catalog

Filter	Type	Purpose
`filters.sources`	string[]	Restrict candidates to selected application source labels.
`filters.tags`	string[]	Restrict candidates using application-defined tags.
`filters.since`	date-time	Set the inclusive lower time boundary.
`filters.until`	date-time	Set the upper time boundary.
`filters.include_summaries`	boolean	Include summary records; defaults to true.
`filters.tier`	`hot`, `warm`, or `cold`	Restrict candidates to a supported tier value.

Choose the right result strategy

What result does your application need?

A small relevant context set

The current task needs a few candidate memories.

Use: Use Query with k from 1 to 50 and optional filters.

One known record

Your application already has the integer memory ID.

Use: Use Get instead of querying.

A complete principal export

The workflow needs the authenticated principal’s available bundle.

Use: Use Export; query window controls do not apply.

Consume a query window safely

Treat the returned array as candidates rather than an authorization decision.
Handle zero matches without converting the result into an application error.
Select only the records needed for the current task.
Delimit selected memory as untrusted context when passing it to a model.
Evaluate representative questions and expected facts before changing k or filters.

Query Memory

See the complete query contract.

Export Memory

Export the current scoped bundle.

Memory API

Compare every memory operation.

Was this page helpful?

← Previous

Rate Limits & Errors

Memory API Overview