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

# Core Concepts

> Allow your users to connect their accounts to Hyperspell

export const IndexedSearch = () => <Tooltip tip="Indexed search uses advanced semantic, hybrid, and graph search methods to find the most relevant results. It's very fast and accurate, but requires upfront indexing of data.">
        <span className="text-sky-600">
            <Icon icon="database" size={14} color="#0084d1" iconType="solid" /> Indexed  Search
        </span>
    </Tooltip>;

export const LiveSearch = () => <Tooltip tip="Live search uses AI to search your integrations native APIs in real-time. This is slower than indexed search and often not as accurate, but does not store any data on Hyperspell's servers and is always up to date.">
        <span className="text-emerald-600">
            <Icon icon="bolt" size={14} color="#009966" iconType="solid" /> Live Search</span>
    </Tooltip>;

export const ConnectView = ({integration, image}) => {
  return <Frame caption={`Hyperspell Connect lets your users easily connect their ${integration} account.`}><svg width="565" height="264" viewBox="0 0 565 264" fill="none" xmlns="http://www.w3.org/2000/svg">
        <rect width="565" height="264" fill="#F5F5F5" />
        <rect width="565" height="264" fill="#FBFBFC" />
        <text fill="#23272E" font-family="Finlandica" font-size="20" letter-spacing="0em"><tspan x="33" y="49">This app uses Hyperspell to securely connect to your data.</tspan></text>
        <rect x="34.5" y="103.5" width="497" height="56" rx="7.5" fill="white" stroke="#E5E7EB" />
        <rect x="34.5" y="178.5" width="497" height="56" rx="7.5" stroke="#E5E7EB" />
        <text fill="#23272E" font-family="Finlandica" font-size="16" letter-spacing="0em"><tspan x="34" y="82.1">Please connect the following accounts to continue:</tspan></text>
        <text fill="#23272E" font-family="Finlandica" font-size="16" letter-spacing="0em"><tspan x="90" y="137.1">{integration}</tspan></text>
        <text fill="#23272E" font-family="Finlandica" font-size="16" letter-spacing="0em"><tspan x="90" y="212.1">Return to app</tspan></text>
        <path d="M503 133H513" stroke="#697282" stroke-width="1.5" stroke-linecap="round" />
        <path d="M508.5 128.5L513 133L508.5 137.5" stroke="#697282" stroke-width="1.5" stroke-linecap="round" />
        <svg x="48" y="117" width="32" height="32">
            <image href={image} width="32" height="32" />
        </svg>
        <path d="M60 207.5L73 207.5C74.1046 207.5 75 206.605 75 205.5L75 203" stroke="#697282" stroke-width="1.5" stroke-linecap="round" />
        <path d="M64.5 212L60 207.5L64.5 203" stroke="#697282" stroke-width="1.5" stroke-linecap="round" />
    </svg></Frame>;
};

## Users

Hyperspell is a multi-tenant platform, and you can have multiple users in your app. You don't have to explicitly create users in Hyperspell — you simply pass the user id from your own database or authentication provider to Hyperspell. As we'll learn in the [authentication](/usage/permissions) section, Hyperspell lets you generate *user tokens* that are specific to a user and can be used to query data from Hyperspell for that user only. However, you can also use an *app token* and not associate data with a specific user.

## Memories, Integrations and Data Sources

Memories are the core concept of Hyperspell. They are a way to store data in Hyperspell, and query it using natural language. Hyperspell lets your users connect their accounts to a variety of services and data sources. Hyperspell transforms that data into memories, and keeps them up to date by automatically updating memories when the data changes.

<Note>
  #### What is a Memory?

  We use the term memory to refer to a wide range of different data — a memory can be an entire Google Doc or a PDF, but it could also be a particular part of a long conversation on Slack, a Person on your team that exists across multiple services, or a specific email.
</Note>

When your create an app, you can choose which integrations you want to enable. Every time you query hyperspell, you can mix and match different data sources.

Some data sources are available by default without requiring any additional configuration:

