Skip to main content
Glama
COA Goldfish MCP

COA Goldfish MCP

by anortham

COA Goldfish MCP (.NET)

Your development session's "flight recorder" - now with SQLite persistence and behavioral enforcement

๐Ÿ  What is Goldfish (.NET)?

Goldfish .NET is a crash-safe developer's work journal rebuilt from the ground up with:

  • SQLite Database - Fast, reliable persistence with Entity Framework Core

  • Behavioral Enforcement - AI agents guided to use tools correctly and consistently

  • Streamlined Architecture - 7 unified tools that work as a cohesive system

  • Global Workspace Support - Cross-project TODOs and plans

  • Optional API Sync - Enterprise-ready with offline-first design

  • 10x Performance - Faster data correlations and queries

Related MCP server: GroundMemory

๐Ÿš€ Installation

# Install as global .NET tool
dotnet tool install -g COA.Goldfish

# Add to Claude Code MCP configuration
# Edit ~/.claude/settings.json:
{
  "mcpServers": {
    "goldfish": {
      "type": "stdio", 
      "command": "goldfish",
      "args": [],
      "env": {}
    }
  }
}

Method 2: Local Development

# Clone and build
git clone [repository-url]
cd "COA Goldfish MCP/dotnet"
dotnet build

# Run directly
dotnet run --project src/COA.Goldfish.McpServer

# Or add to Claude Code with full path:
# "command": "C:/path/to/COA Goldfish MCP/dotnet/src/COA.Goldfish.McpServer/bin/Debug/net9.0/COA.Goldfish.McpServer.exe"

๐Ÿ›  Core Tools (Streamlined Architecture)

Unified Smart Tools

Goldfish .NET provides 7 main tools that enforce a cohesive workflow:

1. mcp__goldfish__plan - Strategic Planning with Discovery Accumulation

  • Design features and create implementation roadmaps

  • Track discoveries and lessons learned during development

  • Generate TODO lists automatically from plans

  • Active Plan Concept - ONE active plan per workspace at a time

You: "Create a plan for implementing OAuth2 authentication"
Goldfish: Creates structured plan with items, discoveries field, and optional TODO generation

2. mcp__goldfish__todo - Smart Task Management

  • Create and manage persistent TODO lists

  • Active List Concept - ONE active TODO list per workspace

  • Smart keyword resolution: "latest", "active", "current"

  • Automatic cleanup of completed/stale tasks

You: "Add urgent task to active list"
Goldfish: Adds to your current active TODO list without needing exact IDs

3. mcp__goldfish__checkpoint - Session State Management

  • Save/restore complete work context with workspace detection

  • Automatic file tracking, git branch capture, session correlation

  • Behavioral Enforcement - AI agents guided to checkpoint regularly

You: "Save checkpoint: Completed JWT implementation with refresh tokens"  
Goldfish: Captures description, active files, git branch, session context

4. mcp__goldfish__standup - Cross-Tool Progress Summaries

  • Daily/weekly/project summaries across all workspaces

  • Enhanced Reporting - Correlates data from checkpoints, TODOs, plans

  • Timeline integration for comprehensive progress tracking

You: "Generate daily standup report"
Goldfish: Shows yesterday's checkpoints, TODO progress, plan updates across all projects

5. mcp__goldfish__recall - Context Restoration

  • Quick access to recent memories and work context

  • Cross-tool search for finding past decisions and solutions

  • No parameters needed - just instant context restoration

You: "What was I working on?"
Goldfish: Shows recent checkpoints, active TODOs, current plans

6. mcp__goldfish__chronicle - Decision and Progress Tracking

  • NEW - Replaces standalone Intel tool with integrated decision tracking

  • Auto-populated from other tools or manual entry creation

  • Chronological progress logging for audit trails

You: "Record decision: Using PostgreSQL over MongoDB for better transaction support"
Goldfish: Creates chronicle entry with timestamp, links to related plans/TODOs

7. mcp__goldfish__workspace - Active Work State Management

  • NEW - Manages active plan and TODO list per workspace

  • Enforces the "ONE active item" concept for focused work

  • Cleanup orphaned work and validate workspace state

You: "Set active plan to user-authentication-plan" 
Goldfish: Makes this the active plan, deactivates others, validates workspace state

๐ŸŽฏ Key Improvements Over TypeScript Version

Behavioral Enforcement System

  • AI Agent Guidance - Tools work together as a system, not isolated commands

  • Active Work State - Enforces ONE active plan and TODO list per workspace

  • Automatic State Management - Prevents stale/orphaned work items

  • Workflow Validation - Ensures proper tool usage patterns

Performance & Architecture

  • SQLite + Entity Framework Core - 10x faster than JSON file operations

  • Structured Queries - Complex data correlations and cross-tool summaries

  • Transaction Safety - ACID compliance for data integrity

  • Automatic Migrations - Schema updates handled seamlessly

Enterprise Features

  • Optional API Sync - Sync data across teams/devices with offline-first design

  • Global Workspace - Cross-project TODO lists and plans using __global__ workspace

  • Audit Trails - Complete history via Chronicle entries

  • Backup & Recovery - Built-in database backup during migrations

