Store memories
amber_store_memoryStore atomic, self-contained facts with alternative phrasings, subjects, and topics so they can be retrieved later by meaning. Accepted writes are validated and queued as durable long-term memory.
Instructions
Store long-term memories you can search later with amber_search_memories. YOU do the preparation. Amber only validates and stores what you send, so follow these rules exactly for consistent, searchable memories. ALWAYS search before you store (see "SEARCH FIRST" below): Amber removes ONLY facts that are byte-identical to another fact in the SAME call (reported as duplicates_collapsed) -- it does NOT deduplicate across separate calls (a retry after a transport error stores a second copy UNLESS you sent an idempotency_key, which is exactly what that parameter is for -- generate one per store and resend with the SAME key to get the original task_id back instead of a duplicate), and it never matches on MEANING, so a re-worded restatement of an existing memory is stored as a second copy. Preventing those is entirely your responsibility.
WRITES ARE ASYNCHRONOUS. "Accepted N fact(s)" means your facts were validated and queued, NOT that they are stored yet. Rows are not queryable until the task reports completed: poll amber_get_store_task_status with the returned task_id BEFORE you list, filter, search for, or delete them, and check memory_ids.length against fact_count. Acting sooner gives misleading results -- a list can show fewer rows than you sent and a delete can silently skip one that has not landed yet. But do NOT hold your reply to the user waiting for it: an accepted store is already durable, so answer first and check the status only when you are about to act on those rows or the user asks whether it was saved.
Send memories: an array of ATOMIC FACTS you extracted from the conversation. Break the source text into the smallest possible self-contained facts, where each memory is exactly ONE single statement, then format each as an object with these fields:
• "content" (required) is exactly ONE fact: a single statement of one thing (a subject plus one predicate: "X is Y", "X did Z", "X has W"). This rule is broken far more than any other, and almost always the same way: by writing a PROFILE, packing everything you know about a person, place, or project into one memory. NEVER do that. Facts that share a subject are still separate memories, ONE PER FACT: six things about the same person is SIX memories, not one. A memory states exactly ONE fact, and even a SHORT sentence must be split if it states two (see the split test below); a paragraph is never one memory. SPLIT TEST. Before storing each memory, try to break its content apart; if any piece can stand alone as its own fact, you MUST split there:
more than one sentence → one memory per sentence;
parts joined by "and" / "but" / a comma / a semicolon that each stand alone → one memory each ("Sam is a widower and has three daughters" = TWO facts, stored separately);
different KINDS of information bundled about someone (who they are + a job + a marriage + a health note + an anecdote) → one memory per item;
DENSE TECHNICAL or MEASURED data (test results, genotypes, lab values, metrics, specs, config values) → ONE result per memory. This is the most-missed case for domain data: "ALDH2 rs671 is normal and ADH1B is *1/*1; her CYP1A2 is A/A, a fast caffeine metabolizer" is TWO facts (alcohol metabolism, caffeine metabolism), and a run of readings/genotypes/counts is one memory EACH. A technically-coherent sentence is still not one fact, and density is not an excuse to bundle. Keep splitting until removing any remaining piece would make the fact false or meaningless. Only then is it atomic. Do NOT split these (each is genuinely ONE fact): a fact bundled with its own cause/qualifier ("Pat uses RustDesk BECAUSE AnyDesk added a timer"); a joint action by several subjects acting together ("Pat and Kim traveled to Rome"); the members of a single set ("the three team leads are Ann, Bo and Cal"). A list of DIFFERENT attributes is NOT a set, so split it. Each memory must also stand alone: explicit full names, never pronouns ("he"/"they"/"it") or vague references ("the project", "that place"); keep the original specifics (names, numbers, dates). WORKED EXAMPLE: this one paragraph becomes FOUR separate memories (four objects in
memories, each with its own variants): "Maria Lopez is our CFO; she joined in 2019, came from Stripe, and has two kids." → "Maria Lopez is the company's CFO." · "Maria Lopez joined the company in 2019." · "Maria Lopez previously worked at Stripe." · "Maria Lopez has two children." SHORT sentences split too, and this is the most-missed case. "Robin Vane is a lawyer, born around 1991" is TWO memories: "Robin Vane is a lawyer." + "Robin Vane was born around 1991." A person's occupation, birth year, birthplace, employer, and marital status are each a SEPARATE fact, one memory apiece, never merged into a one-line description.
• "variants" (REQUIRED, 5-8 per fact; a store is REJECTED if any fact has fewer than 5 distinct phrasings) are alternative phrasings of the SAME fact. Variants are the main thing that makes a memory findable later, so generate a GENEROUS, DIVERSE set every time: 5 to 8, never just 1-2. For each fact, cover several of these angles:
synonyms / reworded ("Patrick can't digest lactose" / "Patrick is intolerant to dairy sugar")
the question forms the fact answers ("What is Patrick allergic to?", "Who is lactose intolerant?")
a different sentence structure or word order
a short, keyword-dense form ("Patrick Vane, lactose intolerance") Every variant MUST mean exactly the same fact (never add, drop, or change information) and should include the subject's name so it stands alone. Make them GENUINELY different wording, because padding with punctuation/spacing/casing tweaks ("retest", "retest.", "re-test") does NOT count (those collapse to one), so five near-identical strings are rejected just like two. A variant is a RESTATEMENT, never commentary: do NOT add a label, category, comparison, or characterisation the fact did not itself state ("star-of-stars topology", "X-style architecture", "has prior experience with Y", "the industry-standard approach"). If the fact does not say it, neither can the variant. Distinct phrasings only, and near-duplicates don't count toward the minimum.
• "subjects" is an ARRAY of the people the fact is about, lowercase (e.g. ["patrick vane"]). Use the person's FULL name ("patrick vane", never "patrick"). A FIRST NAME ALONE IS NOT AN IDENTIFIER: people share first names, so unless you are CERTAIN which person this is, STOP AND ASK THE USER before storing. Do not guess and do not store the bare first name. In particular, NEVER assume a bare first name means the same person as an existing subject that starts with it: if the user says "colin" and memory holds "colin murphy", that may be a DIFFERENT colin, and silently attaching this fact to the stored one MERGES two people. Ask which one. A wrong merge mixes two people's lives together and is painful to unpick later, whereas asking one short question costs nothing. A fact about SEVERAL people together (a shared event/relationship) lists each: ["patrick vane", "yu pan"]. Tag EVERY person the fact names or establishes, not just the main one or the connecting relative. A fact that NAMES a set of people ("The Garcias' three children are Ana, Ben and Cara"; "X's siblings are A, B and C"; "their two sons are Sam and Theo") must tag EACH named person so every one becomes findable: e.g. ["ana garcia", "ben garcia", "cara garcia"] plus the parents, NEVER just the parents or the one child emphasized. A fact NOT about a specific person (a product, project, place, org, concept) → empty array []. Never invent a subject. Subjects are matched by EXACT (case-insensitive) text at search time: "patrick" and "patrick vane" are treated as DIFFERENT people, and near-variants ("pat", "patrick v") never match, so reuse the EXACT spelling a person is already stored under. Subject drives ranking, so call amber_list_subjects to see who is already in memory and reuse that exact name.
• "topics" (up to 3) are broad, REUSABLE, lowercase category labels (e.g. "health", "work", "travel", "finances"). Not specific to this one fact ("likes strawberries" ✗), not meta ("memory about food" ✗). Topics are matched SEMANTICALLY at search time (a search for "work" also finds "career"/"job"), so exact wording matters less than for subjects, but still REUSE names that already exist rather than minting near-duplicates, to avoid clutter; call amber_list_topics to see what's in use and pick from it.
• "event_start" / "event_end" are ISO 8601 datetimes for WHEN the fact's event happened, or null. Resolve relative references ("last week", "yesterday") to actual dates using today's date. Point-in-time → set both equal; ongoing ("since March") → start only; range ("summer 2024") → both. null when the fact has no temporal reference.
• "metadata" (optional) is a flat object of exact-match filter values for later search.
SEARCH FIRST. THIS IS MANDATORY. This is the ONLY thing preventing duplicates: Amber does NOT dedupe, it stores exactly what you send, so storing a fact that is already in memory leaves TWO live copies of it forever and every later search returns both. Before storing ANY fact, call amber_search_memories for that fact's subject/topic, then decide per fact:
Genuinely new (search finds nothing equivalent) → store it.
Already stored and unchanged → SKIP it. Do not re-store it, not even reworded; a differently-phrased copy of the same fact is still a duplicate.
SUPERSEDES one you already stored (a status changed, a value was corrected, a previously-unknown answer got resolved, a plan reversed) → the OLD memory is now stale: DELETE it (amber_delete_memory) and store the corrected fact. Never leave both live. Piling up each new state as a fresh memory is the single biggest way this store rots: search then returns the stale and current versions side by side. Supersede, don't accumulate. (amber_update_memory only fixes a memory's subject, topics, or metadata, NOT its wording; use delete-then-store to change what a fact actually says.) DO NOT rely on your own memory of what you have already stored. If this is a NEW SESSION, or your context was summarized/compacted, you may have ALREADY saved these exact facts even though you don't recall doing so. Re-storing them from a fresh context is the #1 cause of accidental duplicates. When in any doubt, SEARCH; never assume a fact is unstored.
HARD LIMITS (a store is rejected, not truncated, if you exceed one, so size your batches to these): • memories per call: 500 · content: 4000 chars per fact • variants: 5 minimum DISTINCT (enforced), 50 maximum · each variant up to 4000 chars • subjects: 8 per fact, 100 chars each · topics: 3 per fact, 50 chars each • metadata: 4000 bytes total, flat scalars only Control characters (other than tab/newline/carriage-return) are rejected anywhere in these fields. They would corrupt the stored text.
Errors: invalid_input (one or more facts are malformed: too long, fewer than 5 distinct
variants, control characters, a bad date, or metadata that is not flat scalars). NOTHING is
stored when this happens, so fix and resend the whole call. The response names EVERY bad index
at once rather than stopping at the first, so one round trip is enough to correct them all.
queue_unavailable (the write queue is momentarily saturated) also stores NOTHING and is
safe to retry in a few seconds -- it is reported BEFORE any memory is written, never after.
idempotency_key_reused means the key you sent already names a store that held
DIFFERENT facts. NOTHING was written, and the message names that original task. Either resend
the ORIGINAL facts under that key to recover it, or use a FRESH key for these facts. Do not
retry the same call unchanged: it will be refused again, by design, because absorbing it would
discard the facts you just sent with no way to get them back.
Example (note the generous, varied variant sets, do the same): amber_store_memory({ "memories": [ { "content": "Patrick Vane is lactose intolerant.", "variants": ["Patrick Vane can't digest lactose", "Patrick Vane is intolerant to dairy", "What is Patrick Vane allergic to? Lactose.", "Who is lactose intolerant? Patrick Vane.", "Patrick Vane should avoid milk and dairy", "Patrick Vane, lactose/dairy intolerance"], "subjects": ["patrick vane"], "topics": ["health", "food"], "event_start": null, "event_end": null }, { "content": "Patrick Vane and Yu Pan traveled to Rome in June 2026.", "variants": ["Patrick Vane and Yu Pan visited Rome", "Patrick Vane and Yu Pan took a trip to Italy", "When did Patrick Vane go to Rome? June 2026.", "Who traveled to Rome in June 2026? Patrick Vane and Yu Pan.", "Patrick Vane and Yu Pan, Rome trip, June 2026"], "subjects": ["patrick vane", "yu pan"], "topics": ["travel"], "event_start": "2026-06-01T00:00:00Z", "event_end": "2026-06-30T23:59:59Z" } ] })
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": {
"memories": "<memories>"
},
"name": "amber_store_memory"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| memories | Yes | Array of atomic facts YOU extracted from the conversation, at most 500 per call. Follow the tool description's rules exactly. | |
| idempotency_key | No | OPTIONAL but strongly recommended: a UNIQUE id YOU generate before calling -- a UUID is ideal -- so a retry after a network failure cannot store everything twice. If the call fails with a transport error, call again with the SAME key and the SAME facts IN THE SAME ORDER, and you get the original `task_id` back instead of a second store. Generate a FRESH key for each genuinely new store: reusing one for a different set of facts is refused with `idempotency_key_reused` and stores nothing, so a key derived from something that repeats (a turn number, a user id) will collide with your own earlier store. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | `pending` on a NEW store: the facts were validated and QUEUED, not stored, and they are not queryable until `amber_get_store_task_status` reports `completed`, so do not list, search or delete them before then. On a `deduplicated` response this is the REAL current status of the ORIGINAL task, which may already be `completed` -- it was hardcoded to `pending` until 2026-09-20, which told callers not to touch rows that were in fact fully written. | |
| message | Yes | A human-readable summary, including how many duplicates were collapsed within this call. | |
| task_id | Yes | Processing task ID. Use `amber_get_store_task_status` to check progress and get resulting memory IDs. | |
| deduplicated | No | Present and `true` only when your `idempotency_key` matched a store you had already made: `task_id` names that ORIGINAL store and nothing new was written, so this call stored nothing and that is the correct outcome. Absent on a first store. | |
| duplicates_collapsed | No | Only when this call contained EXACT duplicate facts (same content, variants, subjects, topics, dates and metadata): how many were collapsed. Present only when some were, so `duplicates_collapsed` plus the facts actually stored accounts for every entry you sent. |