memorable

Procedural memory for coding agents, stored on your own machine.

When an agent finishes a task, memorable extracts what actually happened — files changed, commands that verified the work, real outcomes — into a stored procedure. When a similar task comes back, memorable recall surfaces it, so the agent skips the diagnosis it has already done. Extraction is deterministic: the procedure is derived from the trace, not written by a model. A small model runs twice on the way through, to title the procedure and to judge whether it is worth keeping, and neither can change the steps. Your procedures live on your machine; the service keeps the prompt line and the steps so the dashboard can render them.

Start here — nothing installed yet

npx memorable-cli login      # opens a browser, links this machine to your workspace
memorable install-hooks      # Claude Code: recall runs on every new prompt
memorable enable             # explicit consent — until you run this, nothing is stored
                             # AND nothing is sent for extraction

npx fetches the package on first use, so there is nothing to install before that first line. To get the short memorable name on PATH afterwards:

npm install -g memorable-cli

Running Codex, Cursor or a custom harness instead of Claude Code? memorable setup writes the instructions into AGENTS.md instead of installing a hook. Storing in your own gbrain database? memorable init gbrain. Both need login first.

Local Codex trace capture (no account required)

npm install -g memorable-cli
memorable install-hooks codex

Restart Codex and approve the new hooks when /hooks asks you to review them. Each completed turn is written locally to ~/.memorable/traces/<session-id>/<turn-id>.json. The capture contains the prompt, minimized tool inputs, explicit tool outcomes, and Codex's final agent response in agent_output; command output, file contents, and patch bodies are not retained. Agent output is capped at 256 KiB and marked with agent_output_truncated: true when capped. This checkpoint only records trace JSON—it does not process, upload, or store a procedure. Set MEMORABLE=0 before starting Codex to disable capture without removing hooks.

Quickstart

memorable login       # once per machine — a key that belongs to your workspace
memorable enable      # explicit consent — until you run this, nothing is stored
                      # AND nothing is sent for extraction

# store a procedure from any agent's trace:
memorable ingest trace.json

# find it when a similar task returns:
memorable recall "rotate the TLS cert"
memorable show <slug>


# a task that is several things at once, assembled from several procedures:
memorable chain "add the refunds endpoint and then cover it with tests"

# see what is stored and clean it up:
memorable list                    # what recall would use, and whether it has helped
memorable prune --superseded      # drop revisions that had their turn and lost

Checking state

memorable status         # backend, consent, how many procedures are stored
memorable doctor         # every integration point, asserted — including whether
                         # semantic recall is actually configured, not just
                         # whether the API returned 200
memorable install-hooks  # add the Claude Code prompt hook so recall injects
                         # automatically at the start of a session
memorable setup          # enable + AGENTS.md in one shot (after `login`)

Revisions

Recording the same task twice is safe. Identical steps refresh the stored revision in place; a genuinely different approach is kept beside it as a new revision, so a better way can be learned without destroying the one that already works.

Recall surfaces one revision per task: a new revision gets a short trial window, and after that the one with the better track record wins. That record comes from the loop itself — when a recalled procedure is injected into a session, how that session ends is credited back to it. The evidence lives in ~/.memorable/stats.json on your machine, never in the store, so recall never writes to your brain and nothing about your outcomes is shared.

memorable list prints the slugs, which revision is preferred, how often each was recalled, and how often the session went well afterwards. --all shows every revision; --json is scriptable.

Removing procedures

memorable prune <slug>          # remove one
memorable prune --stale         # ones whose files no longer exist in this tree
memorable prune --superseded    # revisions that were tried and lost
memorable prune --dry-run       # preview, with any of the above

Pruning works in every consent mode, including forget/deny: a store you cannot empty is not one you can trust. On the gbrain backend this rides gbrain's own delete_page, so removal is a soft delete, recoverable for 72 hours.

A trace is also refused up front when it could not possibly help — an empty session, or one that only read and searched without changing anything. Refusals are logged to ~/.memorable/rejected.jsonl with a reason rather than dropped silently.

Backends

• local (default) — procedures live in ~/.memorable/procedures.jsonl. Works anywhere Node runs; no other software required.
• gbrain — memorable init gbrain stores procedures in your existing gbrain database instead, and unlocks automatic session capture (memorable record and the session-end relay). If your gbrain has an embedding provider configured, it is used for semantic recall instead of the extraction API's. Requires a gbrain install and Bun on PATH; database commands re-exec under Bun automatically.

How recall matches

