goldfish

Goldfish 🐠

An evidence ledger for AI coding sessions. Checkpoints capture what changed and why; briefs hold durable strategic direction; recall pulls both back when the next session needs context. Everything lives as markdown in your repo, so it travels with the code, diffs in PRs, and outlasts any single harness.

Goldfish is a cross-client MCP memory system. Claude Code and Codex both install as a plugin — tools, skills, and a session-start hook that loads Goldfish's guidance into each new session. OpenCode can discover repo-local Goldfish skills from .agents/skills, and VS Code with GitHub Copilot can use the MCP server plus repo instructions.

Version 7.6.1 -- Standup timeframes: /standup 7d, /standup 1w, or /standup 3d widen the report window, and recall's since parameter now accepts week spans like "1w". See CHANGELOG.md for details.

---

Why Goldfish?

Coding harnesses already plan, summarize, and recover from compaction. What they don't do is keep a durable record of why a project moved the way it did, in a place the next session (or the next harness) can read.

Goldfish is git for intent: a source-controlled, harness-agnostic ledger of decisions, milestones, and direction. Three MCP tools (checkpoint, recall, brief) and six skills, with markdown as the source of truth.

---

Client Setup

Prerequisites: Bun runtime (v1.0+)

Start by cloning the repository and installing dependencies:

git clone https://github.com/anortham/goldfish.git
cd goldfish
bun install

Claude Code

Claude Code is the fullest adapter today. You get MCP tools, slash-command skills (/checkpoint, /recall, /brief, /brief-status, /handoff, /standup), and a session-start hook that loads Goldfish's memory guidance into each new session.

Install from the marketplace:

# Add the Goldfish repository as a plugin marketplace
/plugin marketplace add anortham/goldfish

# Install the plugin for your user
/plugin install goldfish@goldfish

# Or scope it to the current project
/plugin install goldfish@goldfish --scope project

Install from a local clone:

claude plugin install /path/to/goldfish

For development, load the plugin from the local directory each time:

claude --plugin-dir /path/to/goldfish

The session-start hook. The plugin registers a SessionStart hook that injects Goldfish's usage guidance (checkpoint triggers, tool reference, brief lifecycle) at the start of each session — this is what keeps agents checkpointing even when tool descriptions are deferred. It fires once at session start (and again after /clear or a context compaction), prints static text, makes no tool calls, and writes no state. It needs no setup: sessions started after the plugin is installed (or updated to 7.5+) pick it up automatically. You can inspect it anytime with /hooks.

Once the plugin is loaded, Goldfish works through manual invocation and agent-driven calls:

1. Session starts -- run /recall (or let the agent call recall()) to restore recent checkpoints and the active brief
2. You work -- checkpoint with /checkpoint at meaningful milestones
3. Direction persists -- save a brief with /brief when goals, constraints, or success criteria should survive the session
4. Next session -- recall replays the same context

Cursor

Cursor runs Goldfish as a plugin. Note a client quirk that affects workspace binding: Cursor advertises MCP roots to user-config MCP servers (registered in ~/.cursor/mcp.json) but not to plugin-launched servers, and it spawns plugin servers with cwd set to your home directory rather than the open project. That means a freshly-installed Goldfish plugin in a brand-new project — before any checkpoint has registered it — has no project path signal and will refuse mutating tools with guidance rather than guess.

Goldfish 7.3+ recovers automatically once a project is known: if cwd or an ancestor is in the cross-project registry, or a parent directory has .memories/ or .git/, recovery resolves the project root without roots. Until that first checkpoint lands, the reliable escape hatch is the same as Codex Desktop — register Goldfish per-project with an explicit GOLDFISH_WORKSPACE:

{
  "mcpServers": {
    "goldfish": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/goldfish/src/server.ts"],
      "env": { "GOLDFISH_WORKSPACE": "/absolute/path/to/your/project" }
    }
  }
}

Add that to the project's .cursor/mcp.json (or your user config scoped to the project) for first use. Once you've checkpointed there once, the plugin's recovery takes over and the override is no longer needed.

Codex CLI / Desktop