How It Works

Retrieve Memory

Ask for the context needed by the current task. MemorySync returns candidate memories from the same project and end-user scope for your application to inspect and use.

What happens from your application’s view

Retrieval flow

1Scope
Send the same project and end-user identifiers used for writes.
2Query
Describe the context needed by the current task.
3Filter
Optionally narrow eligible memories.
4Review
Authorize and select returned candidates before use.

Query with a supported 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="user-123",
)

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

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

Control eligible results

Input	Use
`k`	Maximum results to return, from 1 to 50.
`filters.tags`	Limit retrieval to selected application labels.
`filters.since` / `filters.until`	Limit eligible memories to a time range.
`filters.include_summaries`	Include or exclude summary records.
`filters.tier`	Select `hot`, `warm`, or `cold` when your product requires it.
`session_id`	Carry optional follow-up context; it is not an authorization boundary.

Handle the response as candidates

response.json

{
  "memories": [
    {
      "id": 123,
      "text": "The user prefers concise answers and dark mode.",
      "source": "profile",
      "tags": ["preference", "ui"],
      "is_summary": false,
      "created_at": "2026-07-31T12:00:00Z"
    }
  ],
  "latency_ms": 42.8
}

The stable SDK response includes memories and may include context, latency, session, or query-intent values. Treat optional fields as optional.

Use retrieved memory safely

1
Check the result set
An empty memories array is a successful result. Continue without memory or use a product-specific fallback.
2
Authorize and select
Apply your own object-level rules and keep only records that are useful for the current task.
3
Separate data from instructions
Place memory in a clearly delimited context block. Treat retrieved text as untrusted data, not as system instructions.
4
Generate or render
Send the selected context to your model or present it through your application’s normal user experience.

When expected memory is missing

Confirm add and query use the same project and end-user identifiers.
Remove filters one at a time to find an over-restrictive value.
Confirm the add result was created rather than skipped.
Test with representative wording; do not depend on exact ranking formulas or score thresholds.

Retrieval & Filters

Learn the query contract in more detail.

Query Memory API

Review request and response fields.

← Previous

Add Memory

Processing & Availability