Python SDK

Add & Query

add and query are the two methods you will reach for nine times out of ten. This page covers every parameter, every response shape, and the small surprises (skipped writes, optional context, traversal depth) you should know before they bite you in production.

The shape of add(...)

PYTHON

result = client.add(
    text="The launch is on Friday.",     # required
    source="slack",                       # optional label
    tags=["plan", "launch"],              # optional list of strings
    importance=0.8,                       # optional 0..1 hint
    session_id="conv-42",                 # optional, ties to a chat session
    metadata={"channel": "team"},         # optional dict
    end_user_id=None,                     # optional, multi-tenant only
)

Only text is required. Everything else is a hint that helps later recall.

add() returns one of two things

Most calls return a Memory. If the server decided your text contained no high-value content, it returns an AddSkippedResponse with status == "skipped" instead.

PYTHON

from memorysync.types import AddSkippedResponse

result = client.add(text="ok")
if isinstance(result, AddSkippedResponse):
    print("nothing stored:", result.reason)
else:
    print("stored as id", result.id)

The shape of query(...)

PYTHON

hits = client.query(
    "when is launch",          # required
    k=5,                        # how many hits to return
    filters={                   # optional structured filters
        "tags": ["launch"],
        "source": "slack",
    },
    session_id=None,            # optional, scope to one chat session
    traversal_depth=1,          # optional, 1..3 (default 2); follow related memories
)
for m in hits.memories:
    print(m.id, m.text, m.score)

The response is a QueryResponse with memories, optional pre-built context string, server latency_ms, and the session_id the server resolved.

Filters you can pass

Filter key	Type	Effect
tags	list[str]	Match any tag in the list.
source	str	Match an exact source label.
memory_type	str	Restrict to a specific extracted memory type.
since	ISO datetime	Only return memories created at or after this time.
until	ISO datetime	Only return memories created at or before this time.
include_summaries	bool	Whether summary rows are eligible.
tier	"hot" \| "warm" \| "cold"	Restrict to one storage tier.

When to use the prebuilt context string

QueryResponse.context is a single human-readable string the server assembles from the matching memories. It is convenient for passing straight into a prompt; for fine-grained UI you want memories directly so you can format and link them.

Scoping a recall to a chat session

If your application has the concept of a chat or thread, pass the same session_id on add and query. The recall will favour memories from that session over global ones.

PYTHON

session = "conv-42"
client.add(text="user prefers concise replies", session_id=session)
hits = client.query("preferences", k=3, session_id=session)

Common pitfalls

\u201cMy add returned skipped \u2014 why?\u201d

Either the text was empty after trimming, or the gating pass decided it carried no information worth keeping. The result still tells youcandidates_extracted and candidates_stored so you can tell low-value text from a duplicate.

Don\u2019t store huge blobs in metadata. The server bounds payload size.
Don\u2019t chain reads after a write expecting strong consistency at sub-second timescales \u2014 the recall index is eventually consistent.
Do set importance when you know an item matters; the ranker uses it as a soft signal.

← Previous

Install & Auth

Async Usage