smart_search

Instructions

Implementation Reference

• src/src/index.ts:547-566 (registration)

  Tool registration for smart_search in the TOOLS array, with name, description, and inputSchema (query required, limit optional).

  {
    name: "smart_search",
    description:
      "Search for skills with your history and preferences automatically applied. Returns personalized results excluding skills you already have. Use this by default instead of search_skills.",
    inputSchema: {
      type: "object" as const,
      properties: {
        query: {
          type: "string",
          description:
            "Natural language search query. Examples: 'postgres database', 'browser automation', 'github issues'",
        },
        limit: {
          type: "number",
          description: "Max results to return (default 10, max 25)",
        },
      },
      required: ["query"],
    },
  },

• src/src/index.ts:1060-1098 (handler)

  Handler function handleSmartSearch that loads agent memory, extracts installed slugs and recent searches, calls the search API, records the query, filters out already-installed skills, and returns personalized results with metadata.

  async function handleSmartSearch(args: {
    query: string;
    limit?: number;
  }): Promise<string> {
    // Load all agent memory (installed skills, recent searches, preferences)
    const memories = await loadAgentMemory();
    const installedSlugs = extractInstalledSlugs(memories);
    const recentSearches = extractRecentSearches(memories);
  
    const params = new URLSearchParams({ q: args.query });
    if (args.limit) params.set("limit", String(args.limit));
  
    const result = await fetchJSON(`${API_BASE}/search?${params.toString()}`, {
      "X-Agent-Key": AGENT_KEY,
    });
  
    // Fire-and-forget: record this search query
    recordSearchQuery(args.query, recentSearches);
  
    // Filter out already-installed skills
    const parsed = result as { results?: Array<{ slug?: string }>; [k: string]: unknown };
    const excludedCount = { value: 0 };
    if (parsed.results && installedSlugs.length > 0) {
      const installedSet = new Set(installedSlugs);
      const originalLength = parsed.results.length;
      parsed.results = parsed.results.filter((r) => !r.slug || !installedSet.has(r.slug));
      excludedCount.value = originalLength - parsed.results.length;
    }
  
    // Add metadata about personalization
    const output: Record<string, unknown> = { ...parsed };
    output._personalization = {
      installed_skills_excluded: excludedCount.value,
      installed_skills_count: installedSlugs.length,
      recent_searches: recentSearches.slice(-5),
    };
  
    return JSON.stringify(output, null, 2);
  }

• src/src/index.ts:581-592 (helper)

  Helper function loadAgentMemory that fetches agent memory entries from the API.

  async function loadAgentMemory(typeFilter?: string): Promise<AgentMemoryEntry[]> {
    try {
      const params = new URLSearchParams({ agent_key: AGENT_KEY });
      if (typeFilter) params.set("type", typeFilter);
      const result = (await fetchJSON(`${API_BASE}/memory?${params.toString()}`)) as {
        memories?: AgentMemoryEntry[];
      };
      return result.memories ?? [];
    } catch {
      return [];
    }
  }

• src/src/index.ts:597-604 (helper)

  Helper function extractInstalledSlugs that extracts installed skill slugs from agent memory.

  function extractInstalledSlugs(memories: AgentMemoryEntry[]): string[] {
    for (const m of memories) {
      if (m.key === "installed_skills" && Array.isArray(m.value)) {
        return m.value as string[];
      }
    }
    return [];
  }

• src/src/index.ts:609-636 (helper)

  Helper functions extractRecentSearches and recordSearchQuery that manage the recent search history in agent memory.

  function extractRecentSearches(memories: AgentMemoryEntry[]): string[] {
    for (const m of memories) {
      if (m.key === "recent_searches" && Array.isArray(m.value)) {
        return m.value as string[];
      }
    }
    return [];
  }
  
  /**
   * Fire-and-forget save to agent memory. Never throws.
   */
  function saveMemoryAsync(key: string, value: unknown, type: string): void {
    postJSON(`${API_BASE}/memory`, {
      agent_key: AGENT_KEY,
      key,
      value,
      type,
    }).catch(() => {});
  }
  
  /**
   * Append a search query to the recent_searches memory (keep last 20).
   */
  function recordSearchQuery(query: string, existingSearches: string[]): void {
    const updated = [...existingSearches.filter((q) => q !== query), query].slice(-20);
    saveMemoryAsync("recent_searches", updated, "search");
  }