* <span className="text-violet-700"><img src="https://mintcdn.com/hyperspell/v3b7lBADAA2jgsr8/images/vault.svg?fit=max&auto=format&n=v3b7lBADAA2jgsr8&q=85&s=3f3ed8ee6dbc5717c8e499ca8eaacb76" alt="Vault icon" className="w-6 h-6 inline-block  mr-1 my-0" width="16" height="16" data-path="images/vault.svg" />Vault</span> searches memories and files that have been manually added to Hyperspell.
* <span className="text-sky-800"><img src="https://mintcdn.com/hyperspell/v3b7lBADAA2jgsr8/images/crawler.svg?fit=max&auto=format&n=v3b7lBADAA2jgsr8&q=85&s=034b71938d37c51607e4eac5803365f2" alt="Crawler icon" className="w-6 h-6 inline-block my-0 mr-1" width="16" height="16" data-path="images/crawler.svg" />Web Crawler</span> retrieves relevant data from websites.

## Queries

To search through memories and retrieve data from your data sources, you can use the [query API](/api-reference/memories/query-memories). Internally, there are two different ways of retrieving data, <LiveSearch /> and <IndexedSearch />.

<Card title="Indexed searches" horizontal icon="database" color="#0084d1">
  Indexed searches means that Hyperspell is continuously ingesting data from your data sources, processing it and creating a search index through different vector embeddings. When you run a query against these data sources, Hyperspell will only look in its own search index for the most relevant results.
</Card>

<Card title="Live searches" horizontal icon="bolt" color="#009966">
  Live searches means that Hyperspell will directly query the data sources for the most relevant results. Since most data sources only support keyword searches and exact matches, Hyperspell will generate a number of different keyword queries and run them in parallel, and then combine and rerank the results.
</Card>

Some integrations are only available for live searches, and some are only available for indexed searches. When available, Hyperspell will always pick indexed searches for better latency and accuracy. However, there are times when live searches are the preferred option, and you can choose which option you want to use in each query.

### Query Effort

By default, Hyperspell passes your query through verbatim. If you set `effort: 1`, Hyperspell uses an LLM to rewrite your query for better retrieval and automatically extract date filters from natural language.

For example, with `effort: 1`, a query like *"what's the engineering roadmap for Q1?"* will be rewritten into a more retrieval-friendly form and automatically scoped to the Q1 date range — without you having to specify date filters manually.

<CodeGroup>
  ```python Python theme={null}
  response = client.memories.search(
      query="what's the engineering roadmap for Q1?",
      effort=1,
  )
  ```

  ```typescript TypeScript theme={null}
  const response = await client.memories.search({
      query: "what's the engineering roadmap for Q1?",
      effort: 1,
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.hyperspell.com/memories/query" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "what'\''s the engineering roadmap for Q1?",
      "effort": 1
    }'
  ```
</CodeGroup>

| Value         | Behavior                                                              |
| ------------- | --------------------------------------------------------------------- |
| `0` (default) | Query is passed through verbatim                                      |
| `1`           | LLM rewrites the query for better retrieval and extracts date filters |

If you provide explicit date filters via `options.after` or `options.before`, those take precedence over any dates extracted by the rewriter.

<Accordion title="Learn More:" description="Indexed Searches vs Live Searches" icon="lightbulb">
  ### Indexed searches:

  **Advantages**

  * Better latency: Indexed searches are faster since they don't rely on external APIs.
  * More accurate: Indexed searches often yield better results since Hyperspell can pre-process the data and use our own vector embeddings.
  * Custom data: Any data you manually add to Hyperspell is available for indexed searches immediately, even if we don't support the integration yet.

  **Disadvantages**

  * Not available immediately: Hyperspell needs to first ingest all historical data, which for large data sources can take a while (mostly due to rate limiting)

  ### Live searches:

  **Advantages**

  * Available immediately: You can immediately search for data from the data source.
  * Real-time data: Data is always up to date, whereas indexed searches might be several minutes old
  * Cheaper: All Hyperspell plans come with unlimited live searches.
  * Privacy focused: Hyperspell doesn't store any data for live searches, so you can use it for sensitive data that your customers don't want to store in Hyperspell.

  **Disadvantages**

  * Slower: Live searches rely on external APIs and can be slower.
  * Less accurate: Live searches are not as accurate as indexed searches, as we translate semantic queries to the data source's native query endpoints.
</Accordion>

## Memories, Documents and Structured Data

When we say memories, we really mean any data that you want to index and query. This can be anything from a single text file, an email, a slack channel, a CSV file, an image, or even a PDF or presentation. When you query Hyperspell, you can retrieve data both in structured formats for use in ie. your UI, and in an LLM-ready text representation.
