> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crosmos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Memories

> Search for relevant memories within a memory space using hybrid retrieval (semantic + keyword + graph + temporal), RRF fusion, cross-encoder reranking, and recency/temporal boosting.



## OpenAPI

````yaml https://api.crosmos.dev/openapi.json post /api/v1/search
openapi: 3.1.0
info:
  title: Crosmos API
  version: 0.1.0
servers:
  - url: /
security: []
paths:
  /api/v1/search:
    post:
      tags:
        - search
      summary: Search Memories
      description: >-
        Search for relevant memories within a memory space using hybrid
        retrieval (semantic + keyword + graph + temporal), RRF fusion,
        cross-encoder reranking, and recency/temporal boosting.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Ranked memory candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchErrorBody'
        '404':
          description: Space not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchErrorBody'
        '429':
          description: Rate limited, quota exceeded, or too many concurrent searches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchErrorBody'
        '500':
          description: Unexpected failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchErrorBody'
        '504':
          description: Search timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchErrorBody'
      security:
        - bearerAuth: []
components:
  schemas:
    SearchRequest:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 3000
          description: The search query text
        space_id:
          type: string
          format: uuid
          description: The memory space to search within
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: Max number of results to return
        recency_bias:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          default: null
          description: >-
            Override recency weighting. 0.0 disables recency, higher values
            favor recent memories.
        rerank:
          type: boolean
          default: true
          description: Apply cross-encoder reranking. Disable for lower latency.
        graph:
          type: boolean
          default: true
          description: Include graph traversal signal. Disable for semantic + keyword only.
        diversify:
          type: boolean
          default: false
          description: >-
            Apply MMR diversity post-rerank. Enable for broad/summarization
            intents.
        include_source:
          type: boolean
          default: true
          description: Include original source text in results.
        recall_id:
          type: string
          format: uuid
          description: >-
            Optional stable id for one logical recall. Retries of the same
            logical search should reuse the same value: the server then reuses a
            single concurrency slot instead of counting each retry as a new
            concurrent search. Omit it and behavior is unchanged. Generate a
            fresh id per distinct search — reusing one id across genuinely
            different searches makes them share a slot.
      required:
        - query
        - space_id
    SearchResponse:
      type: object
      properties:
        query:
          type: string
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/MemoryCandidate'
      required:
        - query
        - candidates
    SearchErrorBody:
      type: object
      properties:
        detail:
          nullable: true
    MemoryCandidate:
      type: object
      properties:
        memory_id:
          type: string
          format: uuid
        content:
          type: string
        memory_type:
          type: string
        score:
          type: number
        source:
          type: string
          nullable: true
        source_id:
          type: string
          nullable: true
          format: uuid
        created_at:
          type: string
        event_time:
          type: string
          nullable: true
        owner_name:
          type: string
          nullable: true
      required:
        - memory_id
        - content
        - memory_type
        - score
        - source_id
        - created_at
        - event_time
        - owner_name
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT access token or API key (csk_...)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.