Search Operations

/**
 * Search memories with advanced filtering
 * @param params - Search parameters with query and options
 * @returns Promise resolving to document search results
 */
documents(params: SearchDocumentsParams): APIPromise<SearchDocumentsResponse>;

interface SearchDocumentsParams {
  /** Search query string (required) */
  q: string;
  /** @deprecated Optional category filters */
  categoriesFilter?: Array<"technology" | "science" | "business" | "health">;
  /** Chunk selection sensitivity (0=more results, 1=accurate results) */
  chunkThreshold?: number;
  /** Container tags for filtering */
  containerTags?: string[];
  /** Search within specific document ID */
  docId?: string;
  /** Document selection sensitivity (0=more results, 1=accurate results) */
  documentThreshold?: number;
  /** Advanced filtering with AND/OR logic */
  filters?: FilterExpression | { [key: string]: unknown };
  /** Include full document content in response */
  includeFullDocs?: boolean;
  /** Include document summary in response */
  includeSummary?: boolean;
  /** Maximum number of results */
  limit?: number;
  /** Return only matching chunks without context */
  onlyMatchingChunks?: boolean;
  /** Rerank results based on query relevance */
  rerank?: boolean;
  /** Rewrite query for better document matching (+400ms latency) */
  rewriteQuery?: boolean;
}

interface SearchDocumentsResponse {
  results: DocumentResult[];
  timing: number;
  total: number;
}

interface DocumentResult {
  chunks: DocumentChunk[];
  createdAt: string;
  documentId: string;
  metadata: { [key: string]: unknown } | null;
  score: number;
  title: string | null;
  type: string | null;
  updatedAt: string;
  content?: string | null; // When includeFullDocs=true
  summary?: string | null; // When includeSummary=true
}

interface DocumentChunk {
  content: string;
  isRelevant: boolean;
  score: number;
}

import Supermemory from "supermemory";

const client = new Supermemory({ apiKey: "your-api-key" });

// Basic document search
const basicSearch = await client.search.documents({
  q: "machine learning algorithms",
  limit: 10,
});

// Advanced search with filtering
const advancedSearch = await client.search.documents({
  q: "neural networks",
  containerTags: ["ai-research", "papers"],
  includeFullDocs: true,
  rerank: true,
  documentThreshold: 0.7,
  filters: {
    AND: [
      { type: "pdf" },
      { metadata: { category: "research" } }
    ]
  },
});

// Focused document search
const focusedSearch = await client.search.documents({
  q: "specific concept",
  docId: "document-id-123",
  onlyMatchingChunks: true,
  chunkThreshold: 0.8,
});

/**
 * Search memories with advanced filtering (alias for documents)
 * @param params - Search parameters identical to documents()
 * @returns Promise resolving to search results
 */
execute(params: SearchExecuteParams): APIPromise<SearchExecuteResponse>;

// SearchExecuteParams and SearchExecuteResponse are identical to
// SearchDocumentsParams and SearchDocumentsResponse respectively

/**
 * Search memory entries - Low latency for conversational
 * @param params - Memory search parameters
 * @returns Promise resolving to memory search results
 */
memories(params: SearchMemoriesParams): APIPromise<SearchMemoriesResponse>;

interface SearchMemoriesParams {
  /** Search query string (required) */
  q: string;
  /** Single container tag for filtering */
  containerTag?: string;
  /** Advanced filtering with AND/OR logic */
  filters?: FilterExpression | { [key: string]: unknown };
  /** Control what additional data to include */
  include?: MemorySearchInclude;
  /** Maximum number of results */
  limit?: number;
  /** Rerank results based on query relevance */
  rerank?: boolean;
  /** Rewrite query for better matching (+400ms latency) */
  rewriteQuery?: boolean;
  /** Memory selection sensitivity (0=more results, 1=accurate results) */
  threshold?: number;
}

interface MemorySearchInclude {
  /** Include associated documents */
  documents?: boolean;
  /** Include parent/child contextual memories */
  relatedMemories?: boolean;
  /** Include memory summaries */
  summaries?: boolean;
}

interface SearchMemoriesResponse {
  results: MemoryResult[];
  timing: number;
  total: number;
}

