SkillsAdd

docs.hyperspell.com

setup-hyperspell

Guide the user through integrating Hyperspell into their project. Installs the SDK, configures the API key, detects the project type, sets up memory ingestion (OAuth or direct), and integrates memory search. Use when a user wants to add Hyperspell to their codebase, set up memory search, or connect user accounts via OAuth.

First seen Mar 10, 2026

Installation

$ npx skills add https://docs.hyperspell.com
View on skills.sh ↗ Website ↗
More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Not declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Skill metadata

Parsed from SKILL.md frontmatter.

Version1.0
CompatibilityRequires Node.js or Python environment with a package manager
Allowed toolsBash Read Write Edit Glob Grep WebFetch(https://docs.hyperspell.com/*) AskUserQuestion
More metadata
author
hyperspell
version
1.0

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 9,522 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 81 installs

SKILL.md

Setup Hyperspell

This skill walks you through integrating Hyperspell into a project. It references detailed sub-guides hosted at https://docs.hyperspell.com/skills/. You MUST fetch and read those links when instructed — they contain the implementation details for each step.

Instructions

Copy this checklist and track your progress:

Implementation Progress:
- [ ] Step 1: Install the Hyperspell SDK
- [ ] Step 2: Configure the API Key
- [ ] Step 3: Detect Project Type
- [ ] Step 4: Choose Memory Ingestion Method
- [ ] Step 5: Set Up Memory Ingestion
- [ ] Step 6: Set Up Memory Search
- [ ] Step 7: Verify and wrap up

Before You Begin

Display the following message to the user:

Hi {NAME}, I'll help you integrate Hyperspell into {PROJECT_NAME}. Hyperspell gives your agents memory and context from a broad range of data sources. Do you already have a Hyperspell account?

If possible, display a multiple choice yes / no option, otherwise simply listen to the user input.

If they don't have an account yet, display this:

Go to https://app.hyperspell.com and create a free account. Then, create an app for {PROJECTNAME} and pick which integrations, if any, you want to let your users use. Finally, create an API key and configure it as HYPERSPELLAPI_KEY in your project's existing secret manager or local environment. Don't paste the key into this chat. Tell me when it's configured.

Step 1: Install the Hyperspell SDK

Determine whether the hyperspell SDK is already installed. If not, install it:

  • For TypeScript/JavaScript projects: npm i @hyperspell/hyperspell or yarn add @hyperspell/hyperspell
  • For Python projects: uv add hyperspell or pip install hyperspell (use whatever package manager the project uses)

Step 2: Configure the API Key

Check whether HYPERSPELLAPIKEY is already configured where the application reads environment variables. Never print or display its value.

If it is not configured, display this message and wait for the user to configure it:

Please configure `HYPERSPELL_API_KEY` outside this chat, using this project's existing secret manager or local environment file.

If you don't have one yet, create one at https://app.hyperspell.com/api-keys

If you use a local environment file, make sure Git ignores it. Tell me when the key is configured.

After the user confirms, verify that HYPERSPELLAPIKEY is configured without displaying its value. Follow the project's existing environment and secret-management conventions rather than creating or overwriting an environment file.

If this project contains an .env.example, also put a dummy key in there (HYPERSPELLAPIKEY=hs-0-xxxxxxxxxxxxxxxxxxxxxx)

Step 3: Detect Project Type

Fetch and follow the instructions in detect-project.md to analyze the codebase and determine:

  • Repo type: Backend, Frontend-only, or Monorepo/Fullstack
  • Language: TypeScript/JavaScript or Python
  • Framework: Next.js (App/Pages Router), Express, FastAPI, SPA, etc.
  • Auth system: Clerk, Auth0, NextAuth, custom, or none
  • AI SDK: Vercel AI SDK, LangChain, or none

Store these detection results for use in subsequent steps.

Step 4: Ask How User Wants to Add Memories

Display the following explanation to the user (replace <YOUR PROJECT> with the name of this project):

Hyperspell can create memories from many sources: email, Slack, documents, chat transcripts, or uploaded files.

Most projects let their users connect their accounts (Gmail, Slack, etc.) for automatic memory ingestion. Other projects add memories programmatically by uploading files or tracking conversations.

How do you want to create memories in <YOUR PROJECT>?

Ask the user with this multiple choice:

  • Let users connect their accounts - Users authorize their Gmail, Slack, etc. and Hyperspell automatically ingests their data
  • Add memories directly - You programmatically add memories via API (file uploads, conversation tracking, etc.)

Step 5: Set Up Memory Ingestion

Based on the user's choice in Step 4 and the detection results from Step 3, set up the appropriate ingestion method.

If user chose "Let users connect their accounts" (OAuth):

The OAuth flow requires two pieces:

  1. A backend endpoint that generates a user token (using your API key) and

immediately exchanges it for a one-time connection code

  1. A frontend that redirects users to connect.hyperspell.com with only that code

Fetch and follow the instructions in oauth.md and implement what applies to this project:

  • If the project has a backend: Create the connection-code endpoint using the framework examples in oauth.md.
  • If the project has NO backend (frontend-only): Display this message:

`` The OAuth connect flow requires a backend endpoint to securely generate a user token and exchange it for a one-time code. You'll need to create an endpoint on a separate backend that calls Hyperspell's /auth/user_token API, POSTs the result to /oauth/token-exchange/issue, and returns only the code to your frontend. `` Then continue with the frontend setup, leaving a TODO placeholder for the connection-code endpoint URL.

  • If the project has a frontend: Create the connect button component using the React example in oauth.md.
  • If the project has NO frontend (backend-only): Display this message:

`` Since this is a backend-only project, exchange the user token for a one-time code with POST /oauth/token-exchange/issue, return only that code to your frontend, then redirect to: https://connect.hyperspell.com?code={oneTimeCode}&redirect_uri={returnUrl} ``

If user chose "Add memories directly" (Programmatic):

  • If the project has a backend: Fetch and follow the instructions in direct-ingestion.md to set up memory operations. Use the SDK with your API key and pass the user ID directly.
  • If the project has NO backend (frontend-only): Display this message:

`` Adding memories directly from a frontend requires a backend endpoint to securely make Hyperspell API calls. You'll need to either: 1. Create a backend endpoint that proxies memory operations, OR 2. Create a backend endpoint that generates user tokens (see oauth.md for examples) `` Then follow direct-ingestion.md, noting that the user will need to set up the backend piece separately.

Step 6: Set Up Memory Search (SDK Integration)

Display the following message:

Now that we've set up memory ingestion, let's integrate Hyperspell into your app so it can search and use those memories.

Determine the integration pattern:

First, analyze the codebase to see if the project has an existing AI/LLM integration with tools or function calling.

  • If the agent already uses tools → Use Pattern 1: Hyperspell as a Tool. Do not ask, just proceed with this pattern.
  • If it's a simple conversational agent with no tools → Ask the user which pattern they prefer (see below).
  • If there's no AI integration yet or it's unclear → Ask the user which pattern they prefer (see below).

When asking the user, present these options:

How would you like to integrate Hyperspell's memory search?
  • As a tool in your AI calls (Recommended) - Your AI decides when to search memories. Best for agents with multiple capabilities or when you want intelligent search decisions.
  • Direct search with AI answer - Hyperspell answers questions directly from memories. Best for simple Q&A bots without other tools.
  • Direct search for context only - Get relevant memory snippets to use however you want. Best for custom RAG pipelines or non-AI uses.

Important: Do not use "Direct search with AI answer" to replace an existing AI call if that call relies on other tools - those tools cannot be passed to the Hyperspell API.

Based on the user's choice, fetch and follow the appropriate section in search.md:

  • "As a tool" → Create the search helper, then follow the tool integration for their SDK (Vercel AI, OpenAI, Anthropic, etc.)
  • "Direct search with AI answer" → Create the search helper only, call it with answer: true from existing code. Do NOT create a tool wrapper.
  • "Direct search for context only" → Create the search helper only, call it with answer: false from existing code. Do NOT create a tool wrapper.

Step 7: Verify and Wrap Up

Run the project's relevant tests, type checks, or build command. Do not claim the integration is complete if those checks fail.

Summarize:

  • What you changed
  • What you verified
  • Any remaining configuration or manual setup