๐Ÿ“Š Database Schema

Core Entities

public class WorkspaceState 
{
    public string WorkspaceId { get; set; }
    public string? ActivePlanId { get; set; }      // ONE active plan
    public string? ActiveTodoListId { get; set; }  // ONE active TODO list  
    public DateTime LastActivity { get; set; }
}

public class Plan
{
    public string Id { get; set; }
    public string WorkspaceId { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public PlanStatus Status { get; set; }      // Draft, Active, Complete, Abandoned
    public List<string> Items { get; set; }
    public List<string> Discoveries { get; set; }  // NEW - replaces Intel tool
    public DateTime CreatedAt { get; set; }
}

public class TodoList
{
    public string Id { get; set; }
    public string WorkspaceId { get; set; }
    public string Title { get; set; }
    public bool IsActive { get; set; }          // Active list concept
    public List<TodoItem> Items { get; set; }
    public DateTime CreatedAt { get; set; }
}

public class ChronicleEntry  // NEW - Decision tracking
{
    public string Id { get; set; }
    public string WorkspaceId { get; set; }
    public DateTime Timestamp { get; set; }
    public ChronicleEntryType Type { get; set; }  // Decision, Milestone, Issue, Resolution
    public string Description { get; set; }
    public string? RelatedPlanId { get; set; }    // Link to plans
    public string? RelatedTodoId { get; set; }    // Link to TODOs
}

๐Ÿ”ง Configuration

Database Location

# Default: ~/.coa/goldfish/goldfish.db
# Override with connection string:
export GOLDFISH_DATABASE_CONNECTION_STRING="Data Source=/custom/path/goldfish.db"

# Or set base path (goldfish.db will be created there):
export COA_GOLDFISH_BASE_PATH="/custom/goldfish/storage"

API Sync (Optional)

{
  "Goldfish": {
    "Sync": {
      "Enabled": true,
      "ApiUrl": "https://your-goldfish-api.com",
      "ApiKey": "your-api-key"
    }
  }
}

Behavioral Enforcement Levels

{
  "Goldfish": {
    "Enforcement": {
      "Level": "StronglyUrge",  // None, Suggest, StronglyUrge, Require
      "RequireActiveWork": true,
      "AutoCleanupDays": 7
    }
  }
}

๐Ÿš€ Usage Examples

Morning Workflow

You: "What's my current work state?"
Goldfish: 
- Active Plan: "User Authentication System" (3/7 items complete)
- Active TODO: "API Endpoints" (2 pending tasks)
- Last Checkpoint: "JWT validation complete" (yesterday 4:30 PM)

Strategic Planning

You: "Create plan for database migration to PostgreSQL"
Goldfish: Creates plan with structured items, then asks:
"Would you like me to generate a TODO list from this plan?"

You: "Yes, create TODO list"
Goldfish: 
- Creates TODO list with plan items
- Sets as active TODO list
- Links plan and TODO list in database

Cross-Workspace Reporting

You: "Generate weekly standup across all projects"
Goldfish:
## Weekly Standup (Sept 2-8, 2025)

**Completed Across All Projects:**
- goldfish-mcp: Migration to .NET complete (23 checkpoints)
- api-project: OAuth2 integration (15 checkpoints)  
- client-portal: UI redesign phase 1 (8 checkpoints)

**Active Work:**
- 3 active plans across projects
- 12 pending TODO items
- Next: API testing and deployment

Decision Tracking

You: "Record decision: Using Entity Framework Core over Dapper for better migration support"
Goldfish: Creates chronicle entry linked to current active plan, searchable in future

๐Ÿงช Development & Testing

# Run all tests
dotnet test

# Run specific test project
dotnet test tests/COA.Goldfish.McpServer.Tests/
dotnet test tests/COA.Goldfish.IntegrationTests/

# Development with hot reload
dotnet watch run --project src/COA.Goldfish.McpServer

# Database migrations
dotnet ef migrations add NewMigration --project src/COA.Goldfish.McpServer
dotnet ef database update --project src/COA.Goldfish.McpServer

๐Ÿ“ฆ Migration from TypeScript Version

If you have existing TypeScript Goldfish data:

# Run migration tool (will scan ~/.coa/goldfish automatically)
cd dotnet
dotnet run --project src/COA.Goldfish.Migration

# Or specify custom paths:
dotnet run --project src/COA.Goldfish.Migration -- "/custom/json/path" "Data Source=/custom/db/path"

Note: Migration preserves all checkpoints, TODO lists, and plans while converting them to the new SQLite schema.

๐ŸŽฏ Behavioral Philosophy

Active Work Concept

  • ONE active plan per workspace - Enforces focused strategic work

  • ONE active TODO list per workspace - Prevents task fragmentation

  • Automatic cleanup - Stale work items are automatically archived

  • AI agent guidance - Built-in templates encourage proper usage patterns

Tool Priorities for AI Agents

  1. Plan (90) - Strategic thinking first

  2. Todo (95) - Task management

  3. Checkpoint (100) - Session persistence

