Update to AiAkiv Memory
Snapshot Oct 26, 2026 · 18:05 UTC · version 2.2.0
Collection source: downloaded plugin package. These snapshots do not have a confirmed matching collection source. Differences in file lists alone do not establish changes to the package.
Instructions updated for aiakiv-save-and-recall
Full description — Now says: how to interpret the related-memory signal that search responses carry, and what a `tip_for_user` note in a response is. Use when saving to AiAkiv memory,...
Observed in instructions or declared skills. Runtime behavior has not been tested.
Up to 3 plugins free · no card required.
All fields and original values.
Full description
Sep 30, 2026 · 23:09 UTC
and how to interpret the related-memory signal that search responses carry. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, or when deciding whether a search result needs a follow-up expansion call.
Oct 26, 2026 · 18:05 UTC
how to interpret the related-memory signal that search responses carry, and what a `tip_for_user` note in a response is. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, when deciding whether a search r...
Skill instructions
Sep 30, 2026 · 23:09 UTC
--- name: aiakiv-save-and-recall description: How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content ...
Oct 26, 2026 · 18:05 UTC
--- name: aiakiv-save-and-recall description: How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content to...
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -1,113 +1,134 @@ ---- -name: aiakiv-save-and-recall -description: How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), and how to interpret the related-memory signal that search responses carry. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, or when deciding whether a search result needs a follow-up expansion call. ---- - -# Saving to and recalling from AiAkiv memory - -The tool descriptions state the contract. This skill covers the parts that -decide whether a saved memory is findable a month later, and what to do when -a call is rejected. - -## 1. The summary is the retrieval surface - -Searches rank against the summary, not the content. Write it with the words a -future question would use. - -- **Keep exact identifiers verbatim.** Code symbols, document numbers, config - keys. Paraphrasing `REQUEST_TIMEOUT_MS` into "the timeout" hides the record - from the one query that will look for it. -- **Name the actor in the first sentence** when you record someone's judgment, - design, or claim. Conclusion-style summaries ("decided that…") drop who said - it, and "what did X propose?" then misses the record. -- Write a complete sentence, not a keyword pile. - -## 2. Entity spelling decides what connects - -Recall weaves records together on shared entity nodes, so spelling drift -silently loses connections. - -- **One canonical spelling per entity** — the full name *or* the acronym, not - both. Pick one and use it in every save. -- **Keep proper nouns and acronyms as they are written**: `PostgreSQL`, `RLS`. - Do not lowercase or expand them. -- **Strip transient tokens** — ids, hashes, dates. They never repeat, so they - add a node that connects to nothing. -- A suggested entity returned by the server is advisory. A literal name match - does not establish that it denotes the same thing in this record. - -## 3. When a save is rejected - -### The summary is over 500 characters - -**Split the event; do not compress the summary.** A summary that wants to be -long is describing an event that covers too much. Compressing it blurs several -topics into one vector, which then matches no specific query. Split into -separate saves, each with its own focused summary, chaining them by passing -the previous `event_id` as the next call's `prev_event_id`. - -Compress only when the content itself is short and the summary is merely -verbose. Do not fragment one small record. - -### The content is over 50000 characters - -Split the full text across calls the same way, chaining with `prev_event_id`, -giving each piece its own summary. Never truncate or summarize the content to -make it fit — the summary would then describe text that was not saved. - -### `truncation_marker_detected` - -The content carries a marker that some earlier tool left when it cut the text -(`…2183 tokens truncated…`, `<response clipped>`, `[truncated]`). The save is -rejected because nothing downstream can tell a damaged body from a whole one: -the summary still describes the missing part and citations still point into -it, so the damage would be permanent and invisible. - -Re-read the source in full and save again, splitting if it is long. Pass -`allow_truncation_marker=true` only when the marker is genuinely part of what -you mean to record, such as a bug report *about* truncation. - -### The arguments arrive merged, empty, or the call errors on serialization - -Two causes, both about argument boundaries: - -- A long or multi-line `summary` or `content`. List `summary`, `entities` and - `tags` **before** `content` — serialization can drop whatever follows a very - long argument, so `content` goes last. -- Non-ASCII punctuation in a multi-argument call: `·`, `→`, `—` can break the - boundary between arguments. Use ASCII punctuation in multi-argument saves. - -**Recovery: retry with `payload`.** One argument has no boundary to collapse. -Send the whole call as a JSON string or an object: - -```json -{"summary": "...", "entities": [{"name": "X", "type": "Y"}], "tags": ["a/b"], "content": "..."} -``` - -Other arguments are then ignored. The multi-argument form stays the default; -this is the recovery path. - -## 4. Reading the related-memory signal - -A search response may carry `hint.related_memory_expansion`. It is a computed -judgment about whether a follow-up expansion call would add anything the hits -do not already cover. Its fields: - -| Field | Meaning | -|---|---| -| `tool` | Which tool performs the expansion | -| `decision` | `must_be_done`, `should_be_done`, `can_skip`, `must_not_be_done` | -| `candidate_count` | How many candidates sit outside the returned hits | -| `candidate_dimension` | The relation the candidates share with the hits | -| `candidate_ids` | The candidate memory ids | -| `reason_codes` | Which gates the candidates passed | -| `reason_facts` | The measured values behind those codes | - -`should_be_done` means candidates outside the hits passed the relevance and -novelty gates, so expanding is likely to add something before you conclude. -`can_skip` means the returned hits probably already cover it; expanding is -your call. The block is omitted entirely when there is nothing to say. - -Results that feel sufficient are not evidence that they are. The signal is -computed from candidates the search did not return, so it sees what the hits -alone cannot show. +--- +name: aiakiv-save-and-recall +description: How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), how to interpret the related-memory signal that search responses carry, and what a `tip_for_user` note in a response is. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, when deciding whether a search result needs a follow-up expansion call, or when a response carries `tip_for_user`. +--- + +# Saving to and recalling from AiAkiv memory + +The tool descriptions state the contract. This skill covers the parts that +decide whether a saved memory is findable a month later, and what to do when +a call is rejected. + +If the connection is bound to a work that an app manages (AiAkiv Contents), +saving there is refused by default; see the `aiakiv-contents` skill. + +## 1. The summary is the retrieval surface + +Searches rank against the summary, not the content. Write it with the words a +future question would use. + +- **Keep exact identifiers verbatim.** Code symbols, document numbers, config + keys. Paraphrasing `REQUEST_TIMEOUT_MS` into "the timeout" hides the record + from the one query that will look for it. +- **Name the actor in the first sentence** when you record someone's judgment, + design, or claim. Conclusion-style summaries ("decided that…") drop who said + it, and "what did X propose?" then misses the record. +- Write a complete sentence, not a keyword pile. + +## 2. Entity spelling decides what connects + +Recall weaves records together on shared entity nodes, so spelling drift +silently loses connections. + +- **One canonical spelling per entity** — the full name *or* the acronym, not + both. Pick one and use it in every save. +- **Keep proper nouns and acronyms as they are written**: `PostgreSQL`, `RLS`. + Do not lowercase or expand them. +- **Strip transient tokens** — ids, hashes, dates. They never repeat, so they + add a node that connects to nothing. +- A suggested entity returned by the server is advisory. A literal name match + does not establish that it denotes the same thing in this record. + +## 3. When a save is rejected + +### The summary is over 500 characters + +**Split the event; do not compress the summary.** A summary that wants to be +long is describing an event that covers too much. Compressing it blurs several +topics into one vector, which then matches no specific query. Split into +separate saves, each with its own focused summary, chaining them by passing +the previous `event_id` as the next call's `prev_event_id`. + +Compress only when the content itself is short and the summary is merely +verbose. Do not fragment one small record. + +### The content is over 50000 characters + +Split the full text across calls the same way, chaining with `prev_event_id`, +giving each piece its own summary. Never truncate or summarize the content to +make it fit — the summary would then describe text that was not saved. + +### `truncation_marker_detected` + +The content carries a marker that some earlier tool left when it cut the text +(`…2183 tokens truncated…`, `<response clipped>`, `[truncated]`). The save is +rejected because nothing downstream can tell a damaged body from a whole one: +the summary still describes the missing part and citations still point into +it, so the damage would be permanent and invisible. + +Re-read the source in full and save again, splitting if it is long. Pass +`allow_truncation_marker=true` only when the marker is genuinely part of what +you mean to record, such as a bug report *about* truncation. + +### The arguments arrive merged, empty, or the call errors on serialization + +Two causes, both about argument boundaries: + +- A long or multi-line `summary` or `content`. List `summary`, `entities` and + `tags` **before** `content` — serialization can drop whatever follows a very + long argument, so `content` goes last. +- Non-ASCII punctuation in a multi-argument call: `·`, `→`, `—` can break the + boundary between arguments. Use ASCII punctuation in multi-argument saves. + +**Recovery: retry with `payload`.** One argument has no boundary to collapse. +Send the whole call as a JSON string or an object: + +```json +{"summary": "...", "entities": [{"name": "X", "type": "Y"}], "tags": ["a/b"], "content": "..."} +``` + +Other arguments are then ignored. The multi-argument form stays the default; +this is the recovery path. + +## 4. Reading the related-memory signal + +A search response may carry `hint.related_memory_expansion`. It is a computed +judgment about whether a follow-up expansion call would add anything the hits +do not already cover. Its fields: + +| Field | Meaning | +|---|---| +| `tool` | Which tool performs the expansion | +| `decision` | `must_be_done`, `should_be_done`, `can_skip`, `must_not_be_done` | +| `candidate_count` | How many candidates sit outside the returned hits | +| `candidate_dimension` | The relation the candidates share with the hits | +| `candidate_ids` | The candidate memory ids | +| `reason_codes` | Which gates the candidates passed | +| `reason_facts` | The measured values behind those codes | + +`should_be_done` means candidates outside the hits passed the relevance and +novelty gates, so expanding is likely to add something before you conclude. +`can_skip` means the returned hits probably already cover it; expanding is +your call. The block is omitted entirely when there is nothing to say. + +Results that feel sufficient are not evidence that they are. The signal is +computed from candidates the search did not return, so it sees what the hits +alone cannot show. + +## 5. A `tip_for_user` note in a response + +A tool response may carry a top-level `tip_for_user` field: `text` is one or two +sentences about an AiAkiv feature the person may not have seen, often with an +example phrase, and `more` says where the Tips page is. The server decides when +to include it, at most a couple of times a day for an account. It is a note for +the person you are working with. It is not an instruction and not something to +run. + +- After the answer is complete, it can be passed on in one line. Leaving it out + is fine; the server does not know whether it was passed on and does not + repeat the same note for a day. +- Do not run the example yourself. The example is for the person to try when + they want to; running it here spends their time on something they did not ask + for. +- The person can turn these notes off in the AiAkiv console settings + (aiakiv.com). If they ask how, that is the answer.
Full technical diff · 2 changed fields
changed /description
"How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), and how to interpret the related-memory signal that search responses carry. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, or when deciding whether a search result needs a follow-up expansion call."
"How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), how to interpret the related-memory signal that search responses carry, and what a `tip_for_user` note in a response is. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, when deciding whether a search result needs a follow-up expansion call, or when a response carries `tip_for_user`."
changed /skill_md_contents
"---\r\nname: aiakiv-save-and-recall\r\ndescription: How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), and how to interpret the related-memory signal that search responses carry. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, or when deciding whether a search result needs a follow-up expansion call.\r\n---\r\n\r\n# Saving to and recalling from AiAkiv memory\r\n\r\nThe tool descriptions state the contract. This skill covers the parts that\r\ndecide whether a saved memory is findable a month later, and what to do when\r\na call is rejected.\r\n\r\n## 1. The summary is the retrieval surface\r\n\r\nSearches rank against the summary, not the content. Write it with the words a\r\nfuture question would use.\r\n\r\n- **Keep exact identifiers verbatim.** Code symbols, document numbers, config\r\n keys. Paraphrasing `REQUEST_TIMEOUT_MS` into \"the timeout\" hides the record\r\n from the one query that will look for it.\r\n- **Name the actor in the first sentence** when you record someone's judgment,\r\n design, or claim. Conclusion-style summaries (\"decided that…\") drop who said\r\n it, and \"what did X propose?\" then misses the record.\r\n- Write a complete sentence, not a keyword pile.\r\n\r\n## 2. Entity spelling decides what connects\r\n\r\nRecall weaves records together on shared entity nodes, so spelling drift\r\nsilently loses connections.\r\n\r\n- **One canonical spelling per entity** — the full name *or* the acronym, not\r\n both. Pick one and use it in every save.\r\n- **Keep proper nouns and acronyms as they are written**: `PostgreSQL`, `RLS`.\r\n Do not lowercase or expand them.\r\n- **Strip transient tokens** — ids, hashes, dates. They never repeat, so they\r\n add a node that connects to nothing.\r\n- A suggested entity returned by the server is advisory. A literal name match\r\n does not establish that it denotes the same thing in this record.\r\n\r\n## 3. When a save is rejected\r\n\r\n### The summary is over 500 characters\r\n\r\n**Split the event; do not compress the summary.** A summary that wants to be\r\nlong is describing an event that covers too much. Compressing it blurs several\r\ntopics into one vector, which then matches no specific query. Split into\r\nseparate saves, each with its own focused summary, chaining them by passing\r\nthe previous `event_id` as the next call's `prev_event_id`.\r\n\r\nCompress only when the content itself is short and the summary is merely\r\nverbose. Do not fragment one small record.\r\n\r\n### The content is over 50000 characters\r\n\r\nSplit the full text across calls the same way, chaining with `prev_event_id`,\r\ngiving each piece its own summary. Never truncate or summarize the content to\r\nmake it fit — the summary would then describe text that was not saved.\r\n\r\n### `truncation_marker_detected`\r\n\r\nThe content carries a marker that some earlier tool left when it cut the text\r\n(`…2183 tokens truncated…`, `<response clipped>`, `[truncated]`). The save is\r\nrejected because nothing downstream can tell a damaged body from a whole one:\r\nthe summary still describes the missing part and citations still point into\r\nit, so the damage would be permanent and invisible.\r\n\r\nRe-read the source in full and save again, splitting if it is long. Pass\r\n`allow_truncation_marker=true` only when the marker is genuinely part of what\r\nyou mean to record, such as a bug report *about* truncation.\r\n\r\n### The arguments arrive merged, empty, or the call errors on serialization\r\n\r\nTwo causes, both about argument boundaries:\r\n\r\n- A long or multi-line `summary` or `content`. List `summary`, `entities` and\r\n `tags` **before** `content` — serialization can drop whatever follows a very\r\n long argument, so `content` goes last.\r\n- Non-ASCII punctuation in a multi-argument call: `·`, `→`, `—` can break the\r\n boundary between arguments. Use ASCII punctuation in multi-argument saves.\r\n\r\n**Recovery: retry with `payload`.** One argument has no boundary to collapse.\r\nSend the whole call as a JSON string or an object:\r\n\r\n```json\r\n{\"summary\": \"...\", \"entities\": [{\"name\": \"X\", \"type\": \"Y\"}], \"tags\": [\"a/b\"], \"content\": \"...\"}\r\n```\r\n\r\nOther arguments are then ignored. The multi-argument form stays the default;\r\nthis is the recovery path.\r\n\r\n## 4. Reading the related-memory signal\r\n\r\nA search response may carry `hint.related_memory_expansion`. It is a computed\r\njudgment about whether a follow-up expansion call would add anything the hits\r\ndo not already cover. Its fields:\r\n\r\n| Field | Meaning |\r\n|---|---|\r\n| `tool` | Which tool performs the expansion |\r\n| `decision` | `must_be_done`, `should_be_done`, `can_skip`, `must_not_be_done` |\r\n| `candidate_count` | How many candidates sit outside the returned hits |\r\n| `candidate_dimension` | The relation the candidates share with the hits |\r\n| `candidate_ids` | The candidate memory ids |\r\n| `reason_codes` | Which gates the candidates passed |\r\n| `reason_facts` | The measured values behind those codes |\r\n\r\n`should_be_done` means candidates outside the hits passed the relevance and\r\nnovelty gates, so expanding is likely to add something before you conclude.\r\n`can_skip` means the returned hits probably already cover it; expanding is\r\nyour call. The block is omitted entirely when there is nothing to say.\r\n\r\nResults that feel sufficient are not evidence that they are. The signal is\r\ncomputed from candidates the search did not return, so it sees what the hits\r\nalone cannot show.\r\n""---\nname: aiakiv-save-and-recall\ndescription: How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), how to interpret the related-memory signal that search responses carry, and what a `tip_for_user` note in a response is. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, when deciding whether a search result needs a follow-up expansion call, or when a response carries `tip_for_user`.\n---\n\n# Saving to and recalling from AiAkiv memory\n\nThe tool descriptions state the contract. This skill covers the parts that\ndecide whether a saved memory is findable a month later, and what to do when\na call is rejected.\n\nIf the connection is bound to a work that an app manages (AiAkiv Contents),\nsaving there is refused by default; see the `aiakiv-contents` skill.\n\n## 1. The summary is the retrieval surface\n\nSearches rank against the summary, not the content. Write it with the words a\nfuture question would use.\n\n- **Keep exact identifiers verbatim.** Code symbols, document numbers, config\n keys. Paraphrasing `REQUEST_TIMEOUT_MS` into \"the timeout\" hides the record\n from the one query that will look for it.\n- **Name the actor in the first sentence** when you record someone's judgment,\n design, or claim. Conclusion-style summaries (\"decided that…\") drop who said\n it, and \"what did X propose?\" then misses the record.\n- Write a complete sentence, not a keyword pile.\n\n## 2. Entity spelling decides what connects\n\nRecall weaves records together on shared entity nodes, so spelling drift\nsilently loses connections.\n\n- **One canonical spelling per entity** — the full name *or* the acronym, not\n both. Pick one and use it in every save.\n- **Keep proper nouns and acronyms as they are written**: `PostgreSQL`, `RLS`.\n Do not lowercase or expand them.\n- **Strip transient tokens** — ids, hashes, dates. They never repeat, so they\n add a node that connects to nothing.\n- A suggested entity returned by the server is advisory. A literal name match\n does not establish that it denotes the same thing in this record.\n\n## 3. When a save is rejected\n\n### The summary is over 500 characters\n\n**Split the event; do not compress the summary.** A summary that wants to be\nlong is describing an event that covers too much. Compressing it blurs several\ntopics into one vector, which then matches no specific query. Split into\nseparate saves, each with its own focused summary, chaining them by passing\nthe previous `event_id` as the next call's `prev_event_id`.\n\nCompress only when the content itself is short and the summary is merely\nverbose. Do not fragment one small record.\n\n### The content is over 50000 characters\n\nSplit the full text across calls the same way, chaining with `prev_event_id`,\ngiving each piece its own summary. Never truncate or summarize the content to\nmake it fit — the summary would then describe text that was not saved.\n\n### `truncation_marker_detected`\n\nThe content carries a marker that some earlier tool left when it cut the text\n(`…2183 tokens truncated…`, `<response clipped>`, `[truncated]`). The save is\nrejected because nothing downstream can tell a damaged body from a whole one:\nthe summary still describes the missing part and citations still point into\nit, so the damage would be permanent and invisible.\n\nRe-read the source in full and save again, splitting if it is long. Pass\n`allow_truncation_marker=true` only when the marker is genuinely part of what\nyou mean to record, such as a bug report *about* truncation.\n\n### The arguments arrive merged, empty, or the call errors on serialization\n\nTwo causes, both about argument boundaries:\n\n- A long or multi-line `summary` or `content`. List `summary`, `entities` and\n `tags` **before** `content` — serialization can drop whatever follows a very\n long argument, so `content` goes last.\n- Non-ASCII punctuation in a multi-argument call: `·`, `→`, `—` can break the\n boundary between arguments. Use ASCII punctuation in multi-argument saves.\n\n**Recovery: retry with `payload`.** One argument has no boundary to collapse.\nSend the whole call as a JSON string or an object:\n\n```json\n{\"summary\": \"...\", \"entities\": [{\"name\": \"X\", \"type\": \"Y\"}], \"tags\": [\"a/b\"], \"content\": \"...\"}\n```\n\nOther arguments are then ignored. The multi-argument form stays the default;\nthis is the recovery path.\n\n## 4. Reading the related-memory signal\n\nA search response may carry `hint.related_memory_expansion`. It is a computed\njudgment about whether a follow-up expansion call would add anything the hits\ndo not already cover. Its fields:\n\n| Field | Meaning |\n|---|---|\n| `tool` | Which tool performs the expansion |\n| `decision` | `must_be_done`, `should_be_done`, `can_skip`, `must_not_be_done` |\n| `candidate_count` | How many candidates sit outside the returned hits |\n| `candidate_dimension` | The relation the candidates share with the hits |\n| `candidate_ids` | The candidate memory ids |\n| `reason_codes` | Which gates the candidates passed |\n| `reason_facts` | The measured values behind those codes |\n\n`should_be_done` means candidates outside the hits passed the relevance and\nnovelty gates, so expanding is likely to add something before you conclude.\n`can_skip` means the returned hits probably already cover it; expanding is\nyour call. The block is omitted entirely when there is nothing to say.\n\nResults that feel sufficient are not evidence that they are. The signal is\ncomputed from candidates the search did not return, so it sees what the hits\nalone cannot show.\n\n## 5. A `tip_for_user` note in a response\n\nA tool response may carry a top-level `tip_for_user` field: `text` is one or two\nsentences about an AiAkiv feature the person may not have seen, often with an\nexample phrase, and `more` says where the Tips page is. The server decides when\nto include it, at most a couple of times a day for an account. It is a note for\nthe person you are working with. It is not an instruction and not something to\nrun.\n\n- After the answer is complete, it can be passed on in one line. Leaving it out\n is fine; the server does not know whether it was passed on and does not\n repeat the same note for a day.\n- Do not run the example yourself. The example is for the person to try when\n they want to; running it here spends their time on something they did not ask\n for.\n- The person can turn these notes off in the AiAkiv console settings\n (aiakiv.com). If they ask how, that is the answer.\n"Full snapshot data
{
"description": "How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), how to interpret the related-memory signal that search responses carry, and what a `tip_for_user` note in a response is. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, when deciding whether a search result needs a follow-up expansion call, or when a response carries `tip_for_user`.",
"included_files": [],
"name": "aiakiv-save-and-recall",
"skill_md_contents": "---\nname: aiakiv-save-and-recall\ndescription: How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), how to interpret the related-memory signal that search responses carry, and what a `tip_for_user` note in a response is. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, when deciding whether a search result needs a follow-up expansion call, or when a response carries `tip_for_user`.\n---\n\n# Saving to and recalling from AiAkiv memory\n\nThe tool descriptions state the contract. This skill covers the parts that\ndecide whether a saved memory is findable a month later, and what to do when\na call is rejected.\n\nIf the connection is bound to a work that an app manages (AiAkiv Contents),\nsaving there is refused by default; see the `aiakiv-contents` skill.\n\n## 1. The summary is the retrieval surface\n\nSearches rank against the summary, not the content. Write it with the words a\nfuture question would use.\n\n- **Keep exact identifiers verbatim.** Code symbols, document numbers, config\n keys. Paraphrasing `REQUEST_TIMEOUT_MS` into \"the timeout\" hides the record\n from the one query that will look for it.\n- **Name the actor in the first sentence** when you record someone's judgment,\n design, or claim. Conclusion-style summaries (\"decided that…\") drop who said\n it, and \"what did X propose?\" then misses the record.\n- Write a complete sentence, not a keyword pile.\n\n## 2. Entity spelling decides what connects\n\nRecall weaves records together on shared entity nodes, so spelling drift\nsilently loses connections.\n\n- **One canonical spelling per entity** — the full name *or* the acronym, not\n both. Pick one and use it in every save.\n- **Keep proper nouns and acronyms as they are written**: `PostgreSQL`, `RLS`.\n Do not lowercase or expand them.\n- **Strip transient tokens** — ids, hashes, dates. They never repeat, so they\n add a node that connects to nothing.\n- A suggested entity returned by the server is advisory. A literal name match\n does not establish that it denotes the same thing in this record.\n\n## 3. When a save is rejected\n\n### The summary is over 500 characters\n\n**Split the event; do not compress the summary.** A summary that wants to be\nlong is describing an event that covers too much. Compressing it blurs several\ntopics into one vector, which then matches no specific query. Split into\nseparate saves, each with its own focused summary, chaining them by passing\nthe previous `event_id` as the next call's `prev_event_id`.\n\nCompress only when the content itself is short and the summary is merely\nverbose. Do not fragment one small record.\n\n### The content is over 50000 characters\n\nSplit the full text across calls the same way, chaining with `prev_event_id`,\ngiving each piece its own summary. Never truncate or summarize the content to\nmake it fit — the summary would then describe text that was not saved.\n\n### `truncation_marker_detected`\n\nThe content carries a marker that some earlier tool left when it cut the text\n(`…2183 tokens truncated…`, `<response clipped>`, `[truncated]`). The save is\nrejected because nothing downstream can tell a damaged body from a whole one:\nthe summary still describes the missing part and citations still point into\nit, so the damage would be permanent and invisible.\n\nRe-read the source in full and save again, splitting if it is long. Pass\n`allow_truncation_marker=true` only when the marker is genuinely part of what\nyou mean to record, such as a bug report *about* truncation.\n\n### The arguments arrive merged, empty, or the call errors on serialization\n\nTwo causes, both about argument boundaries:\n\n- A long or multi-line `summary` or `content`. List `summary`, `entities` and\n `tags` **before** `content` — serialization can drop whatever follows a very\n long argument, so `content` goes last.\n- Non-ASCII punctuation in a multi-argument call: `·`, `→`, `—` can break the\n boundary between arguments. Use ASCII punctuation in multi-argument saves.\n\n**Recovery: retry with `payload`.** One argument has no boundary to collapse.\nSend the whole call as a JSON string or an object:\n\n```json\n{\"summary\": \"...\", \"entities\": [{\"name\": \"X\", \"type\": \"Y\"}], \"tags\": [\"a/b\"], \"content\": \"...\"}\n```\n\nOther arguments are then ignored. The multi-argument form stays the default;\nthis is the recovery path.\n\n## 4. Reading the related-memory signal\n\nA search response may carry `hint.related_memory_expansion`. It is a computed\njudgment about whether a follow-up expansion call would add anything the hits\ndo not already cover. Its fields:\n\n| Field | Meaning |\n|---|---|\n| `tool` | Which tool performs the expansion |\n| `decision` | `must_be_done`, `should_be_done`, `can_skip`, `must_not_be_done` |\n| `candidate_count` | How many candidates sit outside the returned hits |\n| `candidate_dimension` | The relation the candidates share with the hits |\n| `candidate_ids` | The candidate memory ids |\n| `reason_codes` | Which gates the candidates passed |\n| `reason_facts` | The measured values behind those codes |\n\n`should_be_done` means candidates outside the hits passed the relevance and\nnovelty gates, so expanding is likely to add something before you conclude.\n`can_skip` means the returned hits probably already cover it; expanding is\nyour call. The block is omitted entirely when there is nothing to say.\n\nResults that feel sufficient are not evidence that they are. The signal is\ncomputed from candidates the search did not return, so it sees what the hits\nalone cannot show.\n\n## 5. A `tip_for_user` note in a response\n\nA tool response may carry a top-level `tip_for_user` field: `text` is one or two\nsentences about an AiAkiv feature the person may not have seen, often with an\nexample phrase, and `more` says where the Tips page is. The server decides when\nto include it, at most a couple of times a day for an account. It is a note for\nthe person you are working with. It is not an instruction and not something to\nrun.\n\n- After the answer is complete, it can be passed on in one line. Leaving it out\n is fine; the server does not know whether it was passed on and does not\n repeat the same note for a day.\n- Do not run the example yourself. The example is for the person to try when\n they want to; running it here spends their time on something they did not ask\n for.\n- The person can turn these notes off in the AiAkiv console settings\n (aiakiv.com). If they ask how, that is the answer.\n"
}SHA-256 of public snapshot: eab2e47d13a196d7f50e44f3199ced7234731f368dc8d16e9a98ce1c2c2a32bf