session_search_memory

Search session history by meaning using semantic vector embeddings to find relevant sessions even when wording differs from your query.

Instructions

Search session history semantically (by meaning, not just keywords). Uses vector embeddings to find sessions with similar context, even when the exact wording differs. Requires pgvector extension in Supabase.

Complements knowledge_search (keyword-based) — use this when keyword search returns no results or when the query is phrased differently from stored summaries.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	Yes	Natural language search query describing what you're looking for.
`project`	No	Optional: limit search to a specific project.
`limit`	No	Maximum results to return (default: 5, max: 20).
`similarity_threshold`	No	Minimum similarity score 0-1 (default: 0.7). Higher = more relevant, fewer results.

Implementation Reference

src/tools/sessionMemoryHandlers.ts:679-785 (handler)

Handler function for the session_search_memory MCP tool, which performs a semantic (vector-based) search across session memory.

export async function sessionSearchMemoryHandler(args: unknown) {
  if (!isSessionSearchMemoryArgs(args)) {
    throw new Error("Invalid arguments for session_search_memory");
  }

  const {
    query,
    project,
    limit = 5,
    similarity_threshold = 0.7,
  } = args;

  console.error(
    `[session_search_memory] Semantic search: query="${query}", ` +
    `project=${project || "all"}, limit=${limit}, threshold=${similarity_threshold}`
  );

  // Step 1: Generate embedding for the search query
  if (!GOOGLE_API_KEY) {
    return {
      content: [{
        type: "text",
        text: `❌ Semantic search requires GOOGLE_API_KEY for embedding generation.\n` +
          `Set this environment variable and restart the server.\n\n` +
          `💡 As a workaround, try knowledge_search (keyword-based) instead.`,
      }],
      isError: true,
    };
  }

  let queryEmbedding: number[];
  try {
    queryEmbedding = await generateEmbedding(query);
  } catch (err) {
    return {
      content: [{
        type: "text",
        text: `❌ Failed to generate embedding for query: ${err instanceof Error ? err.message : String(err)}\n\n` +
          `💡 Try knowledge_search (keyword-based) as a fallback.`,
      }],
      isError: true,
    };
  }

  // Step 2: Search via storage backend
  try {
    const storage = await getStorage();
    const results = await storage.searchMemory({
      queryEmbedding: JSON.stringify(queryEmbedding),
      project: project || null,
      limit: Math.min(limit, 20),
      similarityThreshold: similarity_threshold,
      userId: PRISM_USER_ID,
    });

    if (results.length === 0) {
      return {
        content: [{
          type: "text",
          text: `🔍 No semantically similar sessions found for: "${query}"\n` +
            (project ? `Project: ${project}\n` : "") +
            `Similarity threshold: ${similarity_threshold}\n\n` +
            `Tips:\n` +
            `• Lower the similarity_threshold (e.g., 0.5) for broader results\n` +
            `• Try knowledge_search for keyword-based matching\n` +
            `• Ensure sessions have been saved with embeddings (requires GOOGLE_API_KEY)`,
        }],
        isError: false,
      };
    }

    // Format results with similarity scores
    const formatted = results.map((r: any, i: number) => {
      const score = typeof r.similarity === "number"
        ? `${(r.similarity * 100).toFixed(1)}%`
        : "N/A";
      return `[${i + 1}] ${score} similar — ${r.session_date || "unknown date"}\n` +
        `  Project: ${r.project}\n` +
        `  Summary: ${r.summary}\n` +
        (r.decisions?.length ? `  Decisions: ${r.decisions.join("; ")}\n` : "") +
        (r.files_changed?.length ? `  Files: ${r.files_changed.join(", ")}\n` : "");
    }).join("\n");

    return {
      content: [{
        type: "text",
        text: `🧠 Found ${results.length} semantically similar sessions:\n\n${formatted}`,
      }],
      isError: false,
    };
  } catch (err) {
    const errorMsg = err instanceof Error ? err.message : String(err);
    if (errorMsg.includes("vector") || errorMsg.includes("does not exist")) {
      return {
        content: [{
          type: "text",
          text: `❌ Semantic search is not available: pgvector extension may not be enabled.\n\n` +
            `To fix: Go to Supabase Dashboard → Database → Extensions → enable "vector"\n` +
            `Then run migration 018_semantic_search.sql\n\n` +
            `💡 Use knowledge_search (keyword-based) as an alternative.`,
        }],
        isError: true,
      };
    }
    throw err;
  }
}

src/tools/sessionMemoryDefinitions.ts:401-406 (schema)
Argument validation and type definition for the session_search_memory tool.
```
export function isSessionSearchMemoryArgs(
  args: unknown
): args is {
  query: string;
  project?: string;
  limit?: number;
```

src/tools/sessionMemoryDefinitions.ts:261-266 (registration)

Tool definition and schema for session_search_memory.

export const SESSION_SEARCH_MEMORY_TOOL: Tool = {
  name: "session_search_memory",
  description:
    "Search session history semantically (by meaning, not just keywords). " +
    "Uses vector embeddings to find sessions with similar context, even when " +
    "the exact wording differs. Requires pgvector extension in Supabase.\n\n" +

Prism MCP