> ## Documentation Index > Fetch the complete documentation index at: https://supermemory-personal-brain-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Search memory entries > Search memory entries - Low latency for conversational ## OpenAPI ````yaml https://api.supermemory.ai/v4/openapi post /v4/search openapi: 3.1.0 info: title: supermemory API description: >- The Memory API for the AI era. OpenAPI operations include x-codeSamples for the official TypeScript and Python SDKs (Mintlify-compatible). version: 3.0.0 servers: - description: Production Server url: https://api.supermemory.ai security: - bearerAuth: [] tags: - name: Ingest description: Ingest documents, files, URLs, conversations, and other content - name: Recall (Search) description: >- Semantic recall across your content — supports memories, hybrid, and documents modes - name: Profiles description: >- Entity profiles for users, participants, or any entity — includes profile search - name: Content Management description: List, get, update, and delete content and memories - name: Container Tags description: List and manage container tags (spaces) — settings, merge, and delete - name: Connections description: External service integrations - name: Settings description: Organization settings - name: Documents description: List, get, and search documents paths: /v4/search: post: tags: - Recall (Search) summary: Search memory entries description: Search memory entries - Low latency for conversational operationId: postV4Search requestBody: required: true content: application/json: schema: type: object properties: containerTag: description: >- Optional tag this search should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to filter memories. example: user_alex type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ containerTags: description: >- Optional tags this search should be containerized by. Search is scoped to memories under these tags. example: - user_alex type: array items: type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ threshold: description: >- Threshold / sensitivity for memories selection. 0 is least sensitive (returns most memories, more results), 1 is most sensitive (returns lesser memories, accurate results) example: 0.5 maximum: 1 minimum: 0 default: 0.6 type: number filters: $ref: '#/components/schemas/QueryFilter' description: >- Optional filters to apply to the search. Can be a JSON string or Query object. include: default: documents: false summaries: false relatedMemories: false forgottenMemories: false chunks: false type: object properties: documents: default: false type: boolean summaries: default: false type: boolean relatedMemories: default: false type: boolean forgottenMemories: default: false description: >- If true, include forgotten memories in search results. Forgotten memories are memories that have been explicitly forgotten or have passed their expiration date. example: false type: boolean chunks: default: false description: >- DEPRECATED: Use searchMode='hybrid' instead. If true, automatically switches to hybrid mode. This field is kept for backward compatibility only. example: false deprecated: true type: boolean limit: default: 10 description: Maximum number of results to return example: 10 maximum: 100 minimum: 1 type: integer exclusiveMinimum: 0 q: type: string minLength: 1 description: Search query string example: what are the API rate limits rerank: default: false description: >- If true, rerank the results based on the query. This is helpful if you want to ensure the most relevant results are returned. example: false type: boolean aggregate: default: false description: >- If true, aggregates information from multiple memories to create new synthesized memories. The result will be a mix of aggregated and non-aggregated memories, reranked by relevance to the query. Works in conjunction with reranking. example: false type: boolean rewriteQuery: default: false description: >- If true, rewrites the query to make it easier to find documents. This increases the latency by about 400ms example: false type: boolean searchMode: default: memories description: >- Search mode. 'memories' searches only memory entries (default). 'hybrid' searches both memories and document chunks. 'documents' searches only document chunks. example: memories type: string enum: - memories - hybrid - documents filepath: description: >- Filter search results by filepath. Exact match for full paths, prefix match if ending with / x-hidden: true type: string required: - q responses: '200': content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string description: Memory entry ID or chunk ID example: mem_abc123 memory: description: The memory content (only present for memory results) example: >- The user prefers detailed API responses over minimal ones. type: string chunk: description: >- The chunk content (only present for chunk results from hybrid search) example: This is a chunk of content from a document... type: string metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: Memory metadata example: source: conversation confidence: 0.9 updatedAt: type: string description: Memory last update date format: datetime similarity: type: number description: Similarity score between the query and memory entry example: 0.89 maximum: 1 minimum: 0 filepath: description: >- Filepath of the source document this memory or chunk came from x-hidden: true anyOf: - type: string - type: 'null' version: description: Version number of this memory entry example: 3 anyOf: - type: number - type: 'null' rootMemoryId: description: >- ID of the root (first version) memory entry this one descends from. Null for memories that have never been superseded. Only present on memory results, not on standalone chunk results. example: mem_abc123 anyOf: - type: string - type: 'null' context: description: >- Object containing version history (parents/children via updates) and related memories (extends/derives) type: object properties: parents: type: array items: type: object properties: relation: type: string enum: - updates - extends - derives description: >- Relation type between this memory and its parent/child example: updates version: description: >- Relative version distance from the primary memory (-1 for direct parent, -2 for grand-parent, etc.) example: -1 anyOf: - type: number - type: 'null' memory: type: string description: The contextual memory content example: >- Earlier version: API rate limit is 50 req/min on the free tier. metadata: description: Contextual memory metadata anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' updatedAt: type: string description: Contextual memory last update date format: datetime required: - relation - memory - updatedAt children: type: array items: type: object properties: relation: type: string enum: - updates - extends - derives description: >- Relation type between this memory and its parent/child example: extends version: description: >- Relative version distance from the primary memory (+1 for direct child, +2 for grand-child, etc.) example: 1 anyOf: - type: number - type: 'null' memory: type: string description: The contextual memory content example: >- Later version: API rate limit increased to 100 req/min on the free tier. metadata: description: Contextual memory metadata anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' updatedAt: type: string description: Contextual memory last update date format: datetime required: - relation - memory - updatedAt related: type: array items: type: object properties: relation: type: string enum: - extends - derives description: Relation type memory: type: string description: The related memory content metadata: description: Related memory metadata anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' updatedAt: type: string description: Related memory last update date required: - relation - memory - updatedAt documents: description: Associated documents for this memory entry type: array items: type: object properties: id: type: string description: Document ID example: doc_xyz789 title: description: >- Document title (only included when documents=true) example: API Rate Limiting Policy type: string type: description: >- Document type (only included when documents=true) example: web type: string metadata: description: >- Document metadata (only included when documents=true) example: source: upload language: en anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' summary: description: >- Document summary (only included when summaries=true) example: >- API rate limit policy: 100 req/min free, 1000 req/min pro. anyOf: - type: string - type: 'null' createdAt: type: string description: Document creation date format: datetime updatedAt: type: string description: Document last update date format: datetime required: - id - createdAt - updatedAt chunks: description: >- Relevant chunks from associated documents (only included when chunks=true) type: array items: type: object properties: content: type: string description: Content of the chunk example: >- This is a chunk of content from the document... position: type: number description: Position of chunk in the document (0-indexed) example: 0 documentId: type: string description: ID of the document this chunk belongs to example: doc_xyz789 required: - content - position - documentId isAggregated: description: >- Indicates if this memory was created by aggregating multiple source memories example: false type: boolean required: - id - metadata - updatedAt - similarity description: >- Array of matching memory entries and chunks with similarity scores. Contains memory results when searchMode='memories', both memory and chunk results when searchMode='hybrid', or only chunk results when searchMode='documents'. Memory results have 'memory' field, chunk results have 'chunk' field. BACKWARD COMPATIBILITY: When using deprecated include.chunks=true, only memory results are returned with chunks embedded in them (old format). timing: type: number description: Search execution time in milliseconds example: 245 total: type: number description: Total number of results returned example: 5 required: - results - timing - total description: Memory search results '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid request parameters '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '402': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Search quota or credits exhausted '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error x-codeSamples: - lang: typescript label: TypeScript SDK source: |- import Supermemory from "supermemory"; const client = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY, }); const results = await client.search.memories({ q: "gift ideas for a VP promotion after a Tokyo offsite", containerTag: "user_123", searchMode: "hybrid", // memories | documents | hybrid limit: 5, include: { relatedMemories: true }, }); for (const hit of results.results) { console.log(hit.memory ?? hit.chunk, hit.similarity); } - lang: python label: Python SDK source: |- from supermemory import Supermemory client = Supermemory() # uses SUPERMEMORY_API_KEY results = client.search.memories( q="gift ideas for a VP promotion after a Tokyo offsite", container_tag="user_123", search_mode="hybrid", # memories | documents | hybrid limit=5, include={"related_memories": True}, ) for hit in results.results: print(getattr(hit, "memory", None) or getattr(hit, "chunk", None), hit.similarity) - lang: bash label: cURL source: |- curl -X POST "https://api.supermemory.ai/v4/search" \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "q": "gift ideas for a VP promotion after a Tokyo offsite", "containerTag": "user_123", "searchMode": "hybrid", "limit": 5, "include": { "relatedMemories": true } }' components: schemas: QueryFilter: description: >- Root query object that must contain either an AND or OR array of filter expressions anyOf: - type: object properties: OR: type: array items: $ref: '#/components/schemas/LogicalExpression' description: Array of OR filter expressions required: - OR - type: object properties: AND: type: array items: $ref: '#/components/schemas/LogicalExpression' description: Array of AND filter expressions required: - AND ErrorResponse: type: object properties: error: type: string description: Error message example: Invalid request parameters details: type: string description: Additional error details example: Query must be at least 1 character long required: - error LogicalExpression: description: >- A single filter condition or a nested AND/OR expression. The API validates up to 5 levels of nesting. anyOf: - $ref: '#/components/schemas/FilterCondition' - type: object properties: OR: type: array items: $ref: '#/components/schemas/LogicalExpression' description: 'OR: Array of conditions or nested expressions' required: - OR - type: object properties: AND: type: array items: $ref: '#/components/schemas/LogicalExpression' description: 'AND: Array of conditions or nested expressions' required: - AND FilterCondition: type: object properties: filterType: default: metadata type: string enum: - metadata - numeric - array_contains - string_contains key: type: string negate: anyOf: - type: boolean - type: string enum: - 'true' - 'false' ignoreCase: anyOf: - type: boolean - type: string enum: - 'true' - 'false' numericOperator: default: '=' type: string enum: - '>' - < - '>=' - <= - '=' value: type: string required: - key - value description: >- A single filter condition based on metadata, numeric values, array contents, or string matching securitySchemes: bearerAuth: scheme: bearer type: http ````