recoil

> irm https://recoil.sh/install.ps1 | iex

Installs to %LOCALAPPDATA%\recoil and adds it to the user PATH. irm https://recoil.sh/uninstall.ps1 | iex removes it and keeps your memories; pass -Purge to delete the database too.

Every release ships recoil_<tag>_<os>_<arch>.tar.gz for linux/x86_64, linux/arm64, darwin/arm64 and darwin/x86_64, a .zip for windows/x86_64, and one checksums.txt covering all of them.

$ TAG=$(curl -fsSL https://api.github.com/repos/1broseidon/recoil/releases/latest | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4)
$ OS=$(uname -s | tr '[:upper:]' '[:lower:]')
$ ARCH=$(uname -m); [ "$ARCH" = "aarch64" ] && ARCH=arm64
$ curl -fsSLO "https://github.com/1broseidon/recoil/releases/download/${TAG}/recoil_${TAG}_${OS}_${ARCH}.tar.gz"
$ curl -fsSLO "https://github.com/1broseidon/recoil/releases/download/${TAG}/checksums.txt"
$ grep "recoil_${TAG}_${OS}_${ARCH}.tar.gz" checksums.txt | shasum -a 256 -c -
$ tar xzf "recoil_${TAG}_${OS}_${ARCH}.tar.gz" && install -m755 recoil ~/.local/bin/recoil

$ CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" go install github.com/1broseidon/recoil@latest

A binary built without FTS5 does not work; there is no degraded fallback.

$ git clone https://github.com/1broseidon/recoil && cd recoil
$ make build      # ./recoil
$ make install    # $GOPATH/bin/recoil

recoil is one of the chain.sh tools. One command installs the set:

$ curl -fsSL https://chain.sh/bootstrap.sh | sh

Marks the project (.recoil/project.json), indexes its docs, and installs agent hooks.

wake [query] prints up to --max-chars (default 1600) of memory in lanes, current decisions first. --include-decisions appends a claim-keyed decision trail, --explain adds per-result score components, --minimal prints tab-separated rows. The filters below apply to search, list and forget as well.

Writes a structured handoff under the handoff.latest claim key, superseding the previous one. --next-step, --decision, --constraint and --open-question are repeatable; a free-text summary can come as an argument, from --file, or from stdin with --file -.

$ recoil handoff --agent claude --next-step "Land the per-project cache path, then re-run the cold-start benchmark" --open-question "Prune the cache by age or by size?"
---
id: mem_yr2bckupv2ebyrt3hki6g343ch
scope: project
scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
role: handoff
claim_key: handoff.latest
supersedes: ""
auto_superseded: ""
publish_mode: off
publish_published: 0
publish_queued: 0
publish_duplicate: 0
publish_failed: 0
publish_skipped: policy
---
## Next Steps
- Land the per-project cache path, then re-run the cold-start benchmark

## Open Questions
- Prune the cache by age or by size?

The role is inferred from decision, constraint, preference and handoff signals in the text, and the inference is reported with its confidence. Override it with --role, give a family with --claim-key, attach provenance with --source-path and --source-ref, read long content with --file. Links use --supersedes and --superseded-by.

decide is remember for decisions. The claim key is required; a new decision automatically supersedes the previous active one in the family (--no-supersede keeps both). --stance prefers|rejects|requires|forbids and --subject describe what the decision is about so check can spot a contradicting request.

$ recoil decide --claim-key cache.backend --stance prefers --subject "parser cache backend" --agent claude "Parser cache moves to a per-project SQLite file under .cache/ so worktrees stop sharing one cache. Still SQLite, still no daemon."
---
id: mem_f3epegqcib4qepn47onte7nri2
scope: project
scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
created: 2026-09-21T06:33:07Z
role: decision
validity: active
claim_key: cache.backend
stance: prefers
subject: parser cache backend
predicate_status: unknown
supersedes: mem_7vda2sxdlkgrurmicljaq5fq6k
superseded_by: ""
auto_superseded: mem_7vda2sxdlkgrurmicljaq5fq6k
duplicate: false
publish_mode: off
publish_published: 0
publish_queued: 0
publish_duplicate: 0
publish_failed: 0
publish_skipped: policy
---
Parser cache moves to a per-project SQLite file under .cache/ so worktrees stop sharing one cache. Still SQLite, still no daemon.

A decision can carry a predicate for when it applies: --valid-until <date> is deterministic, --holds-while "<condition>" is semantic, --predicate key=value,… adds structured fields, and --recheck "<question>" is what to ask the operator when the predicate needs review. check reports the result as predicate_status.

Creates the replacement, marks the old memory superseded, and links both. The claim key and role default to the old memory's.

$ recoil supersede mem_jtijf5wmyvvdoehp23sbjs3szu --agent claude "The parser cache is keyed by file content hash plus parser version, so a parser upgrade invalidates stale entries."
---
action: supersede
old_id: mem_jtijf5wmyvvdoehp23sbjs3szu
new_id: mem_w5seoglca7u74isihepwxxag4t
scope: project
scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
claim_key: ""
old_validity: superseded
new_validity: active
duplicate: false
publish_mode: off
publish_published: 0
publish_queued: 0
publish_duplicate: 0
publish_failed: 0
publish_skipped: policy
---
The parser cache is keyed by file content hash plus parser version, so a parser upgrade invalidates stale entries.

mark <id> sets --validity (active, historical, rejected, superseded, stale, unknown), --claim-key, --stance, --subject, and the --supersedes / --superseded-by links.

forget <id> --reason "<why>" tombstones one memory: it stays in the store, leaves every current view, and shows up again with list --include-deleted. --destroy hard-purges. The same filters as wake select memories in bulk; --dry-run previews and --force confirms.

Results come in the same lanes as wake, with historical matches in their own section rather than dropped. --hybrid fuses FTS5 with embedding similarity when an index exists (recoil embed index).

$ recoil search "cache"
---
query: cache
scope: project
scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
retrieval_mode: fts
result_count: 5
history_count: 1
---
## Current Decisions

## mem_f3epegqcib4qepn47onte7nri2
score: 1.0000
created: 2026-09-21T06:33:07Z
validity: active
claim_key: cache.backend
supersedes: mem_7vda2sxdlkgrurmicljaq5fq6k
role: decision
source_kind: direct
source_agent: claude
why: current decision with claim_key cache.backend

Parser cache moves to a per-project SQLite file under .cache/ so worktrees stop sharing one cache. Still SQLite, still no daemon.

## Project Docs

## mem_toqzgisy5ms6ygdwy5c2upqfb2
score: 1.6000
created: 2026-09-21T06:33:07Z
validity: unknown
role: source
source_kind: file
source_agent: recoil
source_path: README.md
source_ref: chunk 1 lines 1-3
why: project document chunk from README.md

# orbit

A parser for satellite two-line element sets with an on-disk cache.

## mem_nbiasls4rskoavtnivpm6v6p7a
score: 1.0000
created: 2026-09-21T06:33:07Z
validity: unknown
role: source
source_kind: file
source_agent: recoil
source_path: docs/architecture.md
source_ref: chunk 1 lines 1-9
why: project document chunk from docs/architecture.md

# Architecture

The parser reads TLE files and keeps a cache of parsed elements so repeated
runs skip the slow checksum pass. Cache entries are keyed by file content hash.

## Cache

Entries live in a SQLite file in WAL mode. Redis was considered and rejected
because installs must work offline with no daemon.

## Recent Evidence

## mem_yr2bckupv2ebyrt3hki6g343ch
score: 1.0000
created: 2026-09-21T06:33:07Z
validity: active
claim_key: handoff.latest
role: handoff
source_kind: direct
source_agent: claude
why: matched query terms

## Next Steps
- Land the per-project cache path, then re-run the cold-start benchmark

## Open Questions
- Prune the cache by age or by size?

## mem_jtijf5wmyvvdoehp23sbjs3szu
score: 1.0000
created: 2026-09-21T06:33:07Z
validity: active
role: note
source_kind: direct
source_agent: claude
why: matched query terms

The parser cache is keyed by file content hash, not mtime: editors rewrite mtimes on save without changing content.

## Historical

## mem_7vda2sxdlkgrurmicljaq5fq6k
score: 1.0000
created: 2026-09-21T06:33:07Z
validity: superseded
claim_key: cache.backend
superseded_by: mem_f3epegqcib4qepn47onte7nri2
role: decision
source_kind: direct
source_agent: claude
why: matched query but lifecycle marks it historical, stale, rejected, or superseded

Keep the parser cache in SQLite with WAL. Redis was rejected: installs must work offline with no daemon.

check "<action>" finds the decision family the request touches and returns a verdict, a recommendation and the reason. check <memory-id>, --claim-key <key> and --claim-key-prefix <prefix> audit a family directly. After the decision from the quickstart was superseded, the same question points at the replacement:

$ recoil check "replace the parser cache backend with Redis"
---
verdict: use_replacement
predicate_status: unknown
recommendation: use_current_decision
reason: matched_historical_decision
predicate_reason: ""
claim_key: cache.backend
decision_stance: ""
decision_subject: ""
requested_action: ""
advisory: ""
recheck: ""
---
## Decision Check

claim_key: cache.backend
verdict: use_replacement
predicate_status: unknown
recommendation: use_current_decision
matched_id: mem_7vda2sxdlkgrurmicljaq5fq6k
current_id: mem_f3epegqcib4qepn47onte7nri2
replacement_id: mem_f3epegqcib4qepn47onte7nri2

## Current Decision

## mem_f3epegqcib4qepn47onte7nri2
created: 2026-09-21T06:33:07Z
validity: active
claim_key: cache.backend
supersedes: mem_7vda2sxdlkgrurmicljaq5fq6k
role: decision
source_kind: direct
source_agent: claude

Parser cache moves to a per-project SQLite file under .cache/ so worktrees stop sharing one cache. Still SQLite, still no daemon.

## Matched Decision

## mem_7vda2sxdlkgrurmicljaq5fq6k
created: 2026-09-21T06:33:07Z
validity: superseded
claim_key: cache.backend
superseded_by: mem_f3epegqcib4qepn47onte7nri2
role: decision
source_kind: direct
source_agent: claude

Keep the parser cache in SQLite with WAL. Redis was rejected: installs must work offline with no daemon.

The request is read against the decision's subject. use, add, enable, switch to and similar cues adopt it; drop, remove, avoid, disable and similar remove it; replace, switch from and move from replace it; keep the decision affirms it. A request that does not name the subject reports requested_action: unknown and falls back to the family verdict.

One row per family: key, number of memories, validity of the current one, and its id.

$ recoil claims
---
scope: project
scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
result_count: 1
---
cache.backend	2	active	mem_f3epegqcib4qepn47onte7nri2

show <id> prints a memory with its full frontmatter; the id can be a unique prefix. list takes the wake filters, --limit (default 50) and --include-deleted; --minimal is one tab-separated row per memory.

$ recoil show mem_f3epegqcib4qepn47onte7nri2
---
id: mem_f3epegqcib4qepn47onte7nri2
scope: project
scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
created: 2026-09-21T06:33:07Z
validity: active
claim_key: cache.backend
supersedes: mem_7vda2sxdlkgrurmicljaq5fq6k
superseded_by: ""
role: decision
source_kind: direct
source_agent: claude
source_path: ""
source_ref: ""
---
Parser cache moves to a per-project SQLite file under .cache/ so worktrees stop sharing one cache. Still SQLite, still no daemon.

$ recoil list --current --minimal
mem_yr2bckupv2ebyrt3hki6g343ch	2026-09-21T06:33:07Z	claude	## Next Steps - Land the per-project cache path, then re-run the cold-start benchmark ## Open Questions - Prune the cache by age or by size?
mem_w5seoglca7u74isihepwxxag4t	2026-09-21T06:33:07Z	claude	The parser cache is keyed by file content hash plus parser version, so a parser upgrade invalidates stale entries.
mem_toqzgisy5ms6ygdwy5c2upqfb2	2026-09-21T06:33:07Z	recoil	# orbit A parser for satellite two-line element sets with an on-disk cache.
mem_nbiasls4rskoavtnivpm6v6p7a	2026-09-21T06:33:07Z	recoil	# Architecture The parser reads TLE files and keeps a cache of parsed elements so repeated runs skip the slow checksum pass. Cache entries are keyed by file content hash. ## Cac...
mem_f3epegqcib4qepn47onte7nri2	2026-09-21T06:33:07Z	claude	Parser cache moves to a per-project SQLite file under .cache/ so worktrees stop sharing one cache. Still SQLite, still no daemon.

For doctrine injection: every current memory in a family or prefix, verbatim, in one block. --historical includes past memories.

$ recoil export --claim-key-prefix cache.
---
kind: export
scope: project
scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
claim_key_prefix: cache.
lifecycle: current
count: 1
---
## cache.backend
id: mem_f3epegqcib4qepn47onte7nri2
created: 2026-09-21T06:33:07Z
validity: active
role: decision
source_kind: direct
source_agent: claude
supersedes: mem_7vda2sxdlkgrurmicljaq5fq6k

Parser cache moves to a per-project SQLite file under .cache/ so worktrees stop sharing one cache. Still SQLite, still no daemon.

setup runs it once; mine [path] runs it again. Files are chunked and stored as source memories with their path and line range, chunks already in the store count as duplicates rather than being stored twice, and a .recoilignore at the root lists paths to leave out. --dry-run previews.

$ recoil mine --dry-run docs
---
root: /tmp/orbit/docs
scope: project
scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
dry_run: true
files_scanned: 1
files_skipped: 0
chunks: 1
added: 0
duplicates: 0
sources: 0
staled: 0
---
dry-run	would-add	docs/architecture.md	chunk 1 lines 1-9

$ recoil status
---
db_path: /tmp/orbit-home/.config/recoil/recoil.db
existed_before: true
memory_count: 7
tombstone_count: 0
fts5: true
project_scope_id: local:dbb8165a8ec8e32bfb255a15ecd75d69
project_root: /tmp/orbit
project_initialized: true
project_marker: /tmp/orbit/.recoil/project.json
---
ready

Settings live in .recoil/config.json at the project root, layered over the defaults. config list shows every key with its source, config explain <key> one key, config set and config unset change a project override, and config path prints the store path in use.

$ recoil config list
---
path: /tmp/orbit/.recoil/config.json
count: 17
---
aging.window-days=30	default	Freshness window in days before note and handoff memories receive read-side aging demotion.
backup.dir=	default	Default destination directory for recoil backup snapshots.
backup.max=3	default	Maximum number of rotating backup snapshots to keep.
mine.exclude_paths=	default	Comma-separated path globs to exclude from mining even when they otherwise look important.
mine.follow_repo_symlinks=true	default	Follow symlinks that resolve inside the mined root for supported text files.
mine.include_hidden_operational=true	default	Include allowlisted hidden operational files such as .github/SECURITY.md without enabling every hidden file.
mine.include_paths=	default	Comma-separated path globs to force into mining, subject to file size and UTF-8 checks.
retrieval.mode=auto	default	Search retrieval mode: auto enables hybrid FTS+embeddings when a usable local embedding index exists; fts forces sparse search; hybrid requires a usable embedding index.
session-evidence.enabled=false	project	Enable mining session evidence captured by installed agent hooks.
session-evidence.min-chars=200	default	Minimum content length for session evidence files before ingestion selects them.

backup writes a consistent snapshot next to the database (or --out) and rotates old ones (--max, default 3). migrate brings the schema up to date and repair rebuilds the FTS index; both take --dry-run, and migrate --age re-runs read-side aging.

embed index builds an embedding sidecar for the scope (--provider local with local-hash-v1, or openrouter), and search --hybrid fuses it with FTS5. eval runs the retrieval fixtures under eval/. profile builds a deterministic entity profile from current memories. tray runs the system tray companion. version prints version, commit and build date.