---
title: "Query memories"
method: POST
path: "/memories/query"
tags: ["Memories"]
---

# Query memories

`POST /memories/query`

Retrieves documents matching the query.

## Request body

- QueryRequest
  - `query` string, required — Query to run.
  - `answer` boolean — If true, the query will be answered along with matching source documents.
  - `effort` 'minimal' | 'low' | 'medium' | 'high' — How much compute the retrieval pipeline should spend on this query. Mirrors the convention popularized by OpenAI's reasoning_effort and similar dials on Anthropic / Gemini APIs. ``minimal`` is the cheapest and fastest path; ``high`` does the most. Tiers map to behavior via ``EFFORT_CONFIG``.
  - `sources` DocumentProviders[] — Only query documents from these sources.
  - `options` QueryOptions
    - `after` string, date-time, nullable — Only query documents created on or after this date.
    - `before` string, date-time, nullable — Only query documents created before this date.
    - `filter` object, nullable — Metadata filters using MongoDB-style operators. Example: {'status': 'published', 'priority': {'$gt': 3}}
    - `resource_ids` string[], nullable — Only return results from these specific resource IDs. Useful for scoping searches to specific documents (e.g., a specific email thread or uploaded file).
    - `memory_types` MemoryType[] — Filter by memory type. Defaults to generic memories only. Pass multiple types to include procedures, etc.
    - `recency_half_life_days` number, nullable — When set, multiplies each result's score by an exponential-decay factor based on the document's most recent activity timestamp (source-reported last_modified, falling back to document_date). A document one half-life old gets its score halved. Resources with no recency timestamp are passed through unchanged. Leave unset to disable.
    - `vault` VaultSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
    - `google_calendar` GoogleCalendarSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `calendar_id` string, nullable — The ID of the calendar to search. If not provided, it will use the ID of the default calendar. You can get the list of calendars with the `/integrations/google_calendar/list` endpoint.
    - `notion` NotionSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `notion_page_ids` string[] — List of Notion page IDs to search. If not provided, all pages in the workspace will be searched.
    - `web_crawler` WebCrawlerSearchOptions — Options for the WebCrawler integration.
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `url` string, nullable — The URL to crawl
      - `max_depth` integer — Maximum depth to crawl from the starting URL
    - `reddit` RedditSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `subreddit` string, nullable — The subreddit to search. If not provided, the query will be searched for in all subreddits.
      - `sort` 'relevance' | 'new' | 'hot' | 'top' | 'comments' — The sort order of the posts. Defaults to 'relevance'.
      - `period` 'hour' | 'day' | 'week' | 'month' | 'year' | 'all' — The time period to search. Defaults to 'month'.
    - `slack` SlackSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `channels` string[] — List of Slack channels to include (by id, name, or #name).
      - `include_private` boolean — Include private channels when constructing Slack 'types'. Defaults to False to preserve existing cassette query params.
      - `include_dms` boolean — Include direct messages (im) when listing conversations.
      - `include_group_dms` boolean — Include group DMs (mpim) when listing conversations.
      - `exclude_archived` boolean, nullable — If set, pass 'exclude_archived' to Slack. If None, omit the param.
    - `box` BoxSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
    - `google_drive` GoogleDriveSearchOptions
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
    - `google_mail` GmailSearchOptions — Search options specific to Gmail integration.
      - `weight` number — Weight of results from this source. A weight greater than 1.0 means more results from this source will be returned, a weight less than 1.0 means fewer results will be returned. This will only affect results if multiple sources are queried at the same time.
      - `label_ids` string[] — List of label IDs to filter messages (e.g., ['INBOX', 'SENT', 'DRAFT']). Multiple labels are combined with OR logic - messages matching ANY specified label will be returned. If empty, no label filtering is applied (searches all accessible messages).
    - `max_results` integer — Maximum number of results to return.
    - `answer_model` 'llama-3.1' | 'gemma2' | 'qwen-qwq' | 'mistral-saba' | 'llama-4-scout' | 'deepseek-r1' | 'gpt-oss-20b' | 'gpt-oss-120b' — Available models for answer generation via AWS Bedrock. Only short, user-friendly names are accepted in API requests. Bedrock model IDs are used internally when calling the Converse API.
  - `max_results` integer — Maximum number of results to return.

## Response `200`

Successful Response

- QueryResult
  - `query_id` string, nullable — The ID of the query. This can be used to retrieve the query later, or add feedback to it. If the query failed, this will be None.
  - `errors` object[], nullable — Errors that occurred during the query. These are meant to help the developer debug the query, and are not meant to be shown to the user.
  - `documents` Resource[], required
    - `source` 'reddit' | 'notion' | 'slack' | 'google_calendar' | 'google_mail' | 'box' | 'dropbox' | 'github' | 'google_drive' | 'vault' | 'web_crawler' | 'trace' | 'microsoft_teams' | 'gmail_actions' | 'granola' | 'fathom' | 'linear' | 'hubspot' | 'salesforce' | 'coda' | 'lightfield', required
    - `resource_id` string, required
    - `title` string, nullable
    - `metadata` Metadata
      - `created_at` string, date-time, nullable
      - `indexed_at` string, date-time, nullable
      - `last_modified` string, date-time, nullable
      - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped'
      - `events` Notification[]
        - `message` string, required
        - `time` string, date-time
        - `type` 'error' | 'warning' | 'info' | 'success', required
      - `url` string, nullable
    - `score` number, nullable — The relevance of the resource to the query
    - `folder_id` string, nullable — Provider folder ID this resource belongs to
    - `parent_folder_id` string, nullable — Parent folder ID for policy inheritance
    - `folder_ancestors` string[] — Ordered list of provider folder IDs from immediate parent up to (but not including) provider root. Used by resolve_sync_mode to walk the actual folder tree without depending on intermediate policy records. Empty = resource lives at provider root.
  - `answer` string, nullable — The answer to the query, if the request was set to answer.
  - `score` number, nullable — The average score of the query feedback, if any.

## Other responses

- `422` — Validation Error

## Changes

- **2026-05-20** `912f94dd47ba` — 1 warning, 1 info
  - added the new `lightfield` enum value to the `documents/items/source` response property for the response status `200`
  - added the new `lightfield` enum value to the request property `sources/items/`
- **2026-05-20** `d7c846c2cd79` — 1 warning, 1 info
  - added the new `coda` enum value to the `documents/items/source` response property for the response status `200`
  - added the new `coda` enum value to the request property `sources/items/`
- **2026-05-18** `6eb290df2d3b` — 2 warning, 2 info
  - added the new `hubspot` enum value to the `documents/items/source` response property for the response status `200`
  - added the new `salesforce` enum value to the `documents/items/source` response property for the response status `200`
  - added the new `hubspot` enum value to the request property `sources/items/`
  - added the new `salesforce` enum value to the request property `sources/items/`
- **2026-05-08** `affa1afb6065` — 2 breaking, 5 info
  - request property `effort` was restricted to a list of enum values
  - the `effort` request property type/format changed from `integer`/`` to `string`/``
  - the `effort` request property default value changed from `0` to `minimal`
  - added the new `high` enum value to the request property `effort`
  - …3 more
- **2026-05-07** `dae795df37e2` — 1 info
  - added the optional property `documents/items/folder_ancestors` to the response with the `200` status

[Full history](https://skmtc.dev/hyperspell/apis/hyperspell-api/changes/memories/query/post.md)

---

[API](https://skmtc.dev/hyperspell/apis/hyperspell-api.md) · [All operations](https://skmtc.dev/hyperspell/apis/hyperspell-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperspell/hyperspell-api/revisions/1ee2b0829dfd/schema)