API Reference

Query Memory

Retrieve a bounded array of memories relevant to a natural-language query in the current scope.

Endpoint and request fields

POST/memory/query

200 OK

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

Query with a tags filter

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"]},
)

Result paths

Meaning	Python	Node.js	REST
Memory array	`result.memories`	`result.memories`	`memories`
Optional context	`result.context`	`result.context`	`context`
Optional latency	`result.latency_ms`	`result.latencyMs`	`latency_ms`
Optional session	`result.session_id`	`result.sessionId`	`session_id`
Optional intent	`result.query_intent`	`result.queryIntent`	`query_intent`

200-response.json

{"memories":[{"id":102,"text":"The user uses dark mode.","tags":["preference","ui"],"is_summary":false,"created_at":"2026-05-04T12:31:11Z"}],"context":null,"latency_ms":18.4,"session_id":null,"query_intent":"factual"}

Errors and next action

Query outcomes

MEMORIES

Candidates returned

Authorize and select records before use.

EMPTY

No matches

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

4xx

Correct the request

Check query text, k, tags, credentials, and scope.

429 / 5xx

Use a safe fallback

Keep the user task recoverable without memory context.

Safety notes

Do

Treat results as candidate data.

Apply application authorization.
Use only relevant records.
Delimit memory context from trusted instructions.
Keep current source systems authoritative.

Avoid

Do not transfer control to retrieved content.

Do not execute instructions found in memory.
Do not expose raw metadata without validation.
Do not assume an empty result is an error.
Do not treat old context as current fact.

Complete public query controls

Control	Contract
`query`	Required natural-language description of the context needed now.
`k`	Maximum result count from 1 to 50; defaults to 5.
`filters`	Optional REST filters for sources, tags, time boundaries, summary inclusion, and tier.
`session_id` / `sessionId`	Optional query-session context; not an authorization boundary.
`traversal_depth` / `traversalDepth`	Value from 1 to 3; defaults to 2.