recoil

recoil — operational memory for this repo

recoil is a local CLI backed by a plain-text store (.recoil/store.tsv). It remembers what went wrong here before — a failed command, a revert, a correction — and surfaces it when the same thing is about to happen again. Matching is deterministic keyword overlap: no embeddings, no network. The loop is two moves: recall before touching files, encode after a surprise — and act on whatever fires. Running recall is safe to attempt even when unsure recoil is installed — if it isn't on PATH the command simply isn't found, and nothing is harmed.

Decide in one read

• Starting a task that will change files, or about to run a test suite, build, or migration? Run recall FIRST. Once per task or area is enough — no need to re-run before every edit to the same files.
• Just got surprised — a correction, an unexpected test/build failure, a revert? encode it BEFORE moving on, while the cue tokens are still in front of you.
• Pure read-only question or exploration that changes nothing? Skip it.

Do not deliberate over whether a moment "counts." If a file change or a test/build is next, the answer is recall.

Before changing code or running tests — recall, then ACT

One command. Pass the files in play; add a few words of intent if you have them:

recoil recall --files src/runner.cs,tests/EditModeTests.cs --top 5
echo "editing the EditMode runner" | recoil recall --min-overlap 2   # no file yet? describe the task

(--min-overlap 2 keeps prose from firing lessons on one coincidental shared word. After a failure, pipe the error text in the same way — the failure may already be remembered.)

A hit looks like this — read it and act on it (hits rises for each day it keeps getting recalled, so a high count means it keeps mattering):

>> Assert.ThrowsAsync hangs the EditMode runner; use a sync assert instead
   [test-fail w=2 hits=3] matched: editmode assert throwsasync runner

Act on what fires — this is the point, not a box to tick. For each hit, say in one line what it changes: avoid the known-bad path, or name the specific token that differs and why the lesson doesn't apply here. "Probably fine" is not an answer. No output means nothing prior matched — clear to proceed. Recalling a lesson also renews it against decay, which is what keeps the useful ones alive.

recoil guard is the same matcher in warn-only form for hooks (git pre-commit, the plugin's pre-edit hook). You normally don't run it by hand — but treat any been burned here before line that appears as a real hazard: it fires only on memories of things that actually went wrong, never plain notes. Do not proceed past one without addressing it.

After a surprise — encode the lesson

Surprise test: encode only when your model of the repo was wrong — you predicted X and got Y. A correction, an unexpected failure, or a revert qualifies. A self-inflicted typo or a compile error you immediately understand is routine — skip it. Encode when the failure revealed something non-obvious about this repo (a hidden dependency, config in an unexpected place, a tool that behaves unusually here). General best practices and routine notes do NOT belong here — they go in normal docs.

Match the trigger to the event — higher weight surfaces sooner:

What just happened (the surprise)	--trigger	weight
User corrected a non-obvious choice ("no" / "that's wrong" / "don't do that")	correction	3
A change was reverted or git reverted	revert	2.5
A test or build expected to pass failed	test-fail	2
A command exited non-zero unexpectedly	error	1.5
Something worth keeping, recorded by hand	manual	1

Keep --gist to one actionable line. Make --cue the tokens the next occurrence will share — this event's real file names, error text, and system names. Warnings need ≥2 overlapping cue tokens to fire, and the matcher drops stopwords and single-character tokens, so a one-word or generic cue silently never recalls again. (Encoding an identical gist+cue twice reinforces the existing lesson instead of duplicating it.)

• Bad: --cue "bug" — one generic token; never re-fires.
• Good: --cue "editmode assert throwsasync runner hang" — the tokens the next hang will share.

Worked examples — fill the cue with this surprise's own tokens:

recoil encode --trigger correction \
  --gist "Config lives in app.toml, not config.yaml — yaml is the old path" \
  --cue  "config app toml yaml settings load"

recoil encode --trigger test-fail \
  --gist "Don't name a Unity folder Build/, .gitignore untracks it" \
  --cue  "unity build folder gitignore"

recoil encode --trigger revert \
  --gist "Bumping the proto version breaks the v1 clients still in prod" \
  --cue  "proto version bump v1 client breaking"

Or let a command record its own failure by wrapping it — but note watch always tags the record error (weight 1.5), even for a test command. When the weight matters, encode manually with --trigger test-fail:

recoil watch -- go test ./...

Cross-tool note

• Claude Code (plugin installed): hooks do part of the loop for you — a session-start digest of the strongest lessons, a recall against each user prompt, and a warn-only guard before Edit/Write/MultiEdit. Lessons and warnings appear in context without you invoking anything; your job is to ACT on them, run recoil recall --files ... yourself once you know which files are in play (the prompt hook can't know that), and encode surprises.
• Codex (or any tool without hooks): nothing is automatic. Recall before changing anything and encoding after surprises are entirely your responsibility.

An auto-recorded revert (from the git post-commit hook) has no human-written gist, so still encode the actual lesson — what the reverted change got wrong is the valuable part the bare hook can't capture.

Setup and housekeeping

Once per repo: recoil init. If the binary is missing from PATH, see the README install steps. Housekeeping (not part of the per-edit loop):

• recoil list — show everything stored, with ids, strength, and age.
• recoil forget <id> — delete one lesson (wrong, stale, or too noisy).
• recoil decay — forget faded lessons (strength halves every ~30 unused days; recall renews it, so the ones that keep mattering stay).
• recoil hook --install — wire the git pre/post-commit guard and revert recorder; won't overwrite existing hooks. The post-commit recorder only captures commits whose subject starts with Revert.