  4. Standup (85) - Progress reporting

  5. Recall (80) - Context restoration

  6. Chronicle (75) - Decision tracking

  7. Workspace (70) - State management

๐Ÿ— Architecture Overview

src/
โ”œโ”€โ”€ COA.Goldfish.McpServer/           # Main MCP server
โ”‚   โ”œโ”€โ”€ Program.cs                    # Entry point with behavioral enforcement
โ”‚   โ”œโ”€โ”€ Models/                       # EF Core entities  
โ”‚   โ”œโ”€โ”€ Services/                     # Business logic layer
โ”‚   โ”‚   โ”œโ”€โ”€ Storage/                  # Database context and services
โ”‚   โ”‚   โ”œโ”€โ”€ WorkspaceService.cs       # Workspace state management
โ”‚   โ”‚   โ””โ”€โ”€ SyncService.cs            # Optional API sync
โ”‚   โ”œโ”€โ”€ Tools/                        # 7 MCP tools
โ”‚   โ””โ”€โ”€ Templates/                    # Behavioral adoption templates
โ””โ”€โ”€ COA.Goldfish.Migration/           # Data migration from TypeScript

๐Ÿš€ Deployment

Global Tool Package

# Build and pack
dotnet pack src/COA.Goldfish.McpServer -c Release

# Install locally for testing
dotnet tool install -g COA.Goldfish --add-source ./src/COA.Goldfish.McpServer/bin/Release

# Publish to NuGet (when ready)
dotnet nuget push COA.Goldfish.*.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json

Container Deployment (API Sync Server)

FROM mcr.microsoft.com/dotnet/aspnet:9.0
COPY . /app
WORKDIR /app
EXPOSE 80
ENTRYPOINT ["dotnet", "COA.Goldfish.McpServer.dll"]

๐Ÿ“„ License

MIT License - Build amazing workflows with structured persistence!


Ready to upgrade? The .NET version provides everything the TypeScript version offered, plus enterprise features, better performance, and AI agent behavioral enforcement for more productive development sessions.

Available Tools

10 tools
checkpointB

Create a checkpoint to save current progress. Use frequently for crash-safe development. Required: description only. Optional: add context like files, branch, highlights for detailed session tracking.

Inputs: description (required), activeFiles, gitBranch, global, +4 more.

create_todo_listA

Create TODO list tied to current session. Use when user mentions multiple tasks or planning work.

Inputs: items (required), title (required), tags.

recallB

Enhanced memory recall with fuzzy search support. Can search or just show recent memories. Perfect for "what did I work on yesterday?" questions.

Inputs: limit, query, scope, since, +2 more.

rememberA

Store a quick thought or note in current session. For detailed checkpoints use checkpoint tool instead.

Inputs: content (required), tags, ttlHours, type.

restore_sessionB

Restore session state after /clear or break. Default shows last checkpoint + highlights. Use depth: "full" for complete session replay when returning after days away.

Inputs: depth, sessionId, workspace.

search_historyB

Search work history with fuzzy matching. Perfect for "Did we fix the auth bug last week?" type questions. Searches across checkpoints and finds relevant work.

Inputs: query (required), limit, scope, since, +1 more.

summarize_sessionB

Create AI-condensed summary of session or recent work. Perfect for "what did I accomplish today?" or understanding long sessions.

Inputs: depth, sessionId, since, workspace.

timelineB

Show timeline of work sessions. Perfect for standups and understanding recent activity across projects. Shows checkpoints grouped by date and workspace.

Inputs: scope, since, workspace.

update_todoC

Update task status or add new tasks to existing lists. Mark tasks done as you work.

Inputs: delete, itemId, listId, newTask, +2 more.

view_todosB

View active TODO lists and their progress. Perfect for checking current status.

Inputs: listId, showCompleted.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.5/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between 'recall' and 'search_history' (both involve searching memory), and 'remember' and 'checkpoint' (both store information, though with different scopes). Descriptions help clarify the differences, but an agent might occasionally confuse these pairs.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures (e.g., create_todo_list, search_history, update_todo). There are no deviations in naming style, making the set predictable and easy to parse.

    Tool Count5/5

    With 10 tools, the count is well-scoped for a session management and productivity server. Each tool serves a specific function in tracking, recalling, and organizing work, with no apparent redundancy or missing essential operations for the domain.

    Completeness4/5

    The toolset covers core session management workflows comprehensively, including saving (checkpoint), recalling (recall, search_history), organizing (create_todo_list, update_todo, view_todos), and summarizing (summarize_session, timeline). A minor gap is the lack of a tool to delete or archive old sessions or TODOs, but agents can work around this.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A self-hosted MCP server that provides AI assistants with a shared, persistent SQLite-backed memory for storing and retrieving project context, decisions, and discoveries. It enables cross-session continuity and team-wide knowledge sharing to keep AI coding tools aligned and informed.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP-native, local-first memory server that gives AI agents persistent, structured memory across sessions and tools, enabling them to maintain identity and context without reconfiguration.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP memory server that gives AI assistants durable project memory across coding sessions, storing context, changes, and decisions.
      1
      MIT