CLI reference

Install

npm install -g memorable-cli

Setup + consent

Remember

memorable ingest - <<'JSON'
{ "session_id": "run-183",
  "task_description": "rotate the TLS cert",
  "harness": "my-orchestrator",
  "tool_calls": [
    { "name": "shell", "input": { "command": "certbot renew" },
      "result": { "ok": true } } ] }
JSON

Recall + inject

Chaining

A long task is rarely a repeat. It is usually a new arrangement of things you have each done before, and retrieval cannot express that — ask for the closest memory and you get one procedure and a shrug for the rest. So recall picks between returning one procedure and assembling several into an ordered plan, and says which it picked and why.

The order 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; steps that share no dependency are marked as safe to run in parallel.

$ memorable chain "add the POST refunds endpoint and then cover it with tests"
4 procedures - 3 artifact edges - 2 segment(s) - coverage 100%
   1. [bridge] Create the refunds database migration
         verified by: bun run migrate
   2. [bridge] Add the refund model
         needs: migrations/003_refunds.sql
         verified by: bun test models
   3. Add the POST refunds endpoint with validation
         needs: src/models/refund.ts
         verified by: bun test routes
   4. Cover the refunds endpoint with tests
         needs: src/routes/refunds.ts
         verified by: bun test refunds

The two steps marked [bridge] match nothing in the prompt. They are there because a later step reads what they create, and without them the plan does not run. 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.

Chaining is per-project: dependencies only form between procedures that touched the same files, so run it where you work.

Inspect

Revisions + pruning

A stored procedure is not a fact. It is a claim that a way of doing something worked once, and claims age: the code moves underneath them, and better ways show up. Three things keep the store honest, and none of them need you to think about it.

A trace that cannot help is refused

An empty session, or one that only read and searched without changing anything, is not stored — there is nothing in it to replay. Refusals are appended to ~/.memorable/rejected.jsonl with a reason rather than dropped silently, because a filter you cannot inspect is indistinguishable from one that is not running.

A better way does not destroy the working one

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 worse second attempt never overwrites a first one that works. Recall surfaces exactly one revision per task: a new one 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 — whether a procedure helped you is local telemetry, and keeping it local means recall never has to write anything.

For agents

Telling a coding agent "use memorable" is enough: every step above is a plain CLI call it can run itself. To make that durable, drop the instructions into your project:

memorable agents-md >> AGENTS.md

Measured

Against the same tasks run without memory, n=25 per arm, p < 0.015.

agent turns   -18% to -29%
input tokens  -13% to -17%
pass rate     100% (125/125 runs)
injected size ~293 tokens
vs a 62KB loaded skill (n=10): +55% tokens, 0% turns