Skip to main content
Glama

Store memories

amber_store_memory

Store 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

NameRequiredDescriptionDefault
memoriesYesArray of atomic facts YOU extracted from the conversation, at most 500 per call. Follow the tool description's rules exactly.
idempotency_keyNoOPTIONAL 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

NameRequiredDescriptionDefault
statusYes`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.
messageYesA human-readable summary, including how many duplicates were collapsed within this call.
task_idYesProcessing task ID. Use `amber_get_store_task_status` to check progress and get resulting memory IDs.
deduplicatedNoPresent 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_collapsedNoOnly 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv1.1.6
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / content
      Removed value: -{
      -  "description": "The text to remember, 1-50000 characters.",
      -  "maxLength": 50000,
      -  "minLength": 1,
      -  "type": "string"
      -}
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "description": "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.",
      +  "maxLength": 200,
      +  "minLength": 8,
      +  "type": "string"
      +}
    • addedInput schema / properties / memories
      Added value: +{
      +  "description": "Array of atomic facts YOU extracted from the conversation, at most 500 per call. Follow the tool description's rules exactly.",
      +  "items": {
      +    "properties": {
      +      "content": {
      +        "description": "ONE atomic, self-contained fact. Explicit names, no pronouns. At most 4000 characters.",
      +        "type": "string"
      +      },
      +      "event_end": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "ISO 8601 datetime the fact's event ended (equal to start for a point in time), or null."
      +      },
      +      "event_start": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "ISO 8601 datetime the fact's event began, or null."
      +      },
      +      "metadata": {
      +        "additionalProperties": {},
      +        "description": "Flat object of exact-match filter values for later search: string, number, boolean or null values only, at most 4000 bytes as JSON.",
      +        "propertyNames": {
      +          "type": "string"
      +        },
      +        "type": "object"
      +      },
      +      "subjects": {
      +        "description": "At most 8 people, each at most 100 characters. Array of the lowercase people the fact is about, FULL names: [\"patrick vane\"] or [\"patrick vane\", \"yu pan\"]. A first name alone is not an identifier -- people share first names, so unless you are CERTAIN who this is, ASK THE USER rather than storing a bare first name or attaching the fact to an existing subject that merely starts with it (that silently MERGES two people). Empty array [] if it is not about a specific person.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "topics": {
      +        "description": "Up to 3 broad, reusable, lowercase categories (e.g. \"health\", \"work\", \"travel\"), each at most 50 characters.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "maxItems": 3,
      +        "type": "array"
      +      },
      +      "variants": {
      +        "description": "REQUIRED. 5-8 (minimum 5, maximum 50) DISTINCT phrasings / question forms of the SAME fact, each at most 4000 characters -- these are what make it findable. Never just 1-2.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "content",
      +      "variants",
      +      "subjects"
      +    ],
      +    "type": "object"
      +  },
      +  "minItems": 1,
      +  "type": "array"
      +}
    • removedInput schema / properties / metadata
      Removed value: -{
      -  "additionalProperties": {},
      -  "description": "Concrete values for exact-match filtering in searches. Only useful for structured data like person names, dates, project names, sources. NOT for categories or topic names. Example: {person: \"Sarah\", date: \"2026-05-09\"}.",
      -  "type": "object"
      -}
    • removedInput schema / properties / topics
      Removed value: -{
      -  "description": "Optional broad categories for this memory (e.g. 'work', 'health', 'travel'). Only needed when the category can't be inferred from the text itself -- most memories don't need this. Matched semantically, so you don't need to guess exact names. Do NOT use topics for specific names, dates, or values -- use `metadata` for those (e.g. {\"person\": \"Sarah\"}). Topics are searched semantically; metadata is filtered by exact match.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": "array"
      -}
    • changedInput schema / required
      Previous value: -[
      -  "content"
      -]New value: +[
      +  "memories"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "deduplicated": {
      +      "description": "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.",
      +      "type": "boolean"
      +    },
      +    "duplicates_collapsed": {
      +      "description": "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.",
      +      "type": "number"
      +    },
      +    "message": {
      +      "description": "A human-readable summary, including how many duplicates were collapsed within this call.",
      +      "type": "string"
      +    },
      +    "status": {
      +      "description": "`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.",
      +      "enum": [
      +        "pending",
      +        "processing",
      +        "completed",
      +        "error"
      +      ],
      +      "type": "string"
      +    },
      +    "task_id": {
      +      "description": "Processing task ID. Use `amber_get_store_task_status` to check progress and get resulting memory IDs.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "task_id",
      +    "status",
      +    "message"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description supplies the real behavioral profile: writes are asynchronous and rows are unqueryable until a task reports completed, dedup is byte-identical and same-call only, retries without an idempotency_key duplicate data, and each named error (invalid_input, queue_unavailable, idempotency_key_reused) is documented with whether anything was written. That is materially more than the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded correctly, but the text runs to well over a thousand words and restates the same warnings repeatedly — non-deduplication is asserted in the opening paragraph, again under SEARCH FIRST, and again in the fresh-context warning; the atomicity rule is stated, then restated as a split test, then as a worked example. Much of this is genuinely necessary for a tool with strict validation, but the redundancy and the bullet-dense formatting make it hard to scan, and a tighter version would lose no instruction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with strict server-side validation and a rejection-not-truncation failure mode, the description covers batching limits, field-level limits, control-character rejection, per-index error reporting, async task polling, and an inline call example. Nothing an agent needs in order to call it successfully is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a baseline 3 would be defensible, but the description adds operational meaning the schema cannot: the split test for what counts as one atomic fact, worked examples of valid variant sets, and why subjects are matched by exact text so full stored spellings must be reused. It also explains the exact retry contract for idempotency_key (same key, same facts, same order), which changes how the parameter is used.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("Store long-term memories") and immediately names the retrieval sibling ("you can search later with amber_search_memories"), so an agent knows exactly what this does and which tool consumes its output. It also distinguishes itself from sibling writers by stating that Amber "only validates and stores what you send" rather than extracting facts itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules: call amber_search_memories before storing, skip unchanged facts, delete-then-store when a fact supersedes an old one, and use amber_get_store_task_status before acting on accepted rows. It also bounds the search-first rule with a when-not ("do NOT hold your reply to the user waiting for it"), which is rare precision.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.