goldfish

Goldfish 🐠

Persistent developer memory for Claude Code. Checkpoints, recall, plans, standup reports, and built-in semantic recall -- stored as human-readable markdown right in your project.

Goldfish gives AI coding sessions memory that survives context compaction, crashes, and session restarts. Markdown in .memories/ stays the source of truth (and is git-committable), while Goldfish keeps a lightweight cross-project registry at ~/.goldfish/registry.json plus derived semantic cache data under ~/.goldfish/cache/semantic/ and model files under ~/.goldfish/models/transformers/.

Version 6.5.0 -- Fifth iteration, built on hard lessons from four previous attempts.

---

Why Goldfish?

AI coding sessions have a memory problem:

• Context windows get compacted, losing work history
• Sessions crash, losing planning and decisions
• Switching projects loses context
• No way to answer "what was I working on yesterday?"

Goldfish solves this with four MCP tools (checkpoint, recall, plan, consolidate), five skills, and three hooks that make memory automatic and transparent.

---

Quick Start

Prerequisites: Bun runtime (v1.0+)

Option 1: Install from GitHub (Recommended)

This gives you the full experience: MCP tools + skills (/checkpoint, /recall, /plan, /standup, /plan-status) + hooks (auto-recall on session start, auto-checkpoint before compaction, auto-save plans).

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

# Install the plugin (user scope, available across all projects)
/plugin install goldfish@goldfish

You can also scope the installation to a specific project:

# Project scope (shared with team via version control)
/plugin install goldfish@goldfish --scope project

Option 2: Install from a Local Clone

If you prefer to clone the repo yourself (useful for development or contributing):

# Clone the repository
git clone https://github.com/anortham/goldfish.git

# Install dependencies
cd goldfish && bun install

# Install as a Claude Code plugin
claude plugin install /path/to/goldfish

For development (loads plugin from local directory each time):

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

Once the plugin is loaded, Goldfish works automatically:

1. Session starts -- the SessionStart hook fires, calling recall() to restore recent context
2. You work -- checkpoint manually with /checkpoint, or let the PreCompact hook auto-checkpoint before context compaction
3. Plans persist -- the ExitPlanMode hook auto-saves plans to .memories/plans/
4. Next session -- everything is recalled automatically

No configuration needed beyond plugin installation.

Option 3: Use as a Standalone MCP Server (Any MCP Client)

Goldfish is a standard MCP server. It works with any MCP-compatible client -- not just Claude Code.

# Clone and install
git clone https://github.com/anortham/goldfish.git
cd goldfish && bun install

Add to your MCP client's configuration (the exact format depends on your client):

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

What you get with standalone MCP: The 4 core tools (checkpoint, recall, plan, consolidate) and the server instructions that guide agent behavior. What you don't get: Skills (/checkpoint, /recall, /plan, /standup, /plan-status) and hooks (auto-recall, auto-checkpoint, auto-plan-save) -- those are Claude Code plugin features.

For standalone MCP usage, you'll want to instruct your agent to:

• Call recall() at session start
• Call checkpoint() after completing work
• Call plan() to save and manage long-running plans
• Call consolidate() periodically to distill checkpoints into memory.yaml

VS Code with GitHub Copilot

Create a .vscode/mcp.json file in your project root:

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

The GOLDFISH_WORKSPACE environment variable tells Goldfish where your project root is. VS Code automatically substitutes ${workspaceFolder} with the actual path.

Without this, Goldfish may create its .memories/ directory in the wrong location since VS Code's MCP integration doesn't pass cwd the way Claude Code does.

If you want Copilot to consistently checkpoint and recall with Goldfish, copy docs/goldfish-checkpoint.instructions-vs-code.md into your repo's .github/instructions/ folder (or adapt it to your preferred instructions layout). That file gives VS Code users a ready-made Goldfish + Julie instruction set instead of starting from a blank page.

---

How It Works