# backpass

> An open-source CLI tool that automatically analyzes agent session transcripts and proposes evidence-backed edits to your AGENTS.md memory file using a gradient descent metaphor.

backpass is an open-source CLI tool built by Kun Chen (kunchenguid) that treats your `AGENTS.md` file as a set of model weights and your agent session transcripts as the loss signal. It reads transcript stores from seven supported agent harnesses directly from disk, distills them, and proposes concrete, evidence-backed edits to your memory file — all locally, with a human review gate before anything is written. The project is published on npm under the MIT license and supports macOS and Linux.

## What It Is

backpass applies the metaphor of neural network training to agent memory management. Your `AGENTS.md` (or `CLAUDE.md`) is the "weights" — the persistent instructions that shape every future agent session. Each agent session is a "forward pass," and the transcript it leaves on disk is the "loss signal." backpass closes the feedback loop that normally requires a human to manually remember a failure and edit the file by hand. It collects session transcripts, distills them, calculates what went wrong or right, aggregates evidence across sessions, and proposes a small set of diffs — then waits for you to accept or reject each one.

## How the Pipeline Works

The tool runs a five-stage backward pass:

- **Collect samples** — reads transcript stores for seven harnesses (claude, codex, pi, opencode, grok, cursor CLI, hermes) directly from disk with no API calls or uploads. Sessions are associated to the current repo via cwd matching, git remote matching, or best-effort path heuristics.
- **Distillation** — reduces raw transcripts deterministically before any model sees them. Tool calls are collapsed to one line, tool output is truncated, harness scaffolding is dropped, and secrets are redacted. The README reports typical reduction of 96–99%.
- **Calculate loss** — one cheap model call per transcript returns strict JSON: which instructions helped, which were violated, and what gaps exist. Every claim must carry a verbatim quote; quoteless items are discarded.
- **Aggregate gradients** — evidence is grouped deterministically (no model). A gap must appear in at least two independent sessions before it can be proposed. A persistent gap ledger accumulates sightings across runs so a gap seen today and corroborated next week graduates on the later run.
- **Gradient descent** — a single high-reasoning agent session edits a staging copy of the memory file. backpass diffs the copy, annotates each hunk, and enforces mechanical gates: at most five edits per run by default, every edit must carry verbatim evidence, new instructions need multi-session support, and the post-edit file must fit the token budget.

## Local-First and Human-Gated Design

backpass has no API keys of its own. All model calls go through [`acpx`](https://github.com/openclaw/acpx), routing to whichever agent harness the user has already authenticated. Transcripts never leave the machine except into an agent the user already controls, and obvious secrets are redacted before they do. The `backpass apply` command is the only command that writes — it opens a browser-based review surface (or a terminal fallback with `--no-ui`) showing each proposed edit with its diff, verbatim evidence quotes, source session references, and a live budget gauge. Rejected edits are remembered and not re-proposed unless materially new evidence arrives.

## Two-Tier Model Architecture

backpass uses cheap models for per-transcript analysis and high-reasoning models for the final synthesis step. Both tiers use an ordered ladder of candidates — the first installed, logged-in harness that serves the target model wins. The default analysis ladder tries `gpt-5.6-luna` via pi/opencode/codex, then `claude-sonnet-5` via claude, then `grok-4.6`. The synthesis ladder tries `gpt-5.6-sol`, then `claude-opus-5`, then `grok-4.6`. Ladders are fully configurable, and individual agents and models can be pinned via CLI flags.

## Skills as a Budget Release Valve

The tool enforces a default budget of 5,000 estimated tokens (~20KB) per always-loaded memory file. Instructions relevant to fewer than roughly 20% of sessions can be extracted into "skills" — separate files whose descriptions are always loaded but whose bodies are only fetched when triggered. The README gives a concrete example: a 640-token procedure relevant to 4% of sessions becomes a 35-token description line, saving 611 always-loaded tokens. At or over budget, the synthesis prompt goes zero-sum: every addition must name the removal or extraction that pays for it.

## Update: v0.1.6

The latest release is backpass v0.1.6, published on 2026-08-26. The project was created on 2026-08-21 and has accumulated 419 stars and 17 forks in its first week. The repository is actively maintained with CI and release automation via GitHub Actions. The README notes that Cursor IDE support is deferred to v1.1, with a best-effort `--include-cursor-ide` flag available in the current release.

## Features
- Reads agent session transcripts from 7 harnesses directly from disk (claude, codex, pi, opencode, grok, cursor CLI, hermes)
- Local-first: no API keys, no uploads, secrets redacted before model calls
- Evidence-gated proposals: every edit requires verbatim quotes from at least 2 independent sessions
- Human review gate: backpass apply shows each edit with evidence before writing
- 96-99% transcript distillation before model analysis
- Persistent gap ledger accumulates evidence across runs
- Two-tier model architecture: cheap analysis, high-reasoning synthesis
- Token budget enforcement with skills extraction as overflow mechanism
- Incremental scan cache for large transcript stores
- Configurable model ladders via .backpassrc.json
- Live progress view in interactive terminals
- Rejection memory: rejected edits not re-proposed without new evidence
- Bootstrap support: creates starter AGENTS.md for repos with no memory file
- Staging copy workflow: repo is read-only during synthesis

## Integrations
Claude (Anthropic), OpenAI Codex, Pi, OpenCode, Grok, Cursor CLI, Hermes, acpx (openclaw), npm, Node.js

## Platforms
MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
0.1.6

## Links
- Website: https://github.com/kunchenguid/backpass
- Documentation: https://github.com/kunchenguid/backpass#readme
- Repository: https://github.com/kunchenguid/backpass
- EveryDev.ai: https://www.everydev.ai/tools/backpass