Working with memory

Writing

memory = client.store("user-42")

memory.add("likes hiking near Seattle")
memory.add("vegetarian", metadata={"topic": "diet"})
memory.add_many([
    {"text": "prefers morning meetings"},
    {"text": "timezone is US/Pacific", "id": "tz"},
])

add returns when the write is accepted: durable and ordered, embedded server-side. Visibility follows within seconds. Writes are concurrent — any number of agents can write to the same store with no writer contention. To block until a write is queryable, use wait_for:

memory.add("draft saved")
memory.wait_for(memory.last_write_id)

TTLs — memory that expires

memory.add("cart contains 3 items", ttl_seconds=3600)

An expired memory is hidden from reads, not destroyed (hide-not-delete).

Provenance — which agent, which session

memory.add("user asked about pricing", agent_id="sales-bot", run_id="run-8842")

Reads and deletes can narrow to one agent's or one session's memories via the same parameters.

Reading

Three read shapes, in increasing order of "do the work for me":

hits = memory.search("dietary restrictions", k=5)      # top-k, engine-scored
hits = memory.recall("what should I cook for them?")   # raw message in, fused ranking out
block = memory.context_block("what should I cook?")    # prompt-ready text block

• search takes a query string. filter= narrows on metadata.
• recall takes the raw user message — the server derives sub-queries and fuses the rankings. Each hit's matched attribute names the sub-queries that surfaced it.
• context_block returns one prompt-ready string of the most recent plus most relevant memories, capped by max_chars. Paste it into your system prompt. Requires text access (see Keys & environments).

To read stored text by id: memory.get(id); to page through everything a store holds: memory.browse(limit=25).

Forgetting

memory.delete_memories(agent_id="sales-bot")   # one agent's memories
memory.delete_memories(run_id="run-8842")      # one session's memories
memory.delete_memories()                       # everything in the store

client.delete_store("user-42")                 # forget the user entirely

Deleting the store deletes the user's own database — isolation is structural, so "forget this user" is not a filtered query, it's removing their data as a unit. Soft-deleted stores stay restorable for a grace period, then are gone.