# memoize — universal instructions for agents Canonical copy: https://memoize.xyz/agents.txt Memoize is persistent, shared memory for agents and apps. A brain has a fast working tier and consolidating long-term storage. One token identifies and authorizes one brain; there are no accounts. If a user sent you here, use the first connection method below that your environment supports. They are ordered from easiest and most reliable to most manual. Do not ask the user to paste raw API requests when a connector or CLI is available. ## 1. Native plugin — easiest for Codex, ChatGPT, and Claude Code The Memoize plugin bundles the MCP connection and the skill that teaches an agent when to recall and remember. Its source is here: https://github.com/harrisonford/memoize/tree/main/plugins/memoize For Claude Code, install it from the repository's marketplace: claude plugin marketplace add harrisonford/memoize claude plugin install memoize@memoize-plugins For Codex and ChatGPT, find "Memoize" in the plugin directory once listed, or install/upload the same `plugins/memoize` directory during development. The plugin connects to the canonical OAuth-protected MCP server below. ## 2. MCP connector — easiest universal connection Add this URL as an MCP server/connector: https://memoize.xyz/mcp The client discovers OAuth 2.1 automatically. The consent screen lets the user choose a brain already saved in this browser, create one, or paste an existing brain token once. The client receives short-lived, scoped credentials rather than the permanent brain token. Clients that cannot complete OAuth but can securely store a private connector URL may use: https://memoize.xyz/mcp/ Append `?as=/` to label writes, for example `?as=kris/claude`. The connector exposes `recall`, `remember`, `stats`, and `forget` tools and supplies the usage policy automatically. Clients that can set authorization headers may send the token directly as `Authorization: Bearer ` to the canonical `/mcp` URL. The token in either form is the brain: never print it, log it, commit it, or send it anywhere except memoize.xyz. Use `forget` only when the user explicitly asks to delete a memory. ## 3. Unified CLI — easiest for coding agents with a shell Set up a project brain (recommended inside a repository): npx memoize-xyz init --project Or omit `--project` for one global brain shared across repositories. `init` creates or adopts a brain, saves the token with mode 0600, gitignores a project token, installs the skill, and verifies the connection. Re-run it to refresh a stale skill. Diagnose an existing setup with: npx memoize-xyz doctor The same zero-install CLI handles everyday memory operations: npx memoize-xyz recall "" -k 8 --actor npx memoize-xyz remember "" --tags --importance 0.7 --actor npx memoize-xyz hot npx memoize-xyz stats npx memoize-xyz facts --subject --predicate --as-of npx memoize-xyz expand npx memoize-xyz pin [--off] npx memoize-xyz forget `recall` also supports `--wait hot|full`, `--tags a,b`, and `--from `. `remember` also supports `--outcome` and `--t-event `. All commands support `--token-file`, `--base-url`, and `--actor` where relevant. If `memoize` is installed on PATH (the npm package exposes that alias when installed, and a native Rust CLI also exists), use the shorter equivalent: memoize recall "" Token resolution is fresh on every command, in this order: 1. `--token-file ` 2. `MEMOIZE_TOKEN` 3. nearest `.memoize-token` walking upward from the current directory 4. `~/.config/memoize/token` ## 4. Capability link — for chat clients that can open links but not MCP Open the personalized brain page from the user's handoff: https://memoize.xyz/b/ It shows recent working memory and links for recall, remember, and stats. Some chat clients cannot construct a new URL containing their own query or memory text; in those clients reading may work while writing does not. Say so honestly and use MCP instead if the client supports it. ## 5. HTTP API — universal fallback Only use raw HTTP when no connector or CLI is available. Resolve the token in a completed shell statement before expanding it in the next command: TOKEN=$(cat "$(git rev-parse --show-toplevel 2>/dev/null)/.memoize-token" 2>/dev/null || cat ~/.config/memoize/token) Recall: curl -sS https://memoize.xyz/v1/recall \ -H "Authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"query":"","k":8,"wait":"full","actor":""}' Remember: curl -sS https://memoize.xyz/v1/remember \ -H "Authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"text":"","tags":[""],"actor":"","importance":0.7}' Other endpoints: GET /v1/hot GET /v1/stats GET /v1/facts?subject=&predicate=&asOf= POST /v1/expand {"memoryId":"..."} POST /v1/pin {"memoryId":"...","on":true} POST /v1/forget {"memoryId":"..."} Create a brain only when no token exists: POST /v1/brains -> {"token":"..."} The token is shown once. Prefer `npx memoize-xyz init`, which writes it safely. ## When to use memory - At session start and before a substantial task: recall the topic before planning or assuming. - When the user references past work or asks what you remember: recall before answering. - When a decision is made and why, the user states a preference or correction, or you learn a durable fact not derivable from repository history: remember one short, standalone fact. - When something worked or failed: remember it with `outcome=true` or `--outcome`; lessons consolidate more strongly into how-to knowledge. - Before reporting a substantial task complete: ask what the team learned that the repository will not show and save each durable lesson. Never submit payment-card data, protected health information, government identifiers, passwords, API keys, private keys, tokens, or authentication secrets. Memoize rejects obvious matches before model processing or storage, but no automated filter is perfect. Do not store routine chatter, transient state, or facts the brain already holds. Recall first when unsure. One fact per write. Use actor names like `/` so shared brains retain clear provenance. ## Reading results Recall returns `hot` (working memory) and `recalled` (long-term matches). Each hit carries `when`; resolve relative phrases such as "yesterday" against that date. A `shared` array may contain facts reached from connected brains; each hit names its source brain and remains owned there. A successful shared recall also places a revocable reference in the reader brain's working memory; `working` reports whether that happened. The reference spends one reader slot but never enters its long-term store or changes the source fact. On a later recall it appears in `hot` with `reference=true`, `brain`, and `sourceMemoryId`. The id in the immediate `shared` result still belongs to the source: do not pin, forget, or expand it through the reader. A later referenced `hot` result carries the reader-local id; pinning or forgetting that id changes only the reader's attention. Use `scope=self` to skip shared search and promotion. `from=` filters raw episodes by writer prefix (`kris` matches `kris` and `kris/*`); consolidated facts remain communal. `expand` reads the durable tier. A memory returned by `remember` may need one drain cycle (normally about 10 seconds) before that same id can be expanded. ## How memory behaves Working memory is bounded. Unused memories fade into long-term storage rather than disappearing and return when recalled. Recalling strengthens locally owned memories; source-owned references track reader-local strength and disappear on revocation without consolidating. An `everything` connection also exposes up to 16 live rows per directly connected brain; these shelves cost the reader no slots. Limits: 8KB per memory and 10,000 writes per day. This document is the single universal explanation. Persistent harness skills may add trigger wording for their environment, but should point back here for setup methods and command reference.