--- name: stash-memory description: > Permanent memory for this agent, served by the Stash API (OptMem over HTTPS). Use at the START of every session to wake your memory before any other work; whenever something with lasting effect happens, to note it; whenever a response carries a "nap", to compress before your next action; and whenever the past matters, to recall or zoom. Requires STASH_URL and STASH_TOKEN in the environment. Contains no secrets and never stores the token. --- # Stash: your permanent memory Your memory outlives every session, compaction, model and vendor change. Without it you do not know who you are, or what was decided and tried. It lives behind an API; you hold the only key. **Environment contract** — both must be set; if either is missing, tell your human and continue without memory rather than guessing: - `STASH_URL` — e.g. `https://stash.sanctumx.ai` - `STASH_TOKEN` — your capability token (`stash1_...`). It is the only key to your memory: the server cannot read a single memory without it. Never print it, never write it to a file, never send it anywhere except the `Authorization` header of calls to `STASH_URL`. Every call below is plain HTTPS. `$H` means: ```sh H="Authorization: Bearer $STASH_TOKEN" ``` ## At session start: wake (mandatory, before any other tool call) ```sh curl -s -H "$H" "$STASH_URL/wake" ``` Read every line, oldest first. Lines look like `#12 2026-08-25 ` (verbatim) or `#0-15 ` (a compression you wrote earlier). Handle the three response shapes: 1. `"awake": true` — you are awake. If the response carries a `"nap"`, do it now (see below). 2. `"next": {"part": P, "T": T}` — the memory arrives in parts. Keep calling `GET $STASH_URL/wake?part=P&T=T` until `"awake": true`, reading every part. Use the returned `T` verbatim — it pins the snapshot so nothing shifts between parts. 3. HTTP 409 — the context needs a summary that does not exist yet. The body carries the `"nap"` to do. Do it, then wake again. Repeat until awake. ## While working: note (mandatory discipline) ```sh curl -s -H "$H" -X POST "$STASH_URL/note" \ -d '{"text":""}' ``` Note whenever you learn something new or something worth keeping happens: a task worth real effort, a fact or insight your human teaches you, anything you learn about their life (even indirectly), any event of lasting effect. One line, at most 280 bytes — accented characters cost 2. Do not register redundant memories: what wake showed you, you already know. **The server accepts duplicates without complaint — the judgment not to write them is yours alone.** The log is append-only and permanent; write like it. ## When a response carries a "nap": compress before your next action `note`, `wake`, and `nap` responses may include a `"nap"` object with a `"block"` (like `"0-15"`), a `"prompt"` showing what to compress, and a `"remaining"` count. Write the summary yourself — keep what has lasting effect, drop what does not, invent nothing — and submit it: ```sh curl -s -H "$H" -X POST "$STASH_URL/nap" \ -d '{"block":"0-15","summary":""}' ``` The response may carry the next nap; keep going until `"nap": null`. Blocks settle strictly in order — always use the block id the API gave you, never invent one. `POST $STASH_URL/nap` with `{}` asks what is due. Two things that look wrong but aren't: `"remaining"` counts the compressions still due *after* this one — `remaining: 0` still means DO this nap, it is the last in the queue, not an idle signal. And under the wake budget (`WAKE_LINES`, default 96) wake arrives fully verbatim even while naps come due on every other note — a due nap is tree-building for your future, not a sign wake is broken. Do it anyway; the log you save is your own. (Curious about your budgets? `GET $STASH_URL/config` — read scope — shows `WAKE_LINES`, `ENTRY_CHARS`, and the paging sizes.) ## When you need an old memory: recall, or navigate ```sh curl -s -H "$H" "$STASH_URL/recall?q=" # url-encode the regex ``` Recall searches every memory ever recorded, word for word — the verbatim log, never the summaries. If `"truncated": true`, narrow the regex. Your memories also form a binary tree: `#0-1`, `#2-3` exist as one-line summaries, pairs of those as `#0-3`, and so on — every `#a-b` line wake prints is one node of it. Open any node into its two halves, down to the raw memories: ```sh curl -s -H "$H" "$STASH_URL/zoom?block=-" ``` Prefer zoom when you know roughly *when*; prefer recall when you know roughly *what*. ## Rare: a summary is wrong If a summary you wrote misrepresents the past, drop it — the log is untouched and the next naps rebuild it: ```sh curl -s -H "$H" -X POST "$STASH_URL/forget" -d '{"block":"-"}' ``` Then answer the naps it hands back. Use sparingly; forgetting is for errors, not regrets. ## Errors, briefly - `401` — the token is missing, malformed, or revoked. Stop and tell your human; do not retry in a loop. - `403` — your token's scope is too low for that operation (a `read` grant cannot note). Say so. - `409` on wake — not an error, and never an auth failure: it is work. Rare by design — it fires only once the log exceeds `WAKE_LINES` while blocks sit unsettled, so an agent that naps on time may never see one. Do the nap it carries, then wake again. - `400 Too long` — your line exceeds 280 bytes. Compress it further. ## Never - Never edit memory by any route other than these calls. The log is append-only; nothing runs in the background; the API manages the rest. - Never note secrets, tokens, or credentials — memory is permanent. - Never expose `STASH_TOKEN` in output, files, or notes. ## If you're a subagent: skip everything above Parallel sessions holding this token are all you, and may all write memories. A subagent is not: it must never call the stash, because it cannot judge what is already known, and its notes would arrive duplicated and incorrectly. When you spawn one, write: `You are a subagent. Don't touch the memory API.` --- ### For the human installing this Mint the identity once (`POST $STASH_URL/init`, with `X-Init-Key` if the server locks init); the token is shown exactly once — store it in your secret manager and set it as `STASH_TOKEN` in the agent's environment. This skill file holds no secrets and is safe to version and share. Skills load on demand, and waking must happen at session start — so pair this skill with one always-on line in the agent's `AGENTS.md` / `CLAUDE.md`: > **Memory (mandatory):** you have permanent memory via the stash-memory > skill. Wake it before any other tool call, in every session, and follow > its discipline throughout.