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

# Search memories

> Unified memory search endpoint supporting multiple memory types and retrieval methods.

**Retrieval Methods**

* **keyword**: BM25 keyword retrieval (Elasticsearch only)
* **vector**: Vector semantic retrieval (Milvus only)
* **hybrid** (default): Hybrid retrieval with rerank (ES + Milvus + Rerank)
* **agentic**: LLM-guided multi-round intelligent retrieval

**Memory Types**

* **episodic\_memory**: Episodic memory (ES + Milvus)
* **profile**: User profile (Milvus only)
* **raw\_message**: Raw unprocessed messages (ES only)
* **agent\_memory**: Agent memory - cases and skills (ES + Milvus)

**Filters DSL**
Same syntax as the GET endpoint. Must contain at least one of `user_id` or `group_id`.


## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/memories/search
openapi: 3.1.0
info:
  title: EverOS API
  description: >-
    Enterprise-grade intelligent memory system for AI agents. Extracts,
    structures, and retrieves information from conversations.
  version: 1.0.0
  contact:
    name: EverOS Team
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.evermind.ai
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Memories
    description: Memory ingestion, retrieval, search, and deletion
  - name: Groups
    description: Group resource CRUD operations
  - name: Senders
    description: Sender resource CRUD operations
  - name: Settings
    description: Global settings management
  - name: Tasks
    description: Async task status tracking
  - name: Storage
    description: Multimodal content storage (pre-signed upload)
paths:
  /api/v1/memories/search:
    post:
      tags:
        - Memories
      summary: Search memories
      description: >-
        Unified memory search endpoint supporting multiple memory types and
        retrieval methods.
      operationId: searchMemories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchMemoriesRequest'
      responses:
        '200':
          description: Search results returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchMemoriesResponse'
        '422':
          description: >-
            Validation error (invalid parameter values, business rule
            violations)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_query:
                  summary: Missing required query
                  value:
                    code: InvalidParameter
                    message: 'query: Field required'
                    request_id: unknown
                    timestamp: '2026-03-24T00:00:00+00:00'
                    path: /api/v1/memories/search
                invalid_method:
                  summary: Invalid retrieval method
                  value:
                    code: InvalidParameter
                    message: >-
                      Unknown method: foo. Built-in: agentic, hybrid, keyword,
                      vector
                    request_id: unknown
                    timestamp: '2026-03-24T00:00:00+00:00'
                    path: /api/v1/memories/search
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: Python
          source: |-
            from everos_cloud import EverOS

            client = EverOS()
            memories = client.v1.memories

            response = memories.search(
                filters={"user_id": "<string>"},
                query="<string>",
                method="<string>",
                top_k=5
            )
            print(response)
        - lang: cURL
          source: |-
            curl --request POST \
              --url 'https://api.evermind.ai/api/v1/memories/search' \
              --header 'Authorization: Bearer <api_key>' \
              --header 'Content-Type: application/json' \
              --data '{}'
