--- name: memoize description: Persistent cross-session memory shared with the team's other agents (memoize.xyz brain). Fire at these moments, unprompted — at session start and before any substantial task, recall prior knowledge; when the user references past work or asks what you remember, recall before answering; when a decision is made, the user corrects you or states a preference, or something works or fails, write it; and before reporting a substantial task done, write what was learned that the repo doesn't record. Local harness memory is single-machine and invisible to teammates; shared lessons belong in the brain. --- # memoize — your persistent memory Canonical setup and connection reference (MCP → CLI → link → HTTP): https://memoize.xyz/agents.txt You have a brain at https://memoize.xyz: a two-tier memory (fast working memory + consolidating long-term storage) shared across sessions, and possibly with other agents. It forgets what goes unused, strengthens what gets recalled, and distills repeated episodes into facts and how-to knowledge while you sleep. ## When this fires These are events, not a startup ritual — each one is a moment during the session where you stop and make one call. Acting on them is not optional politeness; a memory not written is a memory the whole team loses. | The moment | Do this | | ---------------------------------------------------- | ------------------------------------------------------------------------------------- | | Session starts, or a substantial task begins | `recall` the topic before you plan or assume | | User references past work, or asks what you remember | `recall` before answering — never answer from this session's context alone | | A decision is made (and why) | `remember` it | | The user corrects you, or states a preference | `remember` it — corrections are the highest-value memories | | Something worked or failed | `remember` with `"outcome": true` | | **Before you report a substantial task done** | ask "what did the team learn today that the repo won't show?" and `remember` each one | That last row is the one that gets skipped. Recall is easy to remember because you need it; the closing write has no such pressure, and skipping it is invisible in the moment and expensive later. Treat finishing a task without asking that question as leaving the task unfinished. **Your harness's own memory does not count.** A local memory file lives on one machine and is invisible to your user's teammates and their agents. If a lesson concerns the shared project, it belongs in the brain — write it there too. ## The token A brain can be scoped: one overall brain that follows the user everywhere (token at `~/.config/memoize/token`), or a per-project brain (token in a gitignored `.memoize-token` at the repo root, which wins when present). Resolve fresh on every call: TOKEN=$(cat "$(git rev-parse --show-toplevel 2>/dev/null)/.memoize-token" 2>/dev/null || cat ~/.config/memoize/token) If the `memoize` CLI is on PATH (`command -v memoize`), prefer it — it resolves the token the same way (project file first, then global), so the secret never touches a command line: memoize recall "" -k 8 --actor memoize remember "" --tags --importance 0.7 memoize hot | stats | facts | expand | pin | forget (--outcome on worked/failed lessons; --t-event for past events) No installed binary but Node is available? `npx memoize-xyz` now exposes the same everyday commands, so use `npx memoize-xyz recall ...`, `npx memoize-xyz remember ...`, and the other forms above. Raw curls are the last fallback, not the default. If neither file exists, set one up. Two equally good paths — match your user's style (some want zero questions, some want to stay in the loop; if you don't know, one short question settles it): - **Direct, no human needed**: `npx memoize-xyz init` creates a brain and writes the token file itself, so you never see the secret (`--project` scopes it to this repo and gitignores the token). - **Human-in-the-loop**: send your user to https://memoize.xyz — they create the brain in the browser (the token stays on their screen and in that browser's history, never in this chat). The page gives them a terminal command to run themselves, which finishes the whole setup without you ever seeing the token. If they paste the token to you instead, adopt it: `MEMOIZE_TOKEN='' npx memoize-xyz init`. `memoize create` (the Rust CLI) equals the direct path; the last resort is POST https://memoize.xyz/v1/brains, which returns the token ONCE. Never print a token and never commit one — before writing a `.memoize-token`, confirm `.gitignore` covers it (`git check-ignore .memoize-token`). Chat apps without a shell should use the Memoize plugin or add the canonical OAuth connector: https://memoize.xyz/mcp The consent screen lets the user choose, create, or paste a brain without giving the permanent token to the client. A private `/mcp/` connector or `/b/` capability link remains a fallback for clients without OAuth; keep either URL secret. Some link-only clients cannot construct write URLs from their own text, so use MCP whenever it is available. ## Read — recall before you assume At session start, and before starting any substantial task, recall the topic: curl -s https://memoize.xyz/v1/recall \ -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \ -d '{"query": "", "k": 8, "wait": "full", "actor": ""}' Hits arrive as `hot` (working memory, instant) and `recalled` (pulled up from long-term storage). Each hit carries `when` — the date it happened; resolve "yesterday"/"last week" phrasing against it. `wait: "hot"` answers in ~150ms when speed matters more than depth. A third array, `shared`, appears when this brain is connected to others: facts reached through those connections, each carrying `brain` (whose it is) and `sensitivity`. They stay in the brain that owns them, but a successful shared recall also places a revocable reference in this brain's working memory; `working` says whether it landed. The reference spends one local slot, never consolidates here, and disappears when access is revoked. Say where a shared fact came from if you act on it. The immediate shared `id` still belongs to its source, so don't `pin`/`forget`/`expand` that id. A later hot result has a reader-local reference id plus `reference=true`, `brain`, and `sourceMemoryId`; pin/forget on that local id changes only this brain's attention. `"scope": "self"` skips shared search and promotion. On a brain shared with other people or agents, add `"from": ""` (CLI: `--from`) to scope a recall to one writer: only that writer's raw episodes come back — consolidated facts are communal, so `from` never filters them out. `from` matches by prefix: `from=kris` matches both `kris` and `kris/*` (e.g. `kris/claude-code`). Memories written before this feature may carry generic actors (`cli`, `chat-web`, or none), so `from=` won't find those. Also useful: - `GET /v1/hot` — everything currently in working memory. On a brain connected to another at the "everything" level this also returns `shared`: rows borrowed live from those brains, each tagged with `brain`, up to 16 per directly connected source. Treat those live-shelf rows as someone else's working memory — read them, say where they came from, and don't try to `pin`/`forget` them (their ids belong to that brain, so those 404). By contrast, referenced rows inside `slots` are this brain's own attentional slots and are labelled with their original source. - `GET /v1/facts?subject=&predicate=&asOf=` — consolidated facts, time-travel with asOf - `POST /v1/expand {"memoryId": "..."}` — pull a memory's neighbourhood into working memory ## Write — when something merits keeping Write a memory when, and only when: - a **decision** was made (and why) - the user stated a **preference** or correction - something **worked or failed** — add `"outcome": true`; lessons encode more strongly and consolidate into procedural how-to memory - you learned a **durable fact** about a person, project, or system that is not derivable from the repo, files, or git history And once more at the end of every substantial task, as a checkpoint before you report it done: re-read what the session actually taught — the correction you were given, the approach that failed twice before the third worked, the constraint nobody had written down — and write each one. Two or three memories is a normal harvest for a real task; zero usually means the checkpoint was skipped, not that nothing was learned. Never submit payment-card data, protected health information, government identifiers, passwords, API keys, private keys, tokens, or authentication secrets. Memoize rejects obvious matches before processing, but no automated filter is perfect. Do NOT write routine edits, transient state, or facts the brain already holds (recall first if unsure). A shared memory cannot be unseen by the people and agents who share it. curl -s https://memoize.xyz/v1/remember \ -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \ -d '{"text": "", "tags": [""], "actor": "", "importance": 0.7}' Writing well: - **One fact per call**, as a short standalone sentence a stranger could use. - `actor`: compose `/` (e.g. `kris/claude-code`; shell agents can get the username via `$(whoami)`) so writes stay attributable per person and per harness. The brain keeps a per-actor working set, so name yourself consistently. - `t_event` (epoch ms): set it when the event has a real time that is not now. - `importance` 0..1 (default 0.5); reserve >0.8 for things that must survive. - `"outcome": true` on worked/failed lessons. ## Maintain - `POST /v1/pin {"memoryId": "...", "on": true}` — protect from eviction - `POST /v1/forget {"memoryId": "..."}` — remove (user-requested only) - `GET /v1/stats` — slots used, memory count, quota ## Extending this for one project `npx memoize-xyz init` rewrites this file to the published version, so edits here are lost on the next run. Project-specific memory rules — which tags to use, what this team always wants remembered — belong in that project's own agent instructions (`CLAUDE.md`, `AGENTS.md`), which reference this skill and survive updates. ## How this memory behaves Working memory is bounded (slots evict by decay and focus); nothing is lost on eviction — it moves to long-term storage and returns on recall. Recalling strengthens; unused memories fade. Source-owned hot references are the exception: eviction drops only the reader's cache because the durable fact still lives in its source brain. They never consolidate in the reader. Every six hours, a sleep cycle consolidates owned episodes into facts (with provenance, contradiction handling, and time-validity) and procedures. Limits: 8KB per memory, 10k writes/day.