Three tiers, fused by reciprocal rank: an exact match on a stored file path or command, a lexical match on shared tokens, and a semantic match on meaning. Semantic is lazy — it only runs when the first two find nothing, so most queries stay deterministic and offline.

Semantic recall needs vectors. Procedures are embedded by the extraction API (bge-m3, 1024 dimensions, run inside Memorable's own Cloudflare account, so the task title never reaches a third-party vendor). Only the one-line task title is embedded, never your file contents or conversation.

If no embedding provider is reachable, procedures are still stored and recall still works on exact and lexical matches — but the CLI says so on every write rather than degrading quietly, and memorable doctor reports the semantic tier as unavailable.

Switch anytime by re-running memorable init / memorable init gbrain — the sign-in from login carries over.

Chaining: when one procedure is not the answer

A long task is rarely a repeat. It is usually a new arrangement of things you have each done before. Retrieval cannot express that — ask for the closest memory and you get one procedure and a shrug for the rest.

So memorable recall decides between two modes, and says which it picked:

• single — one stored procedure answers the prompt.
• chain — several are assembled into one ordered plan.

It chains when one procedure provably cannot answer: either the prompt is several subgoals matching different procedures, or the best match needs a file that another stored procedure is the one that creates.

The ordering is not guessed. A procedure that writes a file and one that reads it are a dependency, in that direction, and both facts are already in the recorded steps. Steps come out in dependency order, and steps that share no dependency are marked as safe to run in parallel.

Two things fall out of that, and they are the point of the feature:

• A step you never asked for. If the endpoint you asked about reads a file only the migration creates, the migration is inserted and labelled — it matched nothing in your prompt, and without it the plan does not run.
• An honest gap. Anything memory cannot cover is printed as not covered by memory and excluded from the claimed coverage, rather than papered over with the nearest vaguely-similar procedure.

memorable chain "<task>" runs it directly; --render shows the exact block that would be injected, --json is scriptable. memorable recall --single and --chain force either mode.

Chaining is per-project. Dependencies only form between procedures that touched the same files, so run it where you work — a store spanning unrelated projects has nothing to connect.

What leaves your machine

Everything is processed locally except extraction, which is one HTTPS call. That call carries the tool NAMES, a fixed allowlist of argument fields (command, file_path, pattern, url, query and a few siblings), and outcomes — with your home directory collapsed to ~, and emails, credential-shaped strings and long hex digests redacted before sending.

Edit bodies and file contents never leave the machine. One line of your conversation does: task_description is the first substantive line of the prompt, scrubbed and cut to 200 characters, and it is what recall matches against. The service stores that line and the extracted steps in Postgres, so the dashboard can render them; it does not store the corpus, which is sent empty. Embeddings, titling and the admission judge all run inside Memorable's own Cloudflare account, so nothing reaches a third-party vendor.

Is it encrypted?

Plainly, because this is the question that decides whether you can put it on a work machine.

• On your machine. Every procedure is encrypted at rest with AES-256-GCM, one sealed line per procedure, and the file is 0600 on top of that. The key is not kept beside it: on macOS it lives in your login Keychain, and where there is no keychain it falls back to ~/.memorable/store.key at 0600. Set MEMORABLE_STORE_KEY to 64 hex characters to hold your own key instead. Copying ~/.memorable to another machine gets you ciphertext. memorable status names which of the three your key came from, and says KEY MISSING rather than quietly showing an empty list if the store is sealed and the key is gone. Procedures written before 0.5.13 stay readable as plaintext and are sealed the next time the file is rewritten.
• In transit. One HTTPS call per extraction. Nothing else is sent.
• On the service. The task line and the extracted steps are stored in Postgres, encrypted at rest by the database provider, and reachable by your workspace's keys. This is not end-to-end encrypted: the dashboard renders your procedures, so the service can read them. If that is not acceptable for a given repository, do not enable capture there.
• On the service, application-level: a workspace's own embedding vendor key is stored wrapped, written once at setup with an audit row.

If you need the store somewhere other than your home directory, or you need it to stay entirely on your own infrastructure, memorable init gbrain and memorable init qm put procedures in a database you run.

Consent model

Fail-closed. unset means deny: until you run memorable enable, nothing is written. disable makes memory read-only; forget denies everything, recall included. Recalled procedures are injected as guarded reference data — control-character-stripped, size-capped, and explicitly marked as data, not instructions.

For agents

memorable agents-md >> AGENTS.md drops self-contained instructions into a project so any coding agent can drive the whole loop itself — or memorable setup does init + enable + AGENTS.md in one shot.

Docs: https://www.memorable.sh