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

# Search context vault

> Returns ranked retrieval results for workspace knowledge. The endpoint
does not synthesize a single final answer; callers should use returned
chunks, extracted memories, and evidence as grounded context for their
own answer-generation layer.

The response keeps document passages and extracted memories separate.
`documents` mode fills `chunks` and leaves `memories` empty. `memories`
mode fills `memories` and leaves `chunks` empty. `hybrid` mode can fill
both arrays without flattening them into one mixed list, so clients can
pass source chunks as document context and extracted facts as a separate
memory-context document.




## OpenAPI

````yaml /openapi.yaml get /api/context-vault/search
openapi: 3.1.0
info:
  title: MemContext API
  version: 1.1.0
  description: |
    REST API for persistent, evolving AI memory. Save, search, and manage
    memories with automatic deduplication, version chains, and hybrid retrieval.
servers:
  - url: https://api.memcontext.in
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Memories
    description: Save, search, list, update, and delete memories.
  - name: History
    description: Inspect how memories evolve over time.
  - name: Feedback
    description: Rate retrieval quality to improve future results.
  - name: Profiles
    description: Pre-aggregated user context from memory.
  - name: Workspaces
    description: >-
      Company/team account boundaries for billing, members, API keys, and
      vaults.
  - name: API Keys
    description: Workspace-bound API keys for server-side integrations.
  - name: Subscription
    description: Workspace-owned billing and member-memory limits.
  - name: Context Vault
    description: Document ingestion and workspace RAG retrieval.
paths:
  /api/context-vault/search:
    get:
      tags:
        - Context Vault
      summary: Search context vault
      description: |
        Returns ranked retrieval results for workspace knowledge. The endpoint
        does not synthesize a single final answer; callers should use returned
        chunks, extracted memories, and evidence as grounded context for their
        own answer-generation layer.

        The response keeps document passages and extracted memories separate.
        `documents` mode fills `chunks` and leaves `memories` empty. `memories`
        mode fills `memories` and leaves `chunks` empty. `hybrid` mode can fill
        both arrays without flattening them into one mixed list, so clients can
        pass source chunks as document context and extracted facts as a separate
        memory-context document.
      operationId: searchContextVault
      parameters:
        - in: query
          name: workspaceId
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            Optional for API-key calls because the key is bound to one
            workspace. Required for session callers selecting a workspace.
        - in: query
          name: vaultId
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            Optional vault inside the workspace. Defaults to the workspace's
            default vault.
        - in: query
          name: query
          required: true
          schema:
            type: string
            maxLength: 1000
        - in: query
          name: mode
          schema:
            type: string
            enum:
              - memories
              - documents
              - hybrid
            default: hybrid
        - in: query
          name: scope
          schema:
            type: string
            maxLength: 200
          description: Search one hard lane inside the workspace. Omit when using `scopes`.
        - in: query
          name: scopes
          schema:
            type: string
            maxLength: 1000
          description: >-
            Comma-separated scopes for multi-scope retrieval, for example
            `dev,billing`. Takes precedence over `scope`.
        - in: query
          name: project
          schema:
            type: string
            maxLength: 100
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 8
      responses:
        '200':
          description: Company brain search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchContextVaultResponse'
      security:
        - ApiKeyAuth: []
        - CookieAuth: []
components:
  schemas:
    SearchContextVaultResponse:
      type: object
      required:
        - mode
        - found
        - chunks
        - memories
      description: >-
        Ranked Context Vault retrieval results. `chunks` contains source
        document passages; `memories` contains extracted atomic facts with
        citation evidence or curated company facts. Hybrid mode returns these as
        separate arrays instead of a single merged list so callers can build
        downstream context blocks: source documents, extracted memories, and
        curated company facts. This response intentionally does not include a
        synthesized answer.
      properties:
        mode:
          type: string
          enum:
            - memories
            - documents
            - hybrid
        found:
          type: integer
        chunks:
          type: array
          description: Source document chunks/passages. Empty when mode is `memories`.
          items:
            $ref: '#/components/schemas/ContextVaultSearchChunk'
        memories:
          type: array
          description: >-
            Extracted atomic memories with source evidence. Empty when mode is
            `documents`.
          items:
            $ref: '#/components/schemas/ContextVaultSearchMemory'
    ContextVaultSearchChunk:
      type: object
      required:
        - id
        - sourceId
        - title
        - sourceType
        - sectionPath
        - scope
        - project
        - chunkIndex
        - content
        - contextualContent
        - relevance
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        sourceId:
          type: string
          format: uuid
        title:
          type: string
          nullable: true
        sourceType:
          type: string
        sectionPath:
          type: string
          nullable: true
        scope:
          type: string
          nullable: true
        project:
          type: string
          nullable: true
        chunkIndex:
          type: integer
        content:
          type: string
        contextualContent:
          type: string
        relevance:
          type: number
        createdAt:
          type: string
          format: date-time
    ContextVaultSearchMemory:
      type: object
      required:
        - id
        - content
        - category
        - scope
        - project
        - memoryType
        - createdAt
        - evidence
      properties:
        id:
          type: string
          format: uuid
        content:
          type: string
        category:
          type: string
          nullable: true
        scope:
          type: string
          nullable: true
        project:
          type: string
          nullable: true
        memoryType:
          type: string
          enum:
            - document
            - company
          description: >-
            `company` results are curated facts and may have an empty evidence
            array.
        createdAt:
          type: string
          format: date-time
        evidence:
          type: array
          items:
            type: object
            required:
              - sourceId
              - chunkId
              - quote
              - confidence
              - title
              - sectionPath
              - chunkIndex
            properties:
              sourceId:
                type: string
                format: uuid
              chunkId:
                type: string
                format: uuid
              quote:
                type: string
                nullable: true
              confidence:
                type: number
                nullable: true
              title:
                type: string
                nullable: true
              sectionPath:
                type: string
                nullable: true
              chunkIndex:
                type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        API key created from the MemContext dashboard. Keys are prefixed with
        `mc_`, bound to one workspace, and API-key requests cannot override that
        workspace.
    CookieAuth:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: Dashboard session cookie used for workspace/company endpoints.

````