Search long-term memory for facts matching a natural-language query.

Use this before asking the user to repeat themselves. Searches fact content (keyword and, when a retrieval index exists, ranked matching) and returns the best matches with their category and confidence.

Load the user's memory as text ready to put in your context.

Call this once near the start of a task. The returned context string is the backend's own injection format and should be treated as opaque text -- prepend it to the conversation rather than parsing it.

Return the complete stored memory document for a user.

Prefer memory_search or memory_context for normal use; this returns everything (summaries plus the full fact list) and is intended for inspection, export or debugging.

Store one durable fact about the user.

Use this when the user states a preference, corrects you, or shares context worth carrying into future sessions. Do NOT use it for transient details of the current task, and do not re-save something you already saved -- an identical fact is detected and returned as status="duplicate" instead of being stored twice.

Hand a conversation to the backend to extract facts from automatically.

This is the hands-off write path: instead of deciding fact-by-fact what to save, send the turns and let the backend's LLM extraction decide. Requires an LLM to be configured on the server; without one this returns an error rather than silently storing nothing.

Edit an existing fact by id; omitted fields keep their value.

Use this instead of saving a new fact when something changed -- for example when the user switches tooling. Get the fact_id from memory_search first.

Delete a single fact by id.

Use when the user says a stored fact is wrong or no longer applies.

Erase stored memory for a user (or for one agent bucket).

This is destructive and irreversible. Pending extractions for the same scope are cancelled as part of the call, so a queued update cannot resurrect the memory afterwards. Use it when the user asks to be forgotten, not to tidy up individual facts -- use memory_delete_fact for that.

Force pending memory extractions to run now, within a time budget.

Useful before shutting down, or when a client wants the memory written before it reports success.

Report the memory backend's configuration and health.

Use to check whether a model is configured (extraction needs one), where data is stored, and which identity the defaults resolve to.