memory_read
Search persistent memory for user preferences, past decisions, project setup, people, or earlier context across sessions and AI tools. Use it when answers depend on prior work, not general knowledge.
Instructions
Search long-term memory for user preferences, past decisions, project setup, people, or earlier context. The memory persists across sessions and across every AI tool the user has connected. It applies when an answer may depend on something from an earlier session or another tool; it is not needed for general world knowledge. Returns matches ranked by relevance (or newest-first with order_by: 'recency'); each result carries an id; after the answer, memory_feedback takes these ids to record which memories helped. A correction is a fresh memory_write: it is stored alongside the earlier memory, which is not deleted or hidden, unless it is too close to an existing memory, in which case the write is refused. No MCP deletion tool is exposed; a user can permanently delete an individual personal memory through the REST API or with help from support.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "memory_read"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language description of what you're looking for, e.g. 'database choice for the API' or 'user's preferred testing framework'. | |
| since | No | Only memories created at/after this ISO-8601 instant (naive = UTC) — e.g. your last-seen watermark in a shared room. | |
| top_k | No | Requested number of results (default: 5, what this server asks for when you omit it; the engine's own default of 10 never applies, because the field is always sent). ⚠️ Not a hard cap: association expansion can return MORE than this, and the relevance floor can return fewer — raising it does not reliably widen the result set. For a complete, exactly-bounded listing use memory_list_recent instead. | |
| until | No | Only memories created at/before this ISO-8601 instant. | |
| domain | No | Restrict the search to one domain namespace (e.g. 'project:acme'). Omitting it searches your OWN domains — it does NOT include shared rooms, which are separate stores: to search a room, pass its address here (e.g. 'xroom:room_01ABC'). Find room addresses with memory_list_rooms, or in `rooms_not_searched`, which an answer without `domain` carries when you have rooms. | |
| order_by | No | 'relevance' (default) = ranking order. 'recency' = the matched set re-sorted newest-first. For a complete newest-first feed with no search at all, use memory_list_recent instead. | |
| diversity | No | 0 (default) returns the matches as ranked. Above 0, a match that is a near-copy of one already picked gives its slot to the next distinct memory (maximal marginal relevance); 1 lets similarity alone decide after the first pick. It changes which memories come back, not their scores, and applies only when there are more matches than top_k and top_k is below 200. | |
| exclude_author | No | Drop memories written by this author PRINCIPAL — the server-side identity. ⚠️ NOT USABLE FROM HERE YET: the principal is not shown in these results, so there is no value you can obtain through this tool, and a guess like 'me' silently matches nothing and filters nothing. Only pass it if your system knows the exact principal from elsewhere (e.g. the REST API). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Matching memories, ordered per order_by. | |
| rooms_not_searched | No | Present only on a call WITHOUT `domain`, when you have shared rooms or they could not be checked: rooms are separate stores that call did not search. |