Update to AiAkiv Memory

{
  "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.",
  "included_files": [],
  "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"
}