COA Goldfish MCP

Instructions

Implementation Reference

• archive/src/tools/search.ts:265-372 (handler)

  Core handler function for the 'recall' tool. Performs fuzzy memory search (or recent recall without query), formats results with timestamps, workspaces, content summaries, and tags. Returns structured RecallResponse via buildToolContent.

  async recall(args: {
    query?: string;
    since?: string;
    workspace?: string;
    scope?: 'current' | 'all';
    type?: string;
    tags?: string[];
    limit?: number;
    format?: OutputMode;
  }) {
    const {
      query,
      since = '7d',
      workspace,
      scope = 'current',
      type,
      tags,
      limit = 10,
      format
    } = args;
  
    try {
      let memories;
      
      if (query) {
        // Use fuzzy search
        memories = await this.searchEngine.searchMemories({
          query,
          since,
          workspace,
          scope,
          type,
          tags,
          limit
        });
      } else {
        // Return recent memories
        memories = await this.searchEngine.searchMemories({
          since,
          workspace,
          scope,
          type,
          tags,
          limit
        });
      }
  
      if (memories.length === 0) {
        const searchInfo = query ? ` matching "${query}"` : '';
        const formatted = `🧠 No memories found${searchInfo} in the last ${since}`;
        const data = { query, since, scope, workspace, memoriesFound: 0 } as const;
        return buildToolContent('recall', formatted, data as any, format);
      }
  
      // Build formatted output
      const output = ['🧠 Recent Memories:'];
  
      for (const memory of memories) {
        const age = this.formatAge(memory.timestamp);
        const typeIcon = this.getTypeIcon(memory.type);
        const workspaceInfo = memory.workspace === this.storage.getCurrentWorkspace() 
          ? '' 
          : ` [${memory.workspace}]`;
  
        output.push(`${typeIcon} [${memory.id.slice(-6)}] ${age}${workspaceInfo}`);
        
        if (typeof memory.content === 'object' && memory.content && 'description' in memory.content) {
          const contentObj = memory.content as { description?: string };
          output.push(`   ${contentObj.description}`);
        } else {
          const contentStr = typeof memory.content === 'string' 
            ? memory.content 
            : JSON.stringify(memory.content);
          output.push(`   ${contentStr.slice(0, 200)}${contentStr.length > 200 ? '...' : ''}`);
        }
  
        if (memory.tags && memory.tags.length > 0) {
          output.push(`   Tags: ${memory.tags.join(', ')}`);
        }
  
        output.push('');
      }
  
      const formatted = output.join('\n');
      const data = {
        memoriesFound: memories.length,
        timeRange: since,
        memories: memories.map(m => ({
          id: m.id,
          type: m.type,
          age: this.formatAge(m.timestamp),
          content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
          workspace: m.workspace,
          tags: m.tags
        }))
      } as const;
      return buildToolContent('recall', formatted, data as any, format);
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `❌ Recall failed: ${error instanceof Error ? error.message : String(error)}`
          }
        ]
      };
    }
  }

• archive/src/tools/search.ts:493-540 (schema)

  Input schema and metadata for the 'recall' tool, defining optional query, time range, workspace filters, tags, and output format. Provided via SearchTools.getToolSchemas().

  {
    name: 'recall',
    description: 'Restore working context after breaks or /clear. Shows recent activity without query. Use when resuming work sessions.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query (optional - if not provided, shows recent memories)'
        },
        since: {
          type: 'string',
          description: 'Time range (default: "7d")',
          default: '7d'
        },
        workspace: {
          type: 'string',
          description: 'Workspace name or path (e.g., "coa-goldfish-mcp" or "C:\\source\\COA Goldfish MCP"). Will be normalized automatically.'
        },
        scope: {
          type: 'string',
          enum: ['current', 'all'],
          description: 'Search scope (default: "current")',
          default: 'current'
        },
        type: {
          type: 'string',
          enum: ['checkpoint'],
          description: 'Content type filter - only checkpoints available (Memory objects deprecated)'
        },
        tags: {
          type: 'array',
          items: { type: 'string' },
          description: 'Filter by exact tags (all tags must match)'
        },
        limit: {
          type: 'number',
          description: 'Maximum results (default: 10)',
          default: 10
        },
        format: {
          type: 'string',
          enum: ['plain', 'emoji', 'json', 'dual'],
          description: 'Output format override (defaults to env GOLDFISH_OUTPUT_MODE or dual)'
        }
      }
    }
  }

• archive/src/types/responses.ts:29-41 (schema)

  TypeScript interface defining the structured output response for the 'recall' tool.

  export interface RecallResponse extends FormattedResponse {
    operation: 'recall';
    memoriesFound: number;
    timeRange: string;
    memories?: Array<{
      id: string;
      type: string;
      age: string;
      content: string;
      workspace?: string;
      tags?: string[];
    }>;
  }

• archive/src/index.ts:128-129 (registration)

  Tool dispatch registration in the main CallToolRequest handler switch statement, routing 'recall' calls to this.searchTools.recall().

  case 'recall':
    return await this.searchTools.recall(args || {});

• archive/src/index.ts:84-107 (registration)

  Tool list registration: includes SearchTools.getToolSchemas() (containing 'recall') in the list of available tools returned by ListToolsRequest.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        // Unified checkpoint tool (replaces checkpoint, restore_session, and search functionality)
        UnifiedCheckpointTool.getToolSchema(),
        
        // Search and timeline tools
        ...SearchTools.getToolSchemas(),
        
        // Unified TODO tool (replaces create_todo_list, view_todos, update_todo)
        getTodoToolSchema(),
        
        // Plan tool for strategic planning and design decisions
        getPlanToolSchema(),
        
        // Standup tool for intelligent work aggregation and reporting
        getStandupToolSchema(),
        
        getListWorkspacesToolSchema(),
        
        // Intel tool for project knowledge management  
        getIntelToolSchema()
      ],
    };