Search memories
amber_search_memoriesSearch persistent memories by natural-language question or description to recall user facts and events; add synonyms and exact terms to sharpen matches.
Instructions
Find active memories by semantic meaning. Write the query as a natural-language question or description, NOT as keywords. Good: "What are the user's dietary preferences?", "meetings the user had last week". Bad: "diet food preferences", "meeting notes". Recall depends on YOU expanding the query: pass alternative phrasings in query_variants (synonyms, related terms, and sub-questions), the same way you attach variants when storing. Amber searches the query plus every variant and fuses the results -- it does NOT expand the query for you. For exact-term precision, also pass the distinctive lexical terms the answer would contain (key nouns, product names, numbers, IDs) in keywords -- and OMIT the subject's name from them (use subjects for that). Supports optional metadata filtering (e.g. { "user_tag": "work" }). Results are ordered by relevance (higher score = better match). Scores are only meaningful for ranking within a single query, not across different queries. IMPORTANT -- results are RANKED, never FILTERED: Amber always returns the closest n_results memories it has, even when none of them actually answer the query. A returned memory is therefore NOT evidence that the answer is stored, and a low score is not a reliable absence signal (scores aren't comparable across queries). YOU must judge relevance by READING the content: if no returned memory actually states the fact you asked about, treat it as NOT in memory. This matters most for the mandatory search-before-store check -- only count a fact as already stored when a returned memory genuinely states it, not merely because results came back. Ask for fewer results (n_results) if the padding is noisy. Use amber_list_memories for chronological browsing. When several results describe the SAME subject at different points in time, read them as a TIMELINE of how it evolved -- a more recent memory updates an older one, it does NOT contradict it. Each result carries created_at (and event_start/event_end when known); use those timestamps to order the progression rather than treating differing facts as a conflict. Optional topics param: pass topic names (like when storing) to focus on a category -- matched SEMANTICALLY against topics that already exist, so "beliefs" also matches "opinions"/"superstitions". It restricts the SEMANTIC half of the search to memories under the nearest topics and gives closer ones a BOUNDED lift (at most 1.5x) -- it does NOT re-sort by topic, and the keyword half is not restricted, so off-topic memories can still appear. Do not expect the on-topic memory at #1: a memory that answers the query better still wins, which is deliberate (a wrong topic guess must never bury the true answer). There is NO similarity floor: your name is matched to the NEAREST existing topics whatever their similarity, so a name matching nothing conceptually still resolves to the closest topics rather than to none. Check topics_resolved -- it reports the similarity of each match, and a low number there means your name found nothing real. A poor match cannot bury the true answer, because the lift is bounded and the keyword half is never restricted, but it does not silently become a no-op either. Omit if unsure. Content is truncated to 1000 chars in search results -- use amber_get_memory for full content. Rate-limited (drip bucket: 5000 capacity, refills ~1 token per 17 seconds).
Errors: invalid_input (a parameter has the wrong type, or a date could not be parsed). An empty result is NOT an error and comes back as an ordinary response with no hits. It is also RARE, because ranking pads results rather than filtering them, so treat it as "this account has nothing to rank" -- a new or emptied store, or a metadata_filter that excluded everything -- rather than as a stronger absence signal than a padded result.
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>",
"subjects": "<subjects>"
},
"name": "amber_search_memories"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language question or description of what to find. Use full sentences, not keywords. | |
| topics | No | Optional topic hint. Pass category names like 'food', 'work', 'beliefs'. What it actually does, in order: (1) each name is matched SEMANTICALLY against the topics that already exist and have live memories -- 'hobbies' resolves to 'gaming'; (2) the SEMANTIC half of the search is restricted to memories carrying one of the ~10 nearest topics, so on a store with many topics this genuinely narrows, while on a small store it may narrow nothing; (3) the keyword half is NOT restricted, so an off-topic memory can still appear via an exact word match; (4) closer topics get a bounded lift of at most 1.5x. That lift is a TIE-BREAKER and will NOT override relevance: a result scoring clearly better on the text still wins, so do not expect the on-topic memory to jump to #1. A synonym's edge over a near-neighbour topic is only a few percent; an EXACT existing name is far stronger. So if you need the topic to actually decide the order, call amber_list_topics and pass the exact name. The response reports `topics_resolved` -- what each name you passed matched -- so you can see how it was interpreted instead of guessing. A name matching nothing leaves the ranking unrestricted. Omit if unsure. | |
| keywords | No | Optional EXACT lexical terms for the keyword (full-text) side of hybrid search -- the distinctive words the answer would contain: key nouns, product names, numbers, IDs, codes. E.g. for "what car does the user drive?" pass ["car", "drive"]. Pick them yourself and OMIT the subject's name (that's what `subjects` is for -- a name matches every fact about a person and only adds noise). If omitted, Amber extracts keywords heuristically. Semantic matching still runs on the query + query_variants; keywords only sharpen exact-term precision. | |
| subjects | Yes | REQUIRED. Who is this query about? An ARRAY -- usually ONE person, e.g. ["patrick vane"]. Routes ranking so the right person's facts surface. Use ["self"] (or ["me"]) when the query is about the USER (e.g. "what foods is the user allergic to?") -- lifts the user's OWN facts above facts about family or others. Use a person's FULL name (e.g. ["patrick vane"]) when the query is about them: subjects are matched by EXACT (case-insensitive) text, so it must match how they were stored -- a bare first name can miss them or hit a different person. Call amber_list_subjects to see the exact names already stored. Use ["anyone"] or [] for a general query with no personal focus (e.g. "good pasta recipes"). List several only when the query is genuinely about multiple people together. BOOSTS matching memories, never hard-filters -- other subjects still appear, lower down. | |
| n_results | No | Maximum number of results to return (default 10, max 100). | |
| near_date | No | Optional ISO 8601 datetime to rank results by TEMPORAL PROXIMITY to -- memories whose own event time (event_start/event_end) sits closest to this rank higher. Use it when the query has a time focus that plain wording can't resolve: for "where does the user work NOW?" pass today's date so the current job outranks an older one; for "what car did they drive back in 2019?" pass "2019-01-01". Memories with no event date keep their relative order among themselves, though their absolute scores move slightly (measured: about 10% lower under any anchor, because anchoring renormalises the whole result set), and a far-in-time memory is never pushed BELOW an unboosted peer, though its absolute score drops 5-10% under renormalisation -- the ordering claim holds, the score claim did not, and this sentence used to make the stronger one. Pass it whenever the question genuinely has a time focus -- ESPECIALLY for relative-time wording ("recently", "lately", "last week"), because that wording carries no meaning the text search can match, so the anchor is the only thing that can find the right memory. Do NOT pass it for a time-agnostic question: dated memories can then surface above undated ones that answer it better. Omit when in doubt. | |
| near_date_end | No | Optional ISO 8601 datetime. When set together with `near_date`, proximity is measured to the WINDOW [near_date, near_date_end] instead of a single instant (a memory whose event overlaps the window gets the full boost). Use for period queries like "what happened during 2023?" (near_date 2023-01-01, near_date_end 2023-12-31). REJECTED with invalid_input if `near_date` is not also given -- it marks the end of a window, so on its own it is a mistake rather than something to silently drop. Must be on or after near_date. | |
| query_variants | No | Alternative phrasings of the SAME query that YOU generate -- synonyms, related terms, and any sub-questions -- exactly like the variants you attach when storing. Amber embeds and searches every one and fuses the results, so a memory worded differently than the user's phrasing still surfaces. Example: for "what does the user eat?" pass ["the user's dietary preferences", "foods the user likes", "what food does the user avoid?"]. Aim for 3-6; this replaces the automatic query expansion Amber used to do server-side. | |
| metadata_filter | No | Optional EXACT-match metadata filter. Matches memories whose metadata contains every key-value pair given. Matching is TYPE-STRICT: metadata stored as the number 5 is matched by 5, NOT by "5". A null VALUE matches only memories that explicitly stored a null under that key -- a memory missing the key entirely does NOT match. Values must be SCALARS (string/number/boolean/null) -- operator objects like {"$ne": ...}/{"$gte": ...} and nested objects are NOT supported (rejected with invalid_input). NOTE: applied AFTER semantic ranking, so it only filters the top relevance candidates -- a matching memory that scores low against the query can fall out. For an EXHAUSTIVE "give me everything tagged X", use amber_list_memories with its metadata_filter instead. WHEN (and only when) you pass metadata_filter, the response adds `filter_matched_total` (how many memories the filter matches in total) and `filter_truncated` -- if `filter_truncated` is true you are looking at a PARTIAL set and must NOT report it as complete; re-run via amber_list_memories to get all of them. NOTE: no value of n_results makes a filtered search exhaustive -- the filter is applied to a bounded relevance candidate pool, so amber_list_memories is the only exhaustive path. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| results | Yes | Matches, best first. An empty array means nothing matched, which is an ordinary result rather than an error. | |
| topics_resolved | No | Only when `topics` was supplied: what each requested topic name actually matched among the topics that exist. Topic names are matched semantically, so a synonym resolves to a NEARBY topic ('hobbies' -> 'gaming'); check `matched` to see how your name was interpreted. Because the topic boost is a bounded tie-breaker, a correct resolution can still leave the ranking unchanged -- if you need topics to decide the order, pass an EXACT name from amber_list_topics. | |
| filter_truncated | No | Only when metadata_filter was supplied: true when filter_matched_total exceeds the number of results returned. Use `amber_list_memories` with the same metadata_filter to get the complete set. | |
| filter_matched_total | No | Only when metadata_filter was supplied: how many active memories match that filter IN TOTAL, regardless of how many ranked into this page. |