components:
  schemas:
    SearchMemoriesRequest:
      type: object
      required:
        - query
        - filters
      properties:
        query:
          type: string
          description: Search query text
          examples:
            - What did Alice say about the project?
        method:
          type: string
          description: Retrieval method
          enum:
            - keyword
            - vector
            - hybrid
            - agentic
          default: hybrid
        memory_types:
          type: array
          description: Memory types to search
          items:
            type: string
            enum:
              - episodic_memory
              - profile
              - raw_message
              - agent_memory
          default:
            - episodic_memory
            - profile
        top_k:
          type: integer
          description: Max results. -1 = return all meeting threshold (up to 100)
          default: -1
          minimum: -1
          maximum: 100
        radius:
          description: COSINE similarity threshold (0.0-1.0) for vector methods
          minimum: 0
          maximum: 1
          type:
            - number
            - 'null'
        include_original_data:
          type: boolean
          description: Whether to return original data
          default: false
        filters:
          type: object
          description: >-
            Filter conditions. Supported fields: user_id, group_id, session_id,
            timestamp. user_id and group_id are placed at the top level of the
            filters object. session_id and timestamp support operators (eq, in,
            gt, gte, lt, lte) and can be used inside AND/OR combinators.
          additionalProperties: true
    SearchMemoriesResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SearchMemoriesResponseData'
    ErrorResponse:
      type: object
      required:
        - code
        - message
        - timestamp
        - path
      properties:
        code:
          type: string
          description: Error code
          examples:
            - InvalidParameter
            - NotFound
            - InternalError
        message:
          type: string
          description: Error message
        request_id:
          type: string
          description: Request ID
          default: unknown
        timestamp:
          type: string
          description: ISO 8601 timestamp
        path:
          type: string
          description: Request path
    SearchMemoriesResponseData:
      type: object
      required:
        - query
      properties:
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/SearchEpisodeItem'
          default: []
          description: Episodic memory search results
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/SearchProfileItem'
          default: []
          description: Profile search results
        raw_messages:
          type: array
          items:
            $ref: '#/components/schemas/RawMessageDTO'
          default: []
          description: Raw unprocessed messages (pending)
        agent_memory:
          oneOf:
            - $ref: '#/components/schemas/AgentMemorySearchResult'
            - type: 'null'
        query:
          $ref: '#/components/schemas/SearchQueryInfo'
        original_data:
          additionalProperties: true
          description: Original data (if include_original_data=true)
          type:
            - object
            - 'null'
    SearchEpisodeItem:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: MongoDB ObjectId as string
        user_id:
          description: Owner user ID
          type:
            - string
            - 'null'
        group_id:
          description: Group ID
          type:
            - string
            - 'null'
        session_id:
          description: Session identifier
          type:
            - string
            - 'null'
        timestamp:
          format: date-time
          description: Event occurrence time
          type:
            - string
            - 'null'
        participants:
          items:
            type: string
          description: Event participant names
          type:
            - array
            - 'null'
        summary:
          description: Memory summary
          type:
            - string
            - 'null'
        subject:
          description: Memory subject
          type:
            - string
            - 'null'
        episode:
          description: Full episodic memory text
          type:
            - string
            - 'null'
        type:
          description: Episode type
          type:
            - string
            - 'null'
        parent_type:
          description: Parent memory type
          type:
            - string
            - 'null'
        parent_id:
          description: Parent memory ID
          type:
            - string
            - 'null'
        score:
          description: Relevance score
          type:
            - number
            - 'null'
        atomic_facts:
          type: array
          items:
            $ref: '#/components/schemas/SearchAtomicFactItem'
          default: []
          description: Atomic facts expanded from this episode
    SearchProfileItem:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: MongoDB ObjectId as string
        user_id:
          description: User ID
          type:
            - string
            - 'null'
        group_id:
          description: Group ID
          type:
            - string
            - 'null'
        profile_data:
          description: Profile data (explicit_info, implicit_traits)
          additionalProperties: true
          type:
            - object
            - 'null'
        scenario:
          description: 'Scenario type: solo or team'
          type:
            - string
            - 'null'
        memcell_count:
          description: Number of MemCells
          type:
            - integer
            - 'null'
        score:
          description: Relevance score
          type:
            - number
            - 'null'
    RawMessageDTO:
      type: object
      required:
        - id
        - request_id
      properties:
        id:
          type: string
          description: MongoDB ObjectId as string
        request_id:
          type: string
          description: Request ID
        message_id:
          description: Message ID
          type:
            - string
            - 'null'
        group_id:
          description: Group ID
          type:
            - string
            - 'null'
        session_id:
          description: Session identifier
          type:
            - string
            - 'null'
        sender_id:
          description: Sender ID
          type:
            - string
            - 'null'
        sender_name:
          description: Sender name
          type:
            - string
            - 'null'
        content_items:
          items:
            type: object
            additionalProperties: true
          type:
            - array
            - 'null'
        timestamp:
          description: ISO 8601 format
          type:
            - string
            - 'null'
        created_at:
          description: ISO 8601 format
          type:
            - string
            - 'null'
        updated_at:
          description: ISO 8601 format
          type:
            - string
            - 'null'
    AgentMemorySearchResult:
      type: object
      properties:
        cases:
          type: array
          items:
            $ref: '#/components/schemas/SearchAgentCaseItem'
          default: []
          description: Agent case search results
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SearchAgentSkillItem'
          default: []
          description: Agent skill search results
    SearchQueryInfo:
      type: object
      required:
        - text
        - method
      properties:
        text:
          type: string
          description: Search query text
        method:
          type: string
          description: Retrieval method used
        filters_applied:
          description: Filters applied
          additionalProperties: true
          type:
            - object
            - 'null'
    SearchAtomicFactItem:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: MongoDB ObjectId as string
        user_id:
          description: User ID
          type:
            - string
            - 'null'
        group_id:
          description: Group ID
          type:
            - string
            - 'null'
        session_id:
          description: Session identifier
          type:
            - string
            - 'null'
        atomic_fact:
          description: Atomic fact content
          type:
            - string
            - 'null'
        timestamp:
          format: date-time
          description: Event occurrence time
          type:
            - string
            - 'null'
        participants:
          items:
            type: string
          description: Related participant IDs
          type:
            - array
            - 'null'
        parent_type:
          description: Parent memory type
          type:
            - string
            - 'null'
        parent_id:
          description: Parent memory ID
          type:
            - string
            - 'null'
        score:
          description: Relevance score
          type:
            - number
            - 'null'
        parent_episode_id:
          description: Source episode ID (MRAG expansion)
          type:
            - string
            - 'null'
        original_text:
          description: Original text from parent episode
          type:
            - string
            - 'null'
    SearchAgentCaseItem:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: MongoDB ObjectId as string
        user_id:
          description: User ID
          type:
            - string
            - 'null'
        group_id:
          description: Group ID
          type:
            - string
            - 'null'
        session_id:
          description: Session identifier
          type:
            - string
            - 'null'
        task_intent:
          description: Rewritten task intent as retrieval key
          type:
            - string
            - 'null'
        approach:
          description: Step-by-step approach with decisions and lessons
          type:
            - string
            - 'null'
        quality_score:
          description: Task completion quality score (0.0-1.0)
          type:
            - number
            - 'null'
        timestamp:
          format: date-time
          description: Task occurrence time
          type:
            - string
            - 'null'
        parent_type:
          description: Parent memory type
          type:
            - string
            - 'null'
        parent_id:
          description: Parent memory ID
          type:
            - string
            - 'null'
        score:
          description: Relevance score
          type:
            - number
            - 'null'
    SearchAgentSkillItem:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: MongoDB ObjectId as string
        user_id:
          description: User ID
          type:
            - string
            - 'null'
        group_id:
          description: Group ID
          type:
            - string
            - 'null'
        cluster_id:
          description: MemScene cluster ID
          type:
            - string
            - 'null'
        name:
          description: Skill name
          type:
            - string
            - 'null'
        description:
          description: What this skill does and when to use it
          type:
            - string
            - 'null'
        content:
          description: Full skill content
          type:
            - string
            - 'null'
        confidence:
          description: Confidence score (0.0-1.0)
          type:
            - number
            - 'null'
        maturity_score:
          description: Maturity score (0.0-1.0)
          type:
            - number
            - 'null'
        source_case_ids:
          type: array
          items:
            type: string
          description: Source AgentCase IDs
          default: []
        score:
          description: Relevance score
          type:
            - number
            - 'null'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      x-default: Bearer <api_key>
      description: >-
        Bearer authentication header of the form Bearer 'api_key', obtain your
        API key from [everos.evermind.ai](https://everos.evermind.ai).

````