
recoil
Operational memory for coding agents: recall past mistakes before you act, encode the lesson when something goes wrong.
- version
- 1.1.0
- GitHub stars
- 6
Install
/plugin install recoil@recoilRun it inside Claude Code after adding the marketplace with /plugin marketplace add EclipseElips/recoil.
Contents
Discovered from sourceSkills 1
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?
encodeit 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 withRevert.
Sponsors
Details
- Marketplace
- EclipseElips/recoil
- Author
- EclipseElips
- Category
- Community
- License
- MIT
- Keywords
- memory, operational-memory, dev-workflow, coding-agent