goldfish

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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](https://bun.sh) runtime (v1.0+)

Start by cloning the repository and installing dependencies:

```bash
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:

```bash
# 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:

```bash
claude plugin install /path/to/goldfish
```

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

```bash
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`:

```json
{
  "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

**Recommended: install the plugin.** Goldfish ships a Codex plugin manifest (`.codex-plugin/plugin.json`) that delivers everything in one install — the MCP server (tools), the 6 skills, and a SessionStart hook that loads Goldfish's memory guidance into each new session.

```bash
codex plugin marketplace add anortham/goldfish
codex plugin add goldfish@goldfish
```

This same install covers the Codex desktop app: restart it after installing and it picks up the plugin.

**One-time hook trust review.** Installing or enabling a plugin does not automatically trust its hooks — Codex skips them until you approve. Run `codex`, open `/hooks`, review and trust Goldfish's SessionStart hook, then start a new thread. Until you do, tools and skills work but the session-start guidance stays silent.

The hook is deliberately minimal: it fires once at session start (and after `/clear` or a compact), prints static guidance, makes no tool calls, and writes no state.

**Manual alternative: `.codex/config.toml`.** If you would rather not install the plugin, register the server yourself. Codex shares MCP configuration between the CLI and the IDE extension through `~/.codex/config.toml`, and it 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`:

```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`:

```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.

This repository ships a working `opencode.json` (paths relative to the repo root) you can copy as a starting point.

### 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.

This repository ships a working `.vscode/mcp.json` you can copy. To create your own:

```bash
mkdir -p .vscode
```

Create `.vscode/mcp.json`:

```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:

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

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 instruction set instead of starting from a blank page.

If you want the closer Claude-style experience, VS Code's agent plugins preview can also load Claude-format plugins. Goldfish already ships `.claude-plugin/plugin.json`, which VS Code can detect for plugin skills.

Two ways to wire that up:

- Register a local Goldfish clone with the `chat.pluginLocations` setting in `settings.json`
- Add a marketplace with `chat.plugins.marketplaces` if you want shared discovery instead of a direct local path

Use `.vscode/mcp.json` when you only want the MCP tools. Use the plugin path when you want skills as well.

### Any MCP Client

Goldfish is a standard [MCP](https://modelcontextprotocol.io/) server, so any client that can launch a local stdio server can use the three core tools (`checkpoint`, `recall`, `brief`) and the server instructions.

What varies by client:

- **Skills** depend on whether the harness reads repo-local skill files such as `.agents/skills`
- **Workspace binding** depends on roots support, explicit cwd, or `GOLDFISH_WORKSPACE`

### Instruction-Only Harnesses (Zed, Amp, Jules, Cursor rules, Windsurf, Cline, Kiro, ...)

Many harnesses read a repo instruction file (`AGENTS.md`, `.cursor/rules/`, `.windsurf/rules/`, `.clinerules/`, `.kiro/steering/`) but never surface MCP server instructions. For those, copy the generated usage ruleset [`docs/agent-instructions/goldfish-usage.md`](https://github.com/anortham/goldfish/blob/HEAD/docs/agent-instructions/goldfish-usage.md) into your repo's instruction surface.

Honest caveat: this gives the agent Goldfish *behavior rules only*. The `checkpoint`/`recall`/`brief` tools still need the MCP server registered in that harness (see the sections above); without it the rules have nothing to call.

The full support matrix, including what was deliberately not built and why, lives in [`docs/agent-portability.md`](https://github.com/anortham/goldfish/blob/HEAD/docs/agent-portability.md).

---

## How It Works

### Checkpoint -- Save Progress

Checkpoints capture what you did, why, and how. They're saved as individual markdown files with YAML frontmatter.

```
You: "Fix the authentication timeout bug"

Claude: [works on the bug]
Claude: [checkpoints: "Fixed JWT timeout by implementing refresh token rotation.
         Root cause was single-use token with no renewal path. Added
         RefreshTokenStore with 7-day expiry. Auth tests passing."]

[Session crashes or compacts]

You: [new session]
Claude: [auto-recalls checkpoint, picks up where it left off]
```

**Saved to:** `{project}/.memories/2026-02-14/143022_a1b2.md`

### Recall -- Restore Context

Recall returns recent checkpoints, the active brief, and optional cross-project summaries. Agents call it at session start; users can run `/recall` for targeted queries.

```
recall()                                    # Last 5 checkpoints, no date window
recall({ since: "2h" })                     # Last 2 hours
recall({ search: "auth bug" })              # BM25 search across descriptions
recall({ days: 7, limit: 20, full: true })  # Extended history with metadata
recall({ workspace: "all", days: 1 })       # Cross-project (for standups)
recall({ file: "workspace.ts" })            # Intent-blame: who touched this file?
recall({ symbol: "recoverWorkspace" })      # Intent-blame: who touched this symbol?
recall({ limit: 0 })                        # Active brief only
```

When you search with `recall({ search: "..." })`, results are compact by default so agents get dense, low-token snippets. Pass `full: true` to return full descriptions and metadata instead.

### Brief -- Track Durable Direction

Briefs are compact strategic markdown documents that survive across sessions. They appear at the top of every `recall()` response.

```markdown
---
id: auth-system-redesign
title: Auth System Redesign
status: active
created: 2026-02-10T10:00:00.000Z
updated: 2026-02-14T14:30:00.000Z
tags: [auth, architecture, security]
---

## Goal

Redesign auth around durable refresh-token sessions.

## Why Now

Timeout bugs and session drift keep burning time across sessions.

## Constraints

- Keep one-release compatibility for existing auth clients
- Do not break admin SSO

## Success Criteria

- Recall and checkpoint evidence line up with the new auth direction
- Standup reports stay consistent with the brief and recent checkpoints

## References

- docs/plans/2026-02-14-auth-system-redesign.md
```

**Saved to:** `{project}/.memories/briefs/auth-system-redesign.md`

---

## Skills

Goldfish ships 6 skills. Claude Code and Codex plugin installs expose them directly; OpenCode (and Codex without the plugin) discovers the same skill content from `.agents/skills/`.

| Skill | What It Does |
|-------|-------------|
| `/brief` | Create and manage durable strategic briefs |
| `/brief-status` | Assess progress against the active brief |
| `/checkpoint` | Save a checkpoint with rich description and tags |
| `/handoff` | Produce a structured session-resumption summary for a returning or different agent |
| `/recall` | Restore context from recent checkpoints and the active brief |
| `/standup` | Generate a cross-project standup report |

`skills/` is the canonical source. `.agents/skills/` is a checked-in mirror for clients that scan repo-local skills.

---

## Storage Format

Markdown in `.memories/` is the source of truth. Goldfish does not maintain derived caches; search runs over the markdown corpus on demand.

### Project-Level Storage

```
your-project/
  .memories/
    2026-02-13/
      091500_a1b2.md          # Individual checkpoint (YAML frontmatter + markdown)
      143022_c3d4.md
    2026-02-14/
      101530_e5f6.md
    briefs/
      auth-system-redesign.md  # Brief (YAML frontmatter + markdown body)
      api-v2-migration.md
    .active-brief              # Contains the active brief ID
```

Legacy `.memories/plans/` and `.active-plan` paths are still read so older repos keep working, but new writes land in the brief paths above.

### Checkpoint File Format

```markdown
---
id: checkpoint_a1b2c3d4
timestamp: 2026-02-14T14:30:22.000Z
tags:
  - bug-fix
  - auth
git:
  branch: fix/jwt-timeout
  commit: abc1234
  files:
    - src/auth/jwt.ts
    - tests/auth.test.ts
summary: Fixed JWT timeout bug with refresh token rotation
---

Fixed JWT validation bug where expired tokens were accepted. Root cause
was inverted expiry check in validateToken(). Added test coverage for
the edge case and verified the fix prevents token reuse attacks.
```

### Cross-Project Registry

```
~/.goldfish/
  registry.json              # Auto-populated list of projects using Goldfish
```

The registry tracks which projects have `.memories/` directories. It is populated automatically on checkpoint save and used by cross-project recall for standup reports.

---

## Cross-Project Features

### Standup Reports

Standup reports are built from briefs and checkpoints, not `docs/plans/`.

The `/standup` skill aggregates work across all registered projects:

```
## Standup -- February 14, 2026

### goldfish
- Brief says the current push is cross-client portability for Goldfish
- Checkpoints show roots support landed and repo-local skill mirroring landed

> **Next:** Finish client docs and keep standup scoped to memory evidence

### api-gateway
- Fixed rate limiter race condition in Redis cluster mode

> **Blocked:** Waiting on DevOps for staging Redis cluster provisioning
```

Cross-project recall uses `~/.goldfish/registry.json` to discover projects, then reads each project's `.memories/` directory.

---

## Architecture Decisions

This is **iteration #5** of a developer memory system. Each iteration taught something:

1. **Original Goldfish (TypeScript)** -- Good concepts, critical bugs: race conditions, date handling
2. **Tusk (Bun + SQLite)** -- Fixed bugs, added complexity, hook spam disaster
3. **.NET rewrite** -- Over-engineered, never finished
4. **Goldfish 4.0 (Bun + Markdown)** -- Radical simplicity, centralized `~/.goldfish/` storage, proved the markdown-only approach
5. **Goldfish 5.x-6.x** -- Claude Code plugin, project-local `.memories/`, hybrid semantic recall, consolidation, hooks
6. **Goldfish 7.0** -- Subtract sprint: removed hooks, semantic stack, consolidation, and the plan tool; settled on Orama BM25 over markdown and brief-first storage

Foundational decisions (load-bearing since v5):

| Decision | Rationale |
|----------|-----------|
| Markdown storage, no database | Human-readable, git-friendly, transparent |
| Project-local `.memories/` | Git-committable, travels with the codebase |
| Individual checkpoint files | No merge conflicts, no corruption from concurrent writes |
| Atomic file operations | Write-to-temp then rename prevents corruption on crash |
| UTC timestamps everywhere | No timezone bugs (learned the hard way in v1) |
| Quality-focused behavioral language | Directive about checkpoint quality, restrained about frequency |
| Evidence-based features only | Complexity is added only when real usage demands it |

What v7 subtracted, and why:

| Decision | Rationale |
|----------|-----------|
| Orama BM25 over hybrid fuse + embeddings | LLM-issued queries are well-formed; relevance ranking matters more than typo tolerance, and BM25 is a fraction of the runtime weight |
| No hooks *(reversed in 7.5, narrowly)* | The spam came from recurring hooks, and those stay banned. When harness changes capped server instructions at 2k and deferred tool descriptions out of sight, a SessionStart-only static hook became the fix, not the disease — see `docs/agent-portability.md` |
| No consolidation | Token math was net-negative; reading consolidated digests cost more than reading checkpoints directly |
| Briefs replace plans | Harnesses own session execution planning; Goldfish owns durable strategic context that outlasts a session |
| 3 tools, not more | Checkpoint, recall, brief cover all use cases without bloat |
| Skills over slash commands | Plugin-native, no manual `bun setup` step |

---

## Repository Structure

```
goldfish/
  .agents/
    skills/               # Repo-local skill mirror for Codex/OpenCode
  .claude-plugin/
    plugin.json           # Claude Code plugin manifest
  .codex-plugin/
    plugin.json           # Codex plugin manifest (tools + skills + hooks)
  .mcp.json               # Canonical Codex MCP server map
  hooks/
    goldfish-hooks.json   # SessionStart hook map, shared by both manifests
    session-start.ts      # Prints the session guidance to stdout
  skills/
    brief/SKILL.md        # Canonical brief skill
    brief-status/SKILL.md # Canonical brief-status skill
    checkpoint/SKILL.md   # Canonical checkpoint skill
    handoff/SKILL.md      # Canonical handoff skill
    recall/SKILL.md       # Canonical recall skill
    standup/SKILL.md      # Canonical standup skill
  src/
    server.ts             # MCP server entry point
    tools.ts              # Tool definitions (checkpoint, recall, brief)
    instructions.ts       # Server behavioral instructions
    types.ts              # TypeScript interfaces
    checkpoints.ts        # Checkpoint storage and retrieval
    briefs.ts             # Brief storage and activation
    recall.ts             # Recall aggregation across date ranges and workspaces
    ranking.ts            # Orama BM25 search ranking
    digests.ts            # Compact retrieval/search digests
    file-io.ts            # Atomic write helpers
    logger.ts             # File-based logging
    registry.ts           # Cross-project registry (~/.goldfish/registry.json)
    workspace.ts          # Workspace detection and normalization
    git.ts                # Git context capture
    lock.ts               # File locking for concurrent writes
    summary.ts            # Auto-summary generation
    emoji.ts              # Emoji utilities
    handlers/             # Tool handler implementations (checkpoint, recall, brief)
  tests/                  # Test files
```

---

## Development

**This is a TDD project. Tests are written before implementation. No exceptions.**

```bash
# Run all tests
bun test

# Watch mode (recommended during development)
bun test --watch

# Run a specific test file
bun test tests/checkpoints.test.ts

# Run with coverage
bun test --coverage

# Type check
bun run typecheck
```

### Stats

- **Storage:** markdown source of truth in `.memories/`; cross-project registry at `~/.goldfish/registry.json`
- **Runtime dependencies:** `@modelcontextprotocol/sdk`, `@orama/orama`, `yaml`

### TDD Workflow

1. Write test first (watch it fail)
2. Implement minimum code to pass
3. Refactor if needed (keep tests green)
4. Commit test + implementation together

See `CONTRIBUTING.md` for detailed development patterns.

---

## Performance

| Operation | Target | Actual |
|-----------|--------|--------|
| Checkpoint save | < 50ms | ~10ms |
| Recall (7 days, single project) | < 100ms | ~30ms |
| Recall (7 days, all projects) | < 500ms | ~150ms |
| BM25 search (100 checkpoints) | < 50ms | ~15ms |

Benchmarked on Apple Silicon (M-series).

---

## Troubleshooting

### Plugin not loading

1. Verify the plugin is installed: `claude plugin list`
2. Ensure Bun is installed and available in your PATH
3. Restart Claude Code (plugins load at startup)

### Checkpoints not saving

1. Check that `.memories/` is writable in your project directory
2. Run `bun run src/server.ts` directly to see error output
3. Each checkpoint is ~1KB -- disk space is rarely an issue

### Recall returns nothing

1. Checkpoints are per-project: each project has its own `.memories/` directory
2. Default recall returns last 5 checkpoints regardless of age -- try `recall({ days: 7 })` for date-windowed history
3. Verify checkpoints exist: `ls .memories/` in your project root

### Cross-project recall is empty

1. The registry at `~/.goldfish/registry.json` must have entries
2. Projects are auto-registered on first checkpoint save
3. Check that listed projects still have `.memories/` directories

### Session-start guidance not appearing

1. The hook fires only in sessions started **after** the plugin was installed or updated -- start a new session
2. **Claude Code:** check `/hooks` for Goldfish's SessionStart entry; verify the plugin is enabled (`claude plugin list`)
3. **Codex:** plugin hooks stay silent until trusted -- run `/hooks`, review and trust the Goldfish SessionStart hook, then start a new thread
4. The hook runs `bun`, so Bun must be on your PATH (already true if the MCP tools work)

---

## Documentation

| File | Audience | Content |
|------|----------|---------|
| `README.md` | Users | This file -- overview, installation, usage |
| `CLAUDE.md` | AI agents (developing Goldfish) | TDD rules, architecture, coding patterns |
| `CONTRIBUTING.md` | Contributors | Detailed development guide |
| `docs/IMPLEMENTATION.md` | Contributors | Technical specification |
| `docs/agent-portability.md` | Contributors | Per-harness support tiers, deliberate non-support, drift guards |

---

## License

MIT

---

Fifth time's the charm.

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:

Session starts -- run /recall (or let the agent call recall()) to restore recent checkpoints and the active brief
You work -- checkpoint with /checkpoint at meaningful milestones
Direction persists -- save a brief with /brief when goals, constraints, or success criteria should survive the session
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

Recommended: install the plugin. Goldfish ships a Codex plugin manifest (.codex-plugin/plugin.json) that delivers everything in one install — the MCP server (tools), the 6 skills, and a SessionStart hook that loads Goldfish's memory guidance into each new session.

codex plugin marketplace add anortham/goldfish
codex plugin add goldfish@goldfish

This same install covers the Codex desktop app: restart it after installing and it picks up the plugin.

One-time hook trust review. Installing or enabling a plugin does not automatically trust its hooks — Codex skips them until you approve. Run codex, open /hooks, review and trust Goldfish's SessionStart hook, then start a new thread. Until you do, tools and skills work but the session-start guidance stays silent.

The hook is deliberately minimal: it fires once at session start (and after /clear or a compact), prints static guidance, makes no tool calls, and writes no state.

Manual alternative: .codex/config.toml. If you would rather not install the plugin, register the server yourself. Codex shares MCP configuration between the CLI and the IDE extension through ~/.codex/config.toml, and it 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.

This repository ships a working opencode.json (paths relative to the repo root) you can copy as a starting point.

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.

This repository ships a working .vscode/mcp.json you can copy. To create your own:

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:

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

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 instruction set instead of starting from a blank page.

If you want the closer Claude-style experience, VS Code's agent plugins preview can also load Claude-format plugins. Goldfish already ships .claude-plugin/plugin.json, which VS Code can detect for plugin skills.

Two ways to wire that up:

Register a local Goldfish clone with the chat.pluginLocations setting in settings.json
Add a marketplace with chat.plugins.marketplaces if you want shared discovery instead of a direct local path

Use .vscode/mcp.json when you only want the MCP tools. Use the plugin path when you want skills as well.

Any MCP Client

Goldfish is a standard MCP server, so any client that can launch a local stdio server can use the three core tools (checkpoint, recall, brief) and the server instructions.

What varies by client:

Skills depend on whether the harness reads repo-local skill files such as .agents/skills
Workspace binding depends on roots support, explicit cwd, or GOLDFISH_WORKSPACE

Instruction-Only Harnesses (Zed, Amp, Jules, Cursor rules, Windsurf, Cline, Kiro, ...)

Many harnesses read a repo instruction file (AGENTS.md, .cursor/rules/, .windsurf/rules/, .clinerules/, .kiro/steering/) but never surface MCP server instructions. For those, copy the generated usage ruleset docs/agent-instructions/goldfish-usage.md into your repo's instruction surface.

Honest caveat: this gives the agent Goldfish behavior rules only. The checkpoint/recall/brief tools still need the MCP server registered in that harness (see the sections above); without it the rules have nothing to call.

The full support matrix, including what was deliberately not built and why, lives in docs/agent-portability.md.

How It Works

Checkpoint -- Save Progress

Checkpoints capture what you did, why, and how. They're saved as individual markdown files with YAML frontmatter.

You: "Fix the authentication timeout bug"

Claude: [works on the bug]
Claude: [checkpoints: "Fixed JWT timeout by implementing refresh token rotation.
         Root cause was single-use token with no renewal path. Added
         RefreshTokenStore with 7-day expiry. Auth tests passing."]

[Session crashes or compacts]

You: [new session]
Claude: [auto-recalls checkpoint, picks up where it left off]

Saved to: {project}/.memories/2026-02-14/143022_a1b2.md

Recall -- Restore Context

Recall returns recent checkpoints, the active brief, and optional cross-project summaries. Agents call it at session start; users can run /recall for targeted queries.

recall()                                    # Last 5 checkpoints, no date window
recall({ since: "2h" })                     # Last 2 hours
recall({ search: "auth bug" })              # BM25 search across descriptions
recall({ days: 7, limit: 20, full: true })  # Extended history with metadata
recall({ workspace: "all", days: 1 })       # Cross-project (for standups)
recall({ file: "workspace.ts" })            # Intent-blame: who touched this file?
recall({ symbol: "recoverWorkspace" })      # Intent-blame: who touched this symbol?
recall({ limit: 0 })                        # Active brief only

When you search with recall({ search: "..." }), results are compact by default so agents get dense, low-token snippets. Pass full: true to return full descriptions and metadata instead.

Brief -- Track Durable Direction

Briefs are compact strategic markdown documents that survive across sessions. They appear at the top of every recall() response.

---
id: auth-system-redesign
title: Auth System Redesign
status: active
created: 2026-02-10T10:00:00.000Z
updated: 2026-02-14T14:30:00.000Z
tags: [auth, architecture, security]
---

## Goal

Redesign auth around durable refresh-token sessions.

## Why Now

Timeout bugs and session drift keep burning time across sessions.

## Constraints

- Keep one-release compatibility for existing auth clients
- Do not break admin SSO

## Success Criteria

- Recall and checkpoint evidence line up with the new auth direction
- Standup reports stay consistent with the brief and recent checkpoints

## References

- docs/plans/2026-02-14-auth-system-redesign.md

Saved to: {project}/.memories/briefs/auth-system-redesign.md

Skills

Goldfish ships 6 skills. Claude Code and Codex plugin installs expose them directly; OpenCode (and Codex without the plugin) discovers the same skill content from .agents/skills/.

Skill	What It Does
`/brief`	Create and manage durable strategic briefs
`/brief-status`	Assess progress against the active brief
`/checkpoint`	Save a checkpoint with rich description and tags
`/handoff`	Produce a structured session-resumption summary for a returning or different agent
`/recall`	Restore context from recent checkpoints and the active brief
`/standup`	Generate a cross-project standup report

skills/ is the canonical source. .agents/skills/ is a checked-in mirror for clients that scan repo-local skills.

Storage Format

Markdown in .memories/ is the source of truth. Goldfish does not maintain derived caches; search runs over the markdown corpus on demand.

Project-Level Storage

your-project/
  .memories/
    2026-02-13/
      091500_a1b2.md          # Individual checkpoint (YAML frontmatter + markdown)
      143022_c3d4.md
    2026-02-14/
      101530_e5f6.md
    briefs/
      auth-system-redesign.md  # Brief (YAML frontmatter + markdown body)
      api-v2-migration.md
    .active-brief              # Contains the active brief ID

Legacy .memories/plans/ and .active-plan paths are still read so older repos keep working, but new writes land in the brief paths above.

Checkpoint File Format

---
id: checkpoint_a1b2c3d4
timestamp: 2026-02-14T14:30:22.000Z
tags:
  - bug-fix
  - auth
git:
  branch: fix/jwt-timeout
  commit: abc1234
  files:
    - src/auth/jwt.ts
    - tests/auth.test.ts
summary: Fixed JWT timeout bug with refresh token rotation
---

Fixed JWT validation bug where expired tokens were accepted. Root cause
was inverted expiry check in validateToken(). Added test coverage for
the edge case and verified the fix prevents token reuse attacks.

Cross-Project Registry

~/.goldfish/
  registry.json              # Auto-populated list of projects using Goldfish

The registry tracks which projects have .memories/ directories. It is populated automatically on checkpoint save and used by cross-project recall for standup reports.

Cross-Project Features

Standup Reports

Standup reports are built from briefs and checkpoints, not docs/plans/.

The /standup skill aggregates work across all registered projects:

## Standup -- February 14, 2026

### goldfish
- Brief says the current push is cross-client portability for Goldfish
- Checkpoints show roots support landed and repo-local skill mirroring landed

> **Next:** Finish client docs and keep standup scoped to memory evidence

### api-gateway
- Fixed rate limiter race condition in Redis cluster mode

> **Blocked:** Waiting on DevOps for staging Redis cluster provisioning

Cross-project recall uses ~/.goldfish/registry.json to discover projects, then reads each project's .memories/ directory.

Architecture Decisions

This is iteration #5 of a developer memory system. Each iteration taught something:

Original Goldfish (TypeScript) -- Good concepts, critical bugs: race conditions, date handling
Tusk (Bun + SQLite) -- Fixed bugs, added complexity, hook spam disaster
.NET rewrite -- Over-engineered, never finished
Goldfish 4.0 (Bun + Markdown) -- Radical simplicity, centralized ~/.goldfish/ storage, proved the markdown-only approach
Goldfish 5.x-6.x -- Claude Code plugin, project-local .memories/, hybrid semantic recall, consolidation, hooks
Goldfish 7.0 -- Subtract sprint: removed hooks, semantic stack, consolidation, and the plan tool; settled on Orama BM25 over markdown and brief-first storage

Foundational decisions (load-bearing since v5):

Decision	Rationale
Markdown storage, no database	Human-readable, git-friendly, transparent
Project-local `.memories/`	Git-committable, travels with the codebase
Individual checkpoint files	No merge conflicts, no corruption from concurrent writes
Atomic file operations	Write-to-temp then rename prevents corruption on crash
UTC timestamps everywhere	No timezone bugs (learned the hard way in v1)
Quality-focused behavioral language	Directive about checkpoint quality, restrained about frequency
Evidence-based features only	Complexity is added only when real usage demands it

What v7 subtracted, and why:

Decision	Rationale
Orama BM25 over hybrid fuse + embeddings	LLM-issued queries are well-formed; relevance ranking matters more than typo tolerance, and BM25 is a fraction of the runtime weight
No hooks (reversed in 7.5, narrowly)	The spam came from recurring hooks, and those stay banned. When harness changes capped server instructions at 2k and deferred tool descriptions out of sight, a SessionStart-only static hook became the fix, not the disease — see `docs/agent-portability.md`
No consolidation	Token math was net-negative; reading consolidated digests cost more than reading checkpoints directly
Briefs replace plans	Harnesses own session execution planning; Goldfish owns durable strategic context that outlasts a session
3 tools, not more	Checkpoint, recall, brief cover all use cases without bloat
Skills over slash commands	Plugin-native, no manual `bun setup` step

Repository Structure

goldfish/
  .agents/
    skills/               # Repo-local skill mirror for Codex/OpenCode
  .claude-plugin/
    plugin.json           # Claude Code plugin manifest
  .codex-plugin/
    plugin.json           # Codex plugin manifest (tools + skills + hooks)
  .mcp.json               # Canonical Codex MCP server map
  hooks/
    goldfish-hooks.json   # SessionStart hook map, shared by both manifests
    session-start.ts      # Prints the session guidance to stdout
  skills/
    brief/SKILL.md        # Canonical brief skill
    brief-status/SKILL.md # Canonical brief-status skill
    checkpoint/SKILL.md   # Canonical checkpoint skill
    handoff/SKILL.md      # Canonical handoff skill
    recall/SKILL.md       # Canonical recall skill
    standup/SKILL.md      # Canonical standup skill
  src/
    server.ts             # MCP server entry point
    tools.ts              # Tool definitions (checkpoint, recall, brief)
    instructions.ts       # Server behavioral instructions
    types.ts              # TypeScript interfaces
    checkpoints.ts        # Checkpoint storage and retrieval
    briefs.ts             # Brief storage and activation
    recall.ts             # Recall aggregation across date ranges and workspaces
    ranking.ts            # Orama BM25 search ranking
    digests.ts            # Compact retrieval/search digests
    file-io.ts            # Atomic write helpers
    logger.ts             # File-based logging
    registry.ts           # Cross-project registry (~/.goldfish/registry.json)
    workspace.ts          # Workspace detection and normalization
    git.ts                # Git context capture
    lock.ts               # File locking for concurrent writes
    summary.ts            # Auto-summary generation
    emoji.ts              # Emoji utilities
    handlers/             # Tool handler implementations (checkpoint, recall, brief)
  tests/                  # Test files

Development

This is a TDD project. Tests are written before implementation. No exceptions.

# Run all tests
bun test

# Watch mode (recommended during development)
bun test --watch

# Run a specific test file
bun test tests/checkpoints.test.ts

# Run with coverage
bun test --coverage

# Type check
bun run typecheck

Stats

Storage: markdown source of truth in .memories/; cross-project registry at ~/.goldfish/registry.json
Runtime dependencies: @modelcontextprotocol/sdk, @orama/orama, yaml

TDD Workflow

Write test first (watch it fail)
Implement minimum code to pass
Refactor if needed (keep tests green)
Commit test + implementation together

See CONTRIBUTING.md for detailed development patterns.

Performance

Operation	Target	Actual
Checkpoint save	< 50ms	~10ms
Recall (7 days, single project)	< 100ms	~30ms
Recall (7 days, all projects)	< 500ms	~150ms
BM25 search (100 checkpoints)	< 50ms	~15ms

Benchmarked on Apple Silicon (M-series).

Troubleshooting

Plugin not loading

Verify the plugin is installed: claude plugin list
Ensure Bun is installed and available in your PATH
Restart Claude Code (plugins load at startup)

Checkpoints not saving

Check that .memories/ is writable in your project directory
Run bun run src/server.ts directly to see error output
Each checkpoint is ~1KB -- disk space is rarely an issue

Recall returns nothing

Checkpoints are per-project: each project has its own .memories/ directory
Default recall returns last 5 checkpoints regardless of age -- try recall({ days: 7 }) for date-windowed history
Verify checkpoints exist: ls .memories/ in your project root

Cross-project recall is empty

The registry at ~/.goldfish/registry.json must have entries
Projects are auto-registered on first checkpoint save
Check that listed projects still have .memories/ directories

Session-start guidance not appearing

The hook fires only in sessions started after the plugin was installed or updated -- start a new session
Claude Code: check /hooks for Goldfish's SessionStart entry; verify the plugin is enabled (claude plugin list)
Codex: plugin hooks stay silent until trusted -- run /hooks, review and trust the Goldfish SessionStart hook, then start a new thread
The hook runs bun, so Bun must be on your PATH (already true if the MCP tools work)

Documentation

File	Audience	Content
`README.md`	Users	This file -- overview, installation, usage
`CLAUDE.md`	AI agents (developing Goldfish)	TDD rules, architecture, coding patterns
`CONTRIBUTING.md`	Contributors	Detailed development guide
`docs/IMPLEMENTATION.md`	Contributors	Technical specification
`docs/agent-portability.md`	Contributors	Per-harness support tiers, deliberate non-support, drift guards

License

MIT

Fifth time's the charm.