Save-Scum
jaxdeformity/save-scum
Memória de agente com recall capped: checkpoints de handoff, não re-leitura
Ver no GitHubSkill de memória de trabalho limitada para agentes de IA que codificam. Cria checkpoints de handoff por projeto com recall limitado às últimas 5 ações (~5h), reduzindo releitura desnecessária de histórico e economizando tokens. Integra-se com Claude Code e Agent SDK.
Instalação
npx convez-ai jaxdeformity/save-scum1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Sessões longas de desenvolvimento sem re-ler todo o histórico
- Redução de tokens gastos em contexto repetido entre sessões
- Rastreamento de progresso em projetos complexos com checkpoints naturais
Veredito

Solução elegante e bem documentada para um problema real de agentes de IA em projetos longos. Abordagem pragmática com bounds claros reduz waste de tokens e mantém histórico legível e versionável em Git.
README
A tradução para o português deste README ainda está na fila.
save-scum
A bounded working-memory skill for AI coding agents (Claude Code / Agent SDK).
Named for the gaming habit — checkpoint constantly, reload only what's recent.
save-scum gives an agent a cheap, durable, per-project memory: it drops compact
handoff checkpoints as it works, and when it later gathers context it reads only
the most recent few instead of replaying the entire project history. The whole
point is the bound — recall is capped at the last 5 handoffs (~5 hours) unless
you explicitly ask it to go further.
The problem it solves
Long-running agent work has a context problem. To "pick up where we left off," an agent typically re-reads source files, scrolls the transcript, or lets a memory plugin inject everything it has ever recorded. That re-read happens every session, every time you reference past work — and it grows without bound as the project ages. Most of those tokens are paid for repeatedly and thrown away.
save-scum replaces unbounded re-reading with curated, capped recall:
- Write a ~150–300 token handoff at natural checkpoints, on task completion, and whenever ~an hour of work has elapsed.
- Read only the top 5 handoffs (via a one-line-per-entry
INDEX.md), and escalate only on demonstrated need or an explicit "go back further."
The result is recall that costs a fixed ~1–2K tokens instead of a re-read that scales with project age.
How it works
<project>/.save-scum/
INDEX.md # newest-first, 1 line per handoff (cheap to scan)
0007-2026-06-08T1942-dongle-recon.md # compact checkpoint
0006-2026-06-08T1840-sprites.md
...
INDEX.md— one line per handoff:NNNN | ts | slug | one-line hook. The agent scans this first and decides which handoffs (within the last 5) to open.- Handoff files — small, structured: Doing · State & decisions · Open threads / next steps · Pointers. Markdown is the source of truth, so it survives a memory plugin or vector DB being down, and it's human-readable and git-friendly.
- The skill (
SKILL.md) — the discipline the agent follows: read the bound, escalate only on need, write at the triggers. Loaded automatically when the agent picks up work or you reference past context. - The SessionEnd hook (
hooks/session-end-handoff.js) — a safety net that guarantees a closing handoff exists even if the agent forgets, gated to write nothing if a handoff was already written in the last 45 minutes (insurance, not spam). The skill works fully with zero hooks; the hook is optional.
Install (Claude Code)
-
Drop the skill where Claude Code finds personal skills:
~/.claude/skills/save-scum/ SKILL.md hooks/session-end-handoff.js -
(Optional) Wire the safety-net hook in
~/.claude/settings.json:{ "hooks": { "SessionEnd": [ { "hooks": [ { "type": "command", "command": "node \"<HOME>/.claude/skills/save-scum/hooks/session-end-handoff.js\"" } ] } ] } } -
Add
.save-scum/to your project's.gitignoreif you want handoffs kept local (recommended — they're per-machine working notes).
That's it. The agent will start reading/writing .save-scum/ automatically.
The hook is cross-platform (normalizes Git-bash POSIX paths to native Windows).
Token & cost savings
These are transparent estimates, not measured benchmarks. The savings come entirely from replacing an unbounded re-read with a capped one, so the number depends on what your agent would otherwise re-read. The model and assumptions are spelled out below so you can plug in your own.
The model. Each time an agent gathers context, it spends input tokens. Call the
baseline (without save-scum) B and the bounded cost S:
S ≈ INDEX (~N lines × ~15 tok) + 5 handoffs × ~250 tok ≈ 1.5–2.5 K input tokens (flat)
B ≈ whatever it re-reads to reconstruct context:
- re-read all handoffs: N × 250 tok (grows with project age)
- reconstruct from source/transcript: 10–50 K tok (typical for a real pickup)
savings per context-gather = B − S
S is essentially flat; B grows with the project. The savings scale with how much
you don't re-read.
Worked examples (Opus 4.8 input pricing, $5 / 1M input tokens; output unaffected):
| Scenario (per context-gather) | Baseline B | save-scum S | Saved tokens | Saved $ |
|---|---|---|---|---|
| Light: re-read ~20 handoffs | ~5,000 | ~2,000 | ~3,000 | $0.015 |
| Typical: reconstruct from source | ~25,000 | ~2,000 | ~23,000 | $0.115 |
| Heavy: deep transcript/source replay | ~50,000 | ~2,000 | ~48,000 | $0.240 |
Over time. A developer who picks up context ~10×/day at the "typical" rate saves
~230 K input tokens/day ≈ $1.15/day ≈ ~$25/month per active project — and the
gap widens as the project grows, because S stays flat while B climbs. Multiply
across projects and across a team.
Caveats (so the numbers stay honest):
- If your agent would only ever re-read a tiny amount of context,
Bis small and the savings are small. save-scum pays off most on long-lived projects and frequent pickups. - These are input-token savings. Output tokens (the agent's actual work) are unchanged.
- Prompt caching can already cheapen a stable re-read prefix (cache reads ≈ 0.1×, so ~$0.50/1M). save-scum is complementary: it shrinks what must be read at all, and handoffs are curated signal rather than raw history.
- The biggest practical win is often quality, not just cost: bounded, curated recall keeps the agent focused on what's recent and relevant instead of drowning in stale history.
Why not just use a memory plugin / vector DB?
You can use both. save-scum is deliberately:
- Bounded — capped recall by default; memory plugins tend toward unbounded injection.
- Durable & inspectable — plain markdown in your repo tree; survives a worker or
vector store being down, and you can read/edit/
git diffit. - Curated — a handoff is signal the agent chose to record, not a raw transcript dump.
Use a vector DB for deep semantic search across all history; use save-scum for the cheap, recent, "where were we" layer.
Testing
The SessionEnd hook ships with a self-contained test driver:
node hooks/test-session-end.js
# PASS A: writes next handoff on a stale existing index
# PASS B: gate skips when last handoff is fresh
# PASS C: creates .save-scum + 0001 when absent
# PASS D: POSIX cwd normalized -> writes to native location
License
MIT — see LICENSE.