you read file. you forget. you read again. fish happy.

A skill + hook bundle that makes Claude Code, Cursor, and other agents rebuild state from disk before every task instead of trusting fragile chat memory. Decisions stick. Context survives /clear. New teammates get free onboarding.

The problem

You spend an hour with Claude Code working out a tricky schema decision. You ship it. A week later you open a fresh chat, type "let's continue the billing work", and the agent confidently does the wrong thing because it has no idea what you decided last Tuesday. You re-explain. Half the context is lost. Three months later someone refactors away the rationale you no longer remember.

Long sessions drift. /clear erases hard-won context. Decisions live in chat history that nobody reads. Most "agent memory" tools paper over this with vector search and hope.

Goldfish takes the opposite approach: assume the agent has a 3-second memory. Force it to write durable state to disk and read it back every session. The discipline is the product.

How it works

Three files in the repo:

File	Purpose	Lifetime
SPEC.md	What you're building. Goals, non-goals, invariants.	Stable. Read-only unless you opt in.
NOTES.md	Working memory. Status, next, blocked, open questions.	Ephemeral. Rewritten every checkpoint. Cap 80 lines.
DECISIONS.md	Decisions with date, scope, impact, rejected alternatives.	Editable before publication. Immutable after.

The agent follows a strict protocol:

1. Before any task, read SPEC, NOTES, and the latest DECISIONS entries. Restate the task citing relevant SPEC sections.
2. During planning or brainstorming, treat new behavior-affecting facts and proposals as assumptions. Put them in NOTES Open questions or plan docs, not DECISIONS.
3. During implementation, when something decision-shaped emerges, ask "decision or assumption?" and route it to DECISIONS or NOTES accordingly.
4. Before the final checkpoint, sweep the task diff against the task baseline for implicit behavior-affecting choices. Ask which unrecorded choices are decisions worth recording, and which are implementation details.
5. After the task, rewrite NOTES per fixed structure. Record new or revised decisions in DECISIONS. Redact any sensitive data (API keys, secrets).
6. Validator hooks block turn completion if NOTES exceeds budget, published DECISIONS content is edited instead of superseded, or SPEC was edited without explicit permission.

Files commit alongside code. Memory is versioned. New sessions resume from disk, not from your head.

Install

Claude Code

/plugin marketplace add phen0menon/goldfish-marketplace
/plugin install goldfish@goldfish-marketplace

The skill auto-activates on session start. Use /goldfish-resume to load context, /goldfish-checkpoint to save it.

Cursor

/add-plugin goldfish

Or manually copy .cursor/rules.mdc and .cursor/hooks.json from this repo into your project.

Codex

In Codex sidebar, find Goldfish under Coding and click +.

Other agents

npx skills add phen0menon/goldfish

This installs the skill. For auto-activation, add the bootstrap snippet from docs/manual-bootstrap.md to your agent's rules file.

Quick start

goldfish init

Scaffolds SPEC.md (with placeholder Goals / Non-goals / Invariants), empty NOTES.md, empty DECISIONS.md, plus a pre-commit hook running the validator.

Open the SPEC. Fill in three or four sentences about what you're building. The agent will refuse to proceed with significant work until SPEC has actual content - that's by design.

Then just work normally.

A walkthrough

Day 1, fresh repo:

> building a todo app with auth and shared lists

agent: SPEC.md is empty. I need goals and invariants before I can help.
       Want me to draft a starter SPEC from your description?

> yes, then we'll edit

[agent drafts SPEC.md, you tweak invariants]

> let's start with auth. password-based, email reset.

agent: per SPEC §3 (no third-party identity providers in v1),
       proposing argon2id for hashing, 15-minute reset tokens.
       decision or assumption?

> decision. argon2id over bcrypt because we control the deployment.

agent: [appends to DECISIONS.md]
       writing the auth module now.

Day 12, completely fresh chat, you've forgotten half the details:

> /goldfish-resume

agent: last commit 11 days ago.
       auth module complete, password reset flow shipped,
       rate limiting in progress on /reset endpoint.
       open question: should rate limit key be email or IP?
       continue with rate limiting?

> yes. decided: rate limit by email, not IP. shared offices break IP-based limits.

agent: decision or assumption?

> decision.

agent: [appends to DECISIONS.md]
       resuming work on the limiter.

You re-explained nothing. Three months later, when someone asks "why is rate limiting keyed by email?" - the answer is in DECISIONS.md, with the rejected alternative right next to it.

What's in the box

Skills

• goldfish - the core protocol skill, activates at session start
• goldfish-resume - reads files, reports state, asks where to pick up
• goldfish-compact - aggressively trims NOTES when over budget

Commands

• /goldfish-resume - load context from disk
• /goldfish-checkpoint - rewrite NOTES, record decisions
• /goldfish-triage - walk through stale items after a long pause
• /goldfish-compact - force NOTES under cap

Hooks

• SessionStart - injects one reminder per session so the skill triggers reliably without prompt-level noise
• Stop - runs validator after every turn, blocks completion on violations
• pre-commit - runs validator before code lands

Validator (scripts/validate.sh)

• NOTES.md must be 80 lines or fewer
• DECISIONS.md is editable before publication; published content can only be superseded
• SPEC.md is frozen unless commit message contains [spec] or GOLDFISH_ALLOW_SPEC=1 is set

License

MIT