Passive ADR

passive-adr

Passive Architecture Decision Record (ADR) memory for Claude Code.

Claude forgets why you chose Postgres, why the UI went dark-first, why you split the monorepo — the moment a session ends. passive-adr remembers. It watches for architecturally-significant decisions (made by you or the agent), records each as an ADR with its rationale in a gitignored .adr/ folder, and feeds the decision index back into every future session so settled choices are honored instead of silently reversed.

No prompts, no interruptions. A background sweep runs at session end and before context compaction, reads the transcript, and writes only decisions that carry lasting weight and have a stated "why."

Install

/plugin marketplace add zvoque/passive-adr
/plugin install passive-adr@passive-adr

What gets recorded

Only decisions with lasting architectural weight and a rationale:

• Tech-stack / framework / database / hosting picks
• Design direction (visual style, UX approach)
• Structural patterns (monorepo vs polyrepo, event-driven, auth model, API shape)

Trivial or transient choices (which tool to call, a variable name, one-off implementation details) are skipped. If a choice has no stated rationale, it is not recorded — a sparse log beats a noisy one.

How it works

Event	Hook	What it does
SessionStart	adr-inject.sh	Injects .adr/INDEX.md so the agent starts aware of prior decisions
SessionEnd / PreCompact	adr-sweep.sh	Spawns a headless claude -p (Haiku) that reads the transcript + existing index and writes any new decisions, dedup-aware
PostToolUse (Read)	adr-stamp.sh	Stamps an ADR's last_read when the agent reads it — the warmth signal decay filters on

Records live per-project in <cwd>/.adr/, auto-added to .gitignore.

The /adr command

Command	What it does
/adr list	Show the decision index (and a count of archived records). Default when run bare.
/adr show <id>	Print one ADR in full — checks live records first, then the archive. Reading a live ADR re-heats it for decay.
/adr search <term>	Case-insensitive search across every record, live and archived. Archived matches are marked [archived].
/adr sweep	Capture decisions from the current conversation right now, instead of waiting for session end.
/adr new	Dictate one ADR by hand — you supply the title, context, decision, and rationale.
/adr supersede <id>	Mark a decision reversed: flips its status, moves it to the archive, and offers to record the replacement with a link back.
/adr on / /adr off	Pause or resume the plugin for this project (capture and inject stop; the plugin's small always-on metadata only disappears with claude plugin disable passive-adr).
/adr decay <N>	Inject only decisions read in the last N sessions; colder ones collapse to a one-line stub. decay off (or 0) restores inject-everything. Bare /adr decay shows the current setting plus a preview of what would go cold.
/adr consolidate	Spring-clean the store: auto-archives any leftover superseded records, then proposes merging redundant ones — nothing is merged without your approval.

Keeping the cost down (v0.2)

The session inject is terse by design (one preamble line + one line per live decision) and superseded records are archived out of it automatically. Per- session cost is logged to .adr/.inject.log so the tax is visible.

Optional decay: /adr decay 50 injects only decisions read in the last 50 sessions; colder ones collapse to a one-line stub and stay reachable via /adr search (reading one re-heats it). New decisions that touch the same ground as an old one re-heat it automatically during the sweep. Default is off — out of the box, every accepted decision injects every session, exactly like v0.1. /adr off pauses the plugin per-project; /adr consolidate proposes merging redundant records (your approval required).

ADR format

Each ADR is one markdown file (.adr/<id>-<slug>.md) with frontmatter (id, date, status, supersedes, decided_by, last_read) and three sections: Context, Decision, Rationale.

Requirements

• claude CLI on PATH (used by the background sweep; sweep skips silently if absent).
• A sweep failure never blocks or breaks a session.

Compatibility

Built for Claude Code (the local CLI), where your working directory and its .adr/ folder persist between sessions — which is what makes the memory work.

Not supported in Cowork: .adr/ is gitignored by design, so it would not survive Cowork's ephemeral per-session environment, and the background sweep relies on a local claude CLI that isn't guaranteed there.

License

MIT