While you can use the Hyperspell API directly to query memories, the most common way to query memories is using the Hyperspell SDKs, which are available for Python and TypeScript.
If you need an SDK for another language, please let us know and we’ll create it for you.

​
Installation

pip install hyperspell
# Or using Poetry
poetry add hyperspell
# Or using uv
uv add hyperspell
To initialize the client, you need to generate an app token in your dashboard. 
from hyperspell import Hyperspell

client = Hyperspell(api_key="YOUR_APP_TOKEN")
You can also set the HYPERSPELL_API_KEY environment variable and omit the api_key parameter when initializing the client. An app token allows you to insert and query data for any user of your app. Please refer to the Generating Tokens section for more information on how to generate user tokens that are specific to a single user instead.

​
Usage

Before you can query data, you need to add a memory. In this example, we’ll add a a simple poem. We’ll also tag this poem by adding it to the collection poems (if it doesn’t exist, it will be created automatically) — that lets us query for all poems later. 
memory_status = client.memories.add(
    text="’Twas brillig, and the slithy toves did gyre and gimble in the wabe...",
    collection="poems"
)
print(memory_status.resource_id)
The resource_id returned will be the ID of the memory. You can use this ID to retrieve the original document later. Some types of documents may take several seconds to process, so you may need to wait for the document to be processed before you can query it. Once you have added a memory, you can query it using the search method. 
response = client.memories.search(
    query="what is a borogove?",
    sources=["vault"],
    options={
        "vault": {
            "collection": "poems"
        }
    }
)
print(response.documents)
As you can see, the search method takes a query string, and a sources parameter that lists the sources you want to query. In this example, we used vault as a source, which contains all documents added manually with the /memories/add endpoint. Each data source comes with different options when querying data. In this example, we used the vault source, so in the options field we will find a key with the name of the source (vault) which contains all the options. In this case, we only have one option, which is the collection parameter. Note that if we didn’t set this parameter, the entire vault will be searched.

​
Debugging queries

They /memories/query endpoint is designed to always return a result to the best of Hyperspell’s ability, even if some of the data sources might produce errors. Each response from this endpoint contains an errors field, which contains a list of errors that occurred while querying the data sources. If no errors occurred, this field will be empty. 
{
  "errors": [
    {
      "error": "ConnectionNotFound",
      "message": "User hasn't connected their google_calendar account yet"
    }
  ],
  "documents": []
}
If you’re not seeing the result you expected, it’s a good idea to check the errors field for any errors that occurred — during development, we recommend logging the errors as warnings.

​
Asking questions about your data

By default, the search will return the most relevant documents (or parts of documents) that match the query. Documents contain both structured data that you can use ie. in your UI to show results, and an LLM-summary that you can use for retrieval-augmented generation. Of course, you can also use Hyperspell to answer questions about your document directly. To do so, simply include the answer parameter in your query: 
response = client.memories.search(
    query="which attacks does the jabberwock have?",
    sources=["vault"],
    answer=True,
    options={
        "vault": {
            "collection": "poems"
        }
    }
)
print(response.answer)
By default, Hyperspell uses a fine-tuned LLama 3.1 Instruct, 8B instruct model to generate answers, which is by far one of the fastest models available for question-answering based on given documents.Your and your users’ data is never used to train foundational models.If you need a more powerful model, please let us know and we’ll add it to the platform. Of course, you can always bring your own model and only use Hyperspell for the retrieval part.

​
Querying multiple sources

You can query multiple sources at once by passing a list of sources to the sources parameter. 
response = client.memories.search(
    query="what did joe think about my poetry collection?",
    sources=["slack", "gmail"]
)
print(response.documents)
In this example, we’re querying both the slack and gmail sources. Both sources are queried at the same time, and the results are merged together. You can use Hyperspell Connect to let your users securely connect their accounts to Hyperspell, and then query their data.

​
Choosing which answer model to use

By default, Hyperspell uses a fine-tuned Llama 3.1 8B model to answer queries. This model is fast and efficient, but it may not be the best fit for all use cases. If you need a more powerful model, you can choose a different model by passing the answer_model parameter to the search method. 
response = client.memories.search(
    query="which attacks does the jabberwock have?",
    sources=["vault"],
    answer=True,
    answer_model="deepseek-r1",
)
print(response.answer)
The following models are available:
ValueNameUse Case
llama-3.1Meta Llama 3.1 8BGeneral-purpose, fast, high-accuracy model that balances performance and efficiency for most English-language RAG queries.
gemma2Google Gemma 2Lightweight, fast model ideal for fast inference without sacrificing too much quality.
qwen-qwqAlibaba Qwen QWQMultilingual or code-heavy queries where Chinese-language support or reasoning over technical content is important.
mistral-sabaMistral SabaSmall, open-weight model with strong performance in structured reasoning or concise summarization tasks.
llama-4-scoutMeta Llama 4 ScoutState-of-the-art reasoning and nuanced understanding for complex or ambiguous queries.
deepseek-r1DeepSeek R1Use this when your query involves math, code, or scientific reasoning.

​
Fine-tuning the query

There are multiple ways to influence which results the query produces:

​
Setting the number of results

By default, Hyperspell will return 10 results. You can change this by passing the max_results parameter to query options: 
response = client.memories.search(
    query="what did joe think about my poetry collection?",
    sources=["slack", "gmail"],
    options={
        "max_results": 20
    }
)
print(response.documents)
This will both influence how many documents are returned, but also how many documents will be fed into the answer model if you set answer to true.

​
Weighting data sources

In some cases, you may want to influence which data sources are used to answer a query. You can do this by passing the weight parameter to query option for each data source : 
response = client.memories.search(
    query="what did joe think about my poetry collection?",
    sources=["slack", "gmail"],
    options={
        "slack": {
            "weight": 0.5
        },
        "gmail": {
            "weight": 1.5
        }
    }
)
print(response.documents)
All weights will be normalized, so in this example, the gmail source will be weighted three times more than the slack source. The weights will be used internally by the re-ranker to influence which documents are returned and used for answering the query.