interface MemoryResult {
  id: string;
  memory: string;
  metadata: { [key: string]: unknown } | null;
  similarity: number;
  updatedAt: string;
  context?: MemoryContext;
  documents?: AssociatedDocument[];
  version?: number | null;
}

interface MemoryContext {
  children?: ContextualMemory[];
  parents?: ContextualMemory[];
}

interface ContextualMemory {
  memory: string;
  relation: "updates" | "extends" | "derives";
  updatedAt: string;
  metadata?: { [key: string]: unknown } | null;
  version?: number | null;
}

interface AssociatedDocument {
  id: string;
  createdAt: string;
  metadata: { [key: string]: unknown } | null;
  title: string;
  type: string;
  updatedAt: string;
}

// Basic memory search
const memorySearch = await client.search.memories({
  q: "Python programming tips",
  limit: 5,
});

// Conversational search with context
const contextualSearch = await client.search.memories({
  q: "how to optimize performance",
  containerTag: "user_123",
  include: {
    relatedMemories: true,
    documents: true,
  },
  threshold: 0.6,
});

// Advanced memory search
const advancedMemorySearch = await client.search.memories({
  q: "data structures",
  filters: {
    OR: [
      { metadata: { topic: "algorithms" } },
      { metadata: { topic: "computer-science" } }
    ]
  },
  rerank: true,
  rewriteQuery: true,
});

interface FilterExpression {
  AND?: unknown[];
  OR?: unknown[];
}

// Example filter structures:
const filters = {
  AND: [
    { type: "pdf" },
    { metadata: { category: "research" } },
    {
      OR: [
        { metadata: { priority: 1 } },
        { metadata: { priority: 2 } }
      ]
    }
  ]
};

// Metadata-based filtering
const metadataFilter = {
  AND: [
    { metadata: { category: "documentation" } },
    { metadata: { language: "typescript" } }
  ]
};

// Type and status filtering
const typeFilter = {
  OR: [
    { type: "pdf" },
    { type: "webpage" },
    { type: "notion_doc" }
  ]
};

// Complex nested filtering
const complexFilter = {
  AND: [
    { type: "text" },
    {
      OR: [
        { metadata: { topic: "ai" } },
        { metadata: { topic: "ml" } }
      ]
    },
    { status: "done" }
  ]
};

// Process document search results
const documentResults = await client.search.documents({
  q: "API documentation",
  includeFullDocs: true,
});

documentResults.results.forEach((result) => {
  console.log(`Document: ${result.title} (Score: ${result.score})`);
  
  // Process chunks
  result.chunks.forEach((chunk) => {
    if (chunk.isRelevant) {
      console.log(`Relevant chunk: ${chunk.content.substring(0, 100)}...`);
    }
  });
  
  // Access full content if requested
  if (result.content) {
    console.log(`Full content length: ${result.content.length}`);
  }
});

// Process memory search results
const memoryResults = await client.search.memories({
  q: "JavaScript best practices",
  include: { relatedMemories: true },
});

memoryResults.results.forEach((result) => {
  console.log(`Memory: ${result.memory} (Similarity: ${result.similarity})`);
  
  // Process contextual memories
  if (result.context?.parents) {
    console.log("Parent memories:", result.context.parents.length);
  }
  
  if (result.context?.children) {
    console.log("Child memories:", result.context.children.length);
  }
});

// Efficient pagination for large result sets
const searchWithPagination = async (query: string, pageSize = 20) => {
  const results = await client.search.documents({
    q: query,
    limit: pageSize,
    // Note: Use cursors or timestamps for true pagination
    // as the API may not support traditional page offsets
  });
  
  return results;
};

try {
  const results = await client.search.documents({
    q: "search query",
    limit: 100,
  });
} catch (error) {
  if (error instanceof BadRequestError) {
    // Invalid query parameters
    console.error("Invalid search parameters:", error.message);
  } else if (error instanceof RateLimitError) {
    // Too many search requests
    console.error("Search rate limit exceeded:", error.message);
  } else if (error instanceof APIConnectionTimeoutError) {
    // Search took too long
    console.error("Search timeout:", error.message);
  }
}