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 gets the fullest adapter today, with plugin installation and slash-command skills. Codex Desktop and 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.2.0 -- Recall gains type and tags filters, search now indexes checkpoint type, and corrupt registry / brief / lock files are handled defensively instead of wiping data or stalling. 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 and slash-command skills (/checkpoint, /recall, /brief, /brief-status, /handoff, /standup).

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

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

Codex Desktop

Codex shares MCP configuration between the CLI and the IDE extension through ~/.codex/config.toml, and it also discovers repo-local skills from .agents/skills.

Codex Desktop does not send MCP roots. If you want Goldfish bound to the current repo, the reliable setup is a project-local .codex/config.toml in that repo so you can pass GOLDFISH_WORKSPACE for that project.

Add Goldfish to a trusted project-local .codex/config.toml:

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

You can put Goldfish in ~/.codex/config.toml too, but that pins GOLDFISH_WORKSPACE to one repo. For Codex Desktop across multiple repos, keep the server entry in each project's .codex/config.toml.

Goldfish skills in .agents/skills are discovered automatically when you launch Codex inside the repository.

OpenCode

OpenCode loads local MCP servers from opencode.json and can also discover repo-local skills from .agents/skills.

Add Goldfish to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "goldfish": {
      "type": "local",
      "command": ["bun", "run", "/absolute/path/to/goldfish/src/server.ts"],
      "enabled": true
    }
  }
}

OpenCode walks up the repository and loads matching .agents/skills/*/SKILL.md, so the checked-in Goldfish skills are available without extra copying.

VS Code with GitHub Copilot

VS Code supports project-level MCP config in .vscode/mcp.json, supports the full MCP feature set, and can pair Goldfish with repo instructions for better memory habits.

mkdir -p .vscode

Create .vscode/mcp.json:

{
  "servers": {
    "Goldfish": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "/absolute/path/to/goldfish/src/server.ts"]
    }
  }
}

GOLDFISH_WORKSPACE is optional in VS Code now that Goldfish can resolve the active workspace from MCP roots. Keep it as an override if you want to pin Goldfish to a different root or you run in a client that does not provide roots: