# Configuration Source: https://docs.hyperspell.com/advanced/configuration Every setting in the Hyperspell dashboard, what it does, and who can change it. Almost everything in Hyperspell is configured from Settings in the dashboard. Settings are split into two groups. Personal settings affect only you: your profile, your connected accounts, your agents. Admin settings affect the whole organization: integrations, members, content rules, API keys. Admins see both groups. Members see only the personal group. This page walks through each section. [Content rules](/advanced/content-rules) and [connecting agents](/agents/overview) have their own pages and are only summarized here. ## Personal settings ### Profile Your name and avatar, and the dashboard theme: light, dark, or follow the system. The theme applies to the browser you set it in. ### Connect Agents Setup instructions for Claude, ChatGPT, MCP clients, and the command line tool, each pre-filled with what you need. See [Connecting agents](/agents/overview). Below the agent options is your personal API keys list. Keys created here are tied to your account and see exactly what you see. Create one for an agent that acts on your behalf, and revoke it here when you no longer need it. Revoking takes effect immediately. ### Connections The tools your admin has set up as personal integrations, with your own connection state for each. Click Connect to sign in to a tool with your account, or Disconnect to remove your connection and the data it brought in. Some tools let you narrow what Hyperspell reads from your account: * Slack and Microsoft Teams let you pick channels. Direct messages and private channels are included only if your admin allows them and you select them. * Google Drive and Dropbox let you pick folders. You can also choose whether files shared with you that sit outside any folder are included. If a tool supports several accounts, for example two Gmail addresses, you can connect each one, provided your admin has allowed multiple connections for that tool. ## Admin settings ### Organization Your organization's name and logo, as shown to members. Admins can edit both. Usage and billing live on the same page: your current plan, how much of each limit you have used, and, where self-service is enabled, the option to change plans. Any member can see usage. Only admins can change the plan. ### Members The people in your organization and their roles. | Role | Can do | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Member | Use the brain, connect their own personal tools and agents, create personal API keys. | | Admin | Everything a member can, plus: add and configure integrations, write content rules, invite and remove members, change roles, create organization-wide API keys, manage billing. | Invite people by entering one or more email addresses. Invitations show as pending until accepted. For existing members, the Edit menu lets you change a role or remove someone from the organization. Removing a member revokes their access, deletes documents only they could see, and keeps everything that was shared. See [When people leave](/core/permissions#when-people-leave). ### Integrations The list of tools connected to your brain, with a health indicator for each: syncing, live, waiting for first sync, reconnect required, and so on. #### Adding an integration Click Add Integration and choose a tool. You are then asked how it should be set up: * Shared: one credential for the whole team, connected once by an admin. Its data is visible to everyone in the organization. * Personal: each member connects their own account. Their data is private to them by default. * Both, where the tool supports it. Shared is offered only for tools that support a service account or API key. Email and calendars, for example, are personal only. The choice is not permanent; you can change it on the integration's page later. Hyperspell does not copy the source tool's permission settings. Everything a shared credential can read becomes visible to everyone in your organization. Choose shared only for tools whose content the whole company may see, and use [filter rules](/advanced/content-rules#filter-rules) to hold back specific categories. Meeting-notes tools are the one exception: Gong, Fireflies, Fathom, Fellow, and Granola. Recordings often include one-on-ones, so a shared connection for these tools does not make its content visible to everyone automatically. If you want a company-wide meeting corpus, [tell us](mailto:hello@hyperspell.com) when you connect it and we will turn that on. #### Configuring an integration Each integration has its own page. At the top, two switches control the connection modes: * Allow personal connections. Members can connect their own accounts. * Allow shared connections. A team-wide credential can be set up. Turning a mode off hides its settings but never disconnects existing connections. To remove connections, do so explicitly in the sections below. The Configuration section holds the options that shape what gets indexed. The exact options depend on the tool. The most common are: | Option | What it does | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | History window | How far back to index: 30, 90, 180, or 365 days, or everything. Defaults are 180 days for documents and issues, 90 days for mail, messages, and CRM records. | | Channel defaults (Slack, Teams) | Which channels new connections index by default: public channels, private channels, direct messages. Members can still narrow their own selection. | | Folder options (Drive, Dropbox) | Whether to index only files the connecting person owns, whether to require a folder selection before anything syncs, whether to include spreadsheets. | | Mail options (Gmail, Outlook) | Skip newsletters, bounces, and auto-replies. Optionally surface only conversations the person took part in. | | Object types (CRMs) | Which record types to index, such as contacts, companies, and deals. | | Repositories and file patterns (GitHub, GitLab) | Which organizations and repositories to include, and file patterns to include or exclude. | Changing an option applies to data received from then on. When you save, Hyperspell asks whether to also re-sync existing connections so the new options apply to what is already indexed. The Personal connections section lists each member's connection with its folder or channel selection, lets you allow multiple connections per person, and offers a re-sync. The Shared connection section is where an admin enters the service account or API key, or replaces it later. Each tool's [integration page](/integrations/overview) shows where to find these credentials. Deleting an integration disconnects every connection for every member and stops syncing. Already indexed content is not deleted but stops updating. You are asked to type the integration's name to confirm. #### External MCP servers If your company runs its own MCP servers, for example over an internal database or a custom tool, admins can register them as live sources. Hyperspell queries them at answer time and cites the results, but never indexes or stores what they return. Registering a server takes a label, a public HTTPS URL, and an optional bearer token. Hyperspell then lists the server's tools, and you approve the ones the brain may call. Nothing is approved by default, and a tool whose definition changes is suspended until you approve it again. All members share the one credential you enter, so only connect servers whose content the whole organization may see. ### Content rules Filter rules and sharing rules. See [Content rules](/advanced/content-rules). ### API Keys Keys created here are organization-wide. They are not tied to a person and see only content shared with the whole organization. Use them for a team bot, an internal tool, or any agent that should never see personal data. When creating a key you choose a label and the permissions it carries: reading memories, adding and removing memories, reading and managing connections, running actions, and organization-level access. A write permission includes its read counterpart. New keys default to read-only. The key is shown once, at creation. Copy it then. Personal keys that members created from Connect Agents are listed separately on this page, with the owner's name, so admins can see and revoke them. ### Advanced Settings that most organizations never need to touch. Webhooks let another system know when something happens in Hyperspell. Enter a URL, choose which events to send, and use the test button to check the connection. Events available: a member connects a new account, a data source finishes syncing, and a new memory becomes available. The redirect URL is where Hyperspell Connect, the hosted page for connecting accounts, sends people when they are done. Most organizations leave it empty. Source weights let you tell the brain to lean on some tools more than others when compiling pages: high, normal, low, or excluded per tool. A separate switch controls whether compiled pages include citations back to their sources. ## Generated pages Hyperspell compiles pages about your company, its projects, and its people from what it has indexed. These are what the [command line tool](/agents/cli) syncs to disk and what agents read with the context tools. A few things about them can be configured, under File System in the dashboard. * Organization type. Hyperspell detects whether you are, for example, a client services firm, a sales-driven company, a legal practice, or an engineering organization, and adjusts which pages it writes. You can override the detection. * Structure. Admins can adjust the instructions used to write each tier of pages, or define a custom set of pages with their own prompts and search queries. * Canonical documents. Documents you write or upload that outrank anything Hyperspell infers. Use them for policies, org charts, or the official version of a process. * Category filter. Categories stripped from shared pages before they are stored: HR matters, personal information, fundraising, passwords and secrets, hiring and firing, plus any you add. This applies only to generated pages. Filter rules for indexed content are covered under [content rules](/advanced/content-rules). * Skills. Procedures and memos delivered to agents word for word, without any rewriting. * People. The directory used to write personal pages and to identify people on the command line tool. ## Regions Your organization lives in one region, chosen at sign-up: the United States or the European Union. Data is stored and processed in that region and never copied to the other. The dashboard, API, and MCP endpoints differ by region. See [Regions and data residency](/resources/data-residency). ## Not configurable from the dashboard A few things need a message to [support](mailto:hello@hyperspell.com): * Renaming or deleting the app that holds your brain. * Erasing all of your organization's data. * Moving an organization between regions, which is not possible; create a new organization in the other region instead. # Content rules Source: https://docs.hyperspell.com/advanced/content-rules Filter rules keep sensitive content from spreading. Sharing rules bring useful personal content to the team. This page explains both and how they are applied. By default, a document's audience depends on where it came from: content from a shared integration is visible to everyone in the organization, and content from a personal integration is visible only to the person who connected it. Content rules let admins refine those defaults based on what a document actually says. There are two kinds of rules. Filter rules narrow. Sharing rules widen. Both are written by admins in Settings, and both are judged by the same machinery when content arrives. ## Filter rules Filter rules exist for the categories that must never spread: compensation, HR matters, legal disputes, credentials, whatever your company decides. They apply to any content that would otherwise reach more people than those who connected it. When a filter rule matches a document: * If the document came in through a shared integration, nobody can see it. * If it came in through a personal integration and a sharing rule would have widened it, it stays with the person who connected it. Nothing is deleted. The content stays stored, held back from the company brain. Admins can review what a filter caught to check for false positives, and see which rule matched and why. They do not see the private content of others in the process. Filter rules are set up by admins and apply to everyone in the organization. Members cannot opt out of them. ## Sharing rules Content from personal integrations is private by default, which keeps a lot of useful knowledge out of reach: the customer call in one person's Granola, the vendor negotiation in another's inbox. Sharing rules are how that content reaches the team on purpose. A sharing rule says "content like this is meant for the whole organization", for example conversations with customers, or meetings about product. Admins write the rules. Each person then decides, for their own connections, which rules to turn on. A rule that a person has not turned on is never even evaluated against their content. When a sharing rule a person turned on matches one of their documents, the document is offered to the organization. Whether it is shared automatically or after the owner confirms depends on how confident the match is, described [below](#confidence-and-review). Sharing rules are being rolled out to organizations in stages. If you do not see the Sharing settings in your dashboard yet, [let us know](mailto:hello@hyperspell.com) and we will enable them for you. ## Writing a rule A rule has a name and a description. The description is what Hyperspell uses to judge content, so write it the way you would explain the category to a new colleague. Vague descriptions produce vague matches. | Weak description | Better description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Sensitive stuff | Salary figures, compensation bands, bonus and equity details for named employees | | Legal | Drafts or executed contracts, NDAs, terms of service, and correspondence with outside counsel | | Customer calls | Meetings or call transcripts where at least one participant is a customer or prospect, including sales discovery calls and support escalations | A few things to keep in mind: * Rules are judged on content, not on titles. A document called "Q3 planning" that spends a paragraph on salary bands will match a compensation filter. * One good example beats three adjectives. If you can, add a sentence or two of the kind of content you mean. * Start with filter rules for the categories that would cause real harm if they spread. Add sharing rules once those are in place. ## How rules are applied Rules are evaluated when content arrives, not when someone asks a question. This keeps queries fast and makes every decision reproducible. A document comes in through one or more connections. Hyperspell records which connection brought it in and who owns that connection. The same document can arrive through several connections, for example a shared drive that two people also connected personally, and each is recorded. Hyperspell works out which rules apply to this document and judges each one against the content: * The default rule of every connection that brought the document in. A shared connection's default is "everyone". A personal connection's default is "its owner". * Sharing rules that at least one owner of the document has turned on. * Filter rules, but only if anything above could widen the document beyond a single owner. Purely private content that no sharing rule touches has nothing to narrow, so filters do not run on it. Each match is recorded with the rule, its version, and how confident the match was. The document's audience is the union of every sharing rule that matched, intersected with every filter rule that matched. In plain terms: sharing rules add people, filter rules take them away, and a filter always beats a sharing rule. The result is written down as grants, one per audience, each pointing at the rule and version that produced it. Every grant can be explained after the fact. ### Confidence and review Each match carries a confidence score. Where the score falls decides what happens: * Above the automatic threshold, the rule acts on its own. * In the middle band, the match is queued for the owner to review. * Below the ignore threshold, nothing happens. Filter rules act on any match. The admin who set them up already decided that the category should not spread, so there is nothing to ask. Sharing rules are more careful. New sharing rules start with automatic sharing turned off, so every match asks the owner first. Queued matches appear in that person's Inbox, one card per document, showing the source, the title, the rule that matched, and the passage that triggered it. The owner clicks Share or Dismiss. Nothing leaves their view until they do. A document that matches both a sharing rule and a filter rule is never shown in the Inbox. The filter has already decided. ### What changes when you change a rule Sharing is sticky and filters are live. Once a document has been shared with the organization, it stays shared unless a filter rule narrows it. Filter rules are re-evaluated whenever they change, so removing one lets the content it was holding back widen again. | You do this | What happens | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Add or edit a filter rule | Applies to content that arrives from now on. Existing content is only re-checked if an admin explicitly runs the rules over it, which shows an estimate and asks for confirmation first. | | Pause or delete a filter rule | Content it was holding back becomes visible again at its normal audience. | | Add a sharing rule | Nothing happens until people turn it on for their connections. | | Turn a sharing rule on for yourself | Your content is judged against it from now on. An option lets you also check your existing content. | | Turn a sharing rule off | Nothing already shared is taken back. Sharing never retracts on its own. | | Pause or delete a sharing rule | Existing shares stand. New content is no longer judged against it. | | Disconnect an integration | The audience that connection contributed is removed. Anything the document earned through other connections or rules stays. | The only way to take back something that was shared is a filter rule that matches it. This is deliberate: sharing should be a decision people can trust, not something that flickers as configuration changes. ## What you will see in the dashboard Admins find rules under Settings, in two lists: filter rules and sharing rules. Each rule can be created, edited, paused, or deleted. Configuration and content are kept apart on purpose, so this page never shows anyone's documents. Each member has two personal surfaces: * Sharing lists the admin's sharing rules as toggles. Turning one on applies from that moment forward. A secondary action lets you check your existing content against the rule too. * Inbox shows the documents waiting for your decision. Acting on a card brings the next one into view. When the queue is empty it says so. Admins see only their own content in their Inbox. ## Guarantees These hold regardless of how rules are configured: * Nothing widens past its defaults without a matching rule, the owner's opt-in, and, when the match is uncertain, the owner's approval. * Filter rules beat sharing rules. Filtered content always stays with the people who connected it, or with nobody if it came from a shared integration. * Sharing fails closed. If a rule cannot be evaluated, nothing is shared. * Sharing never retracts by itself. Pausing or deleting a sharing rule leaves existing shares standing. * Every grant is explainable: which connection, which rule, which version, who decided. * A document outlives its first owner. As long as one active connection still holds it, it stays in the brain. * Nobody, admins included, sees another person's private content in the process of managing rules. ## Related The model that content rules operate on. Every other setting in the dashboard, including how integrations are set up as shared or personal. # ChatGPT Source: https://docs.hyperspell.com/agents/chatgpt Connect ChatGPT on the web or desktop to your company brain as a custom MCP connector. ChatGPT connects to Hyperspell through its custom connectors, which live behind a setting called developer mode. Once set up, ChatGPT can search the brain and ask it questions in any chat where the connector is enabled. You sign in with your Hyperspell account, so ChatGPT sees exactly what you are allowed to see. ChatGPT support is rolling out. It depends on connector registration that we are enabling for organizations in stages. If the sign-in step does not complete for you yet, use the [Claude connector](/agents/claude) or an [MCP client](/agents/mcp) in the meantime, and check back shortly. ## Before you start * Custom connectors require a paid ChatGPT plan. Plus and Pro plans get read-only connectors, which is all Hyperspell needs for asking questions. Business, Enterprise, and Edu plans get full access. * On Business and Enterprise plans, a workspace admin has to allow custom MCP connectors before members can see the option. This is under Workspace settings, then Permissions and roles. * Copy your MCP URL from the dashboard under Settings, Connect Agents, ChatGPT. For most organizations it is `https://api.hyperspell.com/mcp`, and accounts in the EU region use `https://api.eu.hyperspell.com/mcp`. Organizations on a dedicated Hyperspell instance have their own URL, which is why copying it from the dashboard is the safe choice. ## Connect ChatGPT In ChatGPT, open Settings and turn on developer mode. On a personal plan this is under your own settings. On Business and Enterprise plans it appears only after your workspace admin has allowed custom connectors. ChatGPT settings with the developer mode toggle Open Settings, then Connectors. On some plans this section is called Apps. Create a new connector, give it a name such as Hyperspell, and paste the MCP URL. The ChatGPT new connector dialog with the Hyperspell MCP URL filled in ChatGPT opens a Hyperspell sign-in page. Sign in with your Hyperspell account and approve the connection. In each new chat, open the plus menu, choose developer mode, and turn on the Hyperspell connector. A connector that is installed but not enabled for the conversation is never called. This is the usual reason ChatGPT seems to ignore Hyperspell. The ChatGPT plus menu with developer mode and the Hyperspell connector toggled on ## Using Hyperspell in ChatGPT With the connector enabled, ask questions in plain language: * "What is the current status of the Acme renewal?" * "Find the latest version of our onboarding checklist." * "Who worked on the data export feature, and what is left to do?" ChatGPT calls Hyperspell when it decides the question needs company context, and shows which tool it used. Answers include citations you can follow back to the source documents in the dashboard. ## Troubleshooting **I cannot find developer mode or connectors.** OpenAI moves these settings between releases and gates them by plan. Check that you are on a paid plan and, on Business or Enterprise, that your admin has allowed custom MCP connectors. **ChatGPT does not call Hyperspell.** Open the plus menu in the chat and confirm the connector is enabled for that conversation. It has to be turned on per chat. **The sign-in step fails.** ChatGPT support is still rolling out, and the sign-in may not complete for every organization yet. Use the [Claude connector](/agents/claude) or an [MCP client](/agents/mcp) for now, or [contact us](mailto:hello@hyperspell.com). **Answers miss things I know are in a tool.** Check in the dashboard that the tool is connected and has synced. ChatGPT only sees what your account can see. # Claude Source: https://docs.hyperspell.com/agents/claude Connect Claude on the web, Claude Desktop, or Cowork to your company brain as a custom connector. Claude connects to Hyperspell as a custom connector. You paste one URL, sign in with your Hyperspell account, and Claude can search and ask the brain in any conversation. No API key is involved, and the connection is yours alone: Claude sees exactly what you are allowed to see. This page covers Claude on the web, Claude Desktop, and Cowork. For Claude Code, the terminal agent, see [MCP clients](/agents/mcp) or the [command line tool](/agents/cli). ## Before you start * You need a Hyperspell account. If you were invited by a teammate, accept the invitation first. * On Claude Team and Enterprise plans the setup has two parts, described [below](#team-and-enterprise-plans). * Copy your MCP URL from the dashboard under Settings, Connect Agents, Claude. For most organizations it is `https://api.hyperspell.com/mcp`, and accounts in the EU region use `https://api.eu.hyperspell.com/mcp`. Organizations on a dedicated Hyperspell instance have their own URL, which is why copying it from the dashboard is the safe choice. ## Connect Claude In [claude.ai](https://claude.ai) or Claude Desktop, open Settings, then Connectors. Scroll to the bottom and click Add custom connector. Claude settings with the Connectors tab open and the Add custom connector button visible Give the connector a name, such as Hyperspell, paste the MCP URL, and click Add. The Add custom connector dialog with a name and the Hyperspell MCP URL filled in Claude opens a Hyperspell sign-in page. Sign in with your Hyperspell account and approve the connection. You are returned to Claude, and Hyperspell appears in your list of connectors. The Hyperspell authorization page asking to approve access for Claude ## Team and Enterprise plans On Claude Team and Enterprise plans, connectors are added at the workspace level first and then connected by each person. 1. A workspace owner opens Organization settings, then Connectors, and clicks Add, then Custom, then Web. They enter the connector name and the MCP URL. No sign-in happens at this step. That is expected. 2. Each member then opens Customize, then Connectors, finds the Hyperspell connector, and clicks Connect. They sign in with their own Hyperspell account. The second step matters. The connector is shared across the workspace, but each person's connection is their own, so everyone sees only what they are allowed to see. ## Using Hyperspell in Claude Start a new conversation and make sure the Hyperspell connector is enabled. Claude shows connected tools in the menu below the message box, and you can toggle them per conversation. Then ask questions the way you would ask a colleague: * "What did we decide about the pricing page in the last planning meeting?" * "Who at Acme have we spoken to, and what did they ask for?" * "Summarize what is in the brain about the mobile app launch." Claude decides when to call Hyperspell. For a factual question it usually asks the brain directly and returns an answer with citations. For a broader task it may search first and read a few documents. You can also be explicit: "search Hyperspell for..." or "remember this in Hyperspell" both work. A Claude conversation where an answer cites documents from Hyperspell ## Troubleshooting **Claude does not call Hyperspell.** Check that the connector is enabled for the current conversation. Connectors can be turned off per chat, and a new chat sometimes starts with them off. **The sign-in page does not appear, or the connection fails.** On Team and Enterprise plans, confirm the workspace owner has added the connector first. If you are in the EU region, make sure you used the EU URL. If it still fails, [contact us](mailto:hello@hyperspell.com). **Answers are missing things I know are in a tool.** Check in the dashboard that the tool is connected and has finished its first sync. Also remember that Claude sees only what you can see: a colleague's personal integration is not visible to you unless a [sharing rule](/advanced/content-rules) applies. **I want to disconnect.** In Claude, open Settings, then Connectors, and remove Hyperspell. In the Hyperspell dashboard, your personal API keys and connected agents are listed under Settings, Connect Agents. # Command line tool Source: https://docs.hyperspell.com/agents/cli Keep a Markdown copy of your company brain on your computer for coding agents, and ask the brain questions from the terminal. Coding agents such as Claude Code, Codex, and Cursor are best at reading files. The Hyperspell command line tool plays to that strength. It keeps an up-to-date folder of Markdown pages about your company, projects, people, and decisions on your machine, and tells your coding agents where to find it. Agents read the pages with the tools they already have, without a network call, and can still ask the brain a live question when the pages are not enough. The tool has two parts, installed together: * `hyperspell`, the sync tool. It runs in the background, keeps the Markdown folder current, and configures your coding agents. * `hyperbrain`, the query tool. It lets you, or an agent, ask the brain a question, search it, or save a note from the terminal. ## Install In the dashboard, open Settings, then Connect Agents, and choose CLI. The dashboard generates an install command that includes a one-time token tied to you. The token works once and expires after an hour, so generate a fresh one when you need it. The Set up the CLI dialog showing a generated install command with a copy button Paste the command into a terminal on your Mac or Linux machine. It looks like this, with your token in place of the placeholder: ```bash theme={null} curl -fsSL -X POST -H 'Content-Type: application/json' \ --data '{"install_token":"YOUR_TOKEN"}' \ 'https://app.hyperspell.com/api/daemon/install.sh' | bash ``` The installer sets up an isolated Python environment, installs both tools, saves your credentials, registers the sync tool to start automatically when you log in, and runs a first sync. It refuses to run as root. ```bash theme={null} hyperspell status ``` This shows when the brain last synced, where the files are, and a log of the changes the installer made to your agent configuration. Prefer to install by hand? The query tool is on PyPI: `uv tool install hyperspell-brain` or `pipx install hyperspell-brain`, then `hyperbrain login`. The sync tool is only distributed through the dashboard install command. ## Sign in from another machine If you install on a second machine, or your credentials expire, run: ```bash theme={null} hyperspell login ``` The tool prints a short code and opens a page in your browser. Approve the login there, and the terminal picks it up on its own. ```mermaid theme={null} sequenceDiagram participant T as Terminal participant H as Hyperspell participant B as Your browser T->>H: Request a device code H-->>T: Code + approval link T->>B: Open approval page B->>H: You approve the code loop every few seconds T->>H: Is it approved yet? end H-->>T: Credentials T->>T: Save to ~/.hyperspell/config.toml ``` The approval page shows the code, the app it is for, and where the request came from. It asks you to confirm that you started the login yourself on your own device. If someone sends you an approval link by email or chat, do not approve it. Codes work once and expire after ten minutes. The Approve Device Login page with the app name, a confirmation checkbox, and an Approve button ## What gets installed The tool writes to a few well-defined places. | Location | What it holds | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `~/.hyperspell/` | Your credentials, logs, and the canonical copy of the synced pages. Readable only by your user. | | `~/Hyperspell/` | A readable mirror of the pages, so agents running in a sandbox or container can read them too. | | `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.cursorrules` | A short managed block telling each agent where the brain lives and when to use it. The block sits between two marker comments, and the tool never touches anything outside them. | | Claude Desktop and Claude Code configuration | A registration for the Hyperspell MCP server, so those agents can also ask the brain live questions. | Once installed, a coding agent can answer "what does the billing service do and who owns it?" by reading `~/Hyperspell/`, and can fall back to `hyperbrain ask` for anything the pages do not cover. On a computer with several user accounts, everyone with an account can read the `~/Hyperspell/` mirror. If that is a concern, run the install with `--no-visible-mirror`, or set `visible_mirror = false` in `~/.hyperspell/config.toml`. Agents then read the private copy instead. ## Ask from the terminal The query tool works for people and for agents alike. ```bash theme={null} # Ask a question and get a cited answer hyperbrain ask "who owns the mobile release process?" # Search for documents without an answer hyperbrain search "Q3 pricing experiment" # Save something worth remembering hyperbrain remember "The staging database is refreshed from production every Sunday night." # Check your setup hyperbrain doctor ``` `hyperbrain help --agent` prints the whole command surface as one short document, which is handy to paste into an agent's instructions. ## Keep it up to date The sync tool checks for a new version of itself and of the query tool once a day and upgrades within the supported range. `hyperspell update` forces a check. `hyperbrain update` upgrades the query tool by itself. Other commands you may need: | Command | What it does | | --------------------------- | ------------------------------------------------------------------------------------------------------- | | `hyperspell status` | Show sync state, file locations, and recent actions. | | `hyperspell sync --once` | Sync now and exit. | | `hyperspell search "query"` | Search the synced pages locally. | | `hyperspell uninstall` | Remove the tool and its autostart entry. Add `--purge` to also delete the synced files and credentials. | ## Brain on disk, or not Some organizations do not want a copy of the company brain sitting on employee laptops. The sync tool supports a lean mode for this. In lean mode it still installs the query tool and registers the MCP server with your agents, so they can ask the brain live questions, but it syncs no pages to disk and removes any it previously synced. Admins can require lean mode for the whole organization from Settings. When that policy is on, every install is lean and the option cannot be turned off on individual machines. Individuals can also choose lean mode for their own install with `--no-context-docs`. ## Troubleshooting **The install command fails immediately.** The token works once and expires after an hour. Generate a new one from the dashboard. If you are on a machine where you are root, the installer stops on purpose; run it as a normal user. **Claude Code does not seem to know about the brain.** Open a new session so it re-reads `~/.claude/CLAUDE.md`, and check `claude mcp list` shows the Hyperspell server. `hyperspell status` lists what the installer configured. **The pages look stale.** Run `hyperspell sync --once` and then `hyperspell status`. If the sync tool is not running, `hyperspell login` re-registers it to start automatically. **I want everything gone.** `hyperspell uninstall --purge` removes the tools, the synced files, the credentials, and the managed blocks in your agent configuration files. # MCP clients Source: https://docs.hyperspell.com/agents/mcp Connect Claude Code, Codex, Cursor, or any other agent that speaks the Model Context Protocol. Hyperspell runs a server that speaks the Model Context Protocol, or MCP. Any agent that supports MCP can connect to it and gain the same tools Claude and ChatGPT use: ask the brain a question, search it, read its compiled pages, or save a note into it. This page covers agents that authenticate with an API key, which includes coding agents such as Claude Code, Codex, and Cursor, as well as desktop apps and cloud agents. For Claude on the web or desktop, use the [Claude connector](/agents/claude) instead. For ChatGPT, see [ChatGPT](/agents/chatgpt). Neither of those can send an API key, so they sign in with your account. ## Get your endpoint and key Open the dashboard, go to Settings, then Connect Agents, and choose MCP clients. Everything you need is on that screen, pre-filled with an API key created for you. The Connect via MCP dialog with Cursor, Claude Code, and Other tabs and a generated API key Two things worth knowing about that key: * It is personal. It is tied to your account and lets the agent see what you see. Treat it like a password. * It is created once and reused. Reopening the dialog shows the same key. You can revoke it under Settings, Connect Agents, API Keys at any time, and create a new one. The endpoint depends on your region: | Region | MCP endpoint | | ----------------------- | -------------------------------------------------------------- | | United States (default) | `https://api.hyperspell.com/mcp` | | European Union | `https://api.eu.hyperspell.com/mcp` | | Dedicated instance | The URL shown in your dashboard, specific to your organization | If your organization runs on a dedicated Hyperspell instance, the shared endpoints above will not know your organization. Always copy the URL from the dashboard. ## Set up your client Click Add to Cursor in the dashboard. Cursor opens and asks you to confirm the new server, already configured with your key. If the button does nothing, or you prefer to edit the file yourself, add this to your `mcp.json` (in `.cursor/mcp.json` for a project or `~/.cursor/mcp.json` globally): ```json theme={null} { "mcpServers": { "hyperspell": { "url": "https://api.hyperspell.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` The dashboard shows this snippet with your real key filled in, so you can copy it directly. Run the command shown in the dashboard. It has this shape: ```bash theme={null} claude mcp add --transport http hyperspell https://api.hyperspell.com/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` Claude Code adds the server to your configuration. Run `claude mcp list` to confirm it shows up, then start a session and ask something about your company. If you also install the [command line tool](/agents/cli), it registers Hyperspell with Claude Code for you and adds a short note to your `CLAUDE.md` telling Claude Code when to consult the brain. Add the server to `~/.codex/config.toml` and put your key in an environment variable: ```toml theme={null} [mcp_servers.hyperspell] url = "https://api.hyperspell.com/mcp" bearer_token_env_var = "HYPERSPELL_API_KEY" ``` ```bash theme={null} export HYPERSPELL_API_KEY="YOUR_API_KEY" ``` Restart Codex to pick up the change. Any client that supports remote MCP servers over HTTP can connect. You need two values: * Server URL: `https://api.hyperspell.com/mcp` (or the EU endpoint). * An `Authorization` header with the value `Bearer YOUR_API_KEY`. Where your client asks for a transport, choose HTTP or Streamable HTTP. Hyperspell does not support the older SSE-only transport or stdio. ## What the agent gets Once connected, the agent sees these tools. It chooses among them based on what you ask, so you rarely need to name them. | Tool | What it does | | ------------ | ----------------------------------------------------------- | | `ask` | Ask the brain a question. Returns an answer with citations. | | `search` | Find documents matching a query, ranked, without an answer. | | `remember` | Write a note or document into the brain. | | `get_memory` | Fetch one document by source and ID. | Results are compact by default: an answer plus its citations, or a list of documents plus their summaries. Agents can ask for the full document when they need it. ## Personal keys and organization keys The key from Connect Agents acts as you. That is what you want for an agent you use yourself. For an agent that serves the whole team, such as an internal bot, an admin can create an organization-wide key under Settings, API Keys. That key sees content shared with everyone and nobody's personal data. See [Permissions](/core/permissions) for the difference and [Configuration](/advanced/configuration#api-keys) for creating keys. ## Troubleshooting **The agent lists the server but every call fails with an authentication error.** Check that the header reads `Bearer` followed by a space and the key, and that the key has not been revoked in the dashboard. **The agent connects but says the brain is empty.** Run `brain_status`, or ask the agent to. If your tools are still syncing, the brain fills in over the next minutes to hours. If a source is missing, check its connection in Settings. **I am in the EU region and get a not-found error.** Use `https://api.eu.hyperspell.com/mcp`. Keys are region-specific, and the US endpoint will not accept an EU key. # How agents use Hyperspell Source: https://docs.hyperspell.com/agents/overview What an AI agent can do once it is connected to your company brain, and the ways to connect one. An AI agent on its own knows only what is in the current conversation. However just like humans, agents produce their best work if they have context on the goals, decisions, history, and future plans. Hyperspell provides that context to agents. When you connect an agent to Hyperspell, it can query the company brain to get grounded answers, with a paper trail of where the information came from. ## System Prompts We recommend using an additional system prompt to guide the agent's behavior. Hyperspell is the source of truth for everything about this organization: people, roles, projects, decisions, history, and priorities. When starting a new task, use the Hyperspell MCP to get the context on the task, goals, prior decisions, and how it matters to the organization. Before answering any question that touches the organization — or making an assumption about who someone is, who owns what, or the state of a project — consult the Hyperspell MCP. Never guess about people, ownership, or project state when Hyperspell can tell you. You can add this to your Instructions for Claude in the personal settings. Admins can also add this to the Organization instructions at [claude.ai](https://claude.ai/admin-settings/organization). Additionally, you can add your agent's work, decisions, and insights into the brain to save it for later. Hyperspell is the source of truth for everything about this organization: people, roles, projects, decisions, history, and priorities. When starting a new task, use the Hyperspell MCP to get the context on the task, goals, prior decisions, and how it matters to the organization. Before answering any question that touches the organization — or making an assumption about who someone is, who owns what, or the state of a project — consult the Hyperspell MCP. Never guess about people, ownership, or project state when Hyperspell can tell you. Before compacting, or when done with a task, use the `remember` tool to save your decisions to the brain. Things that should be remembered: * Decisions made and summaries of tasks you completed * Complex tool calls that took several reasoning steps to figure out the right tools and arguments * Insights about the user, their work, and the organization ## Agents act as you Every agent you connect acts with your identity and your permissions. It sees the documents you can see: everything shared with the organization plus your own personal data. It cannot reach a colleague's private inbox any more than you can. See [Permissions](/core/permissions) for the model behind this. Admins can also create organization-wide API keys for agents that are not tied to a person, such as an internal bot. Those see only content shared with everyone. [Configuration](/advanced/configuration#api-keys) covers when to use which. ## Choose your setup Claude on the web, Claude Desktop, and Cowork. One-click connector, sign in with your Hyperspell account. ChatGPT on the web and desktop, as a custom connector. Claude Code, Codex, Cursor, and any other agent that supports MCP. Keep a Markdown copy of the brain on your machine for coding agents, and ask questions from the terminal. **Slack.** If your organization uses Slack, an admin can also install the Hyperspell assistant in your workspace. Mention it in a channel or send it a direct message to ask the brain a question without leaving Slack. It appears as an option in Connect Agents once your Slack integration is connected. This is separate from the Slack integration that indexes your messages. ## Tips for getting good answers * Ask the way you would ask a colleague. "Who is the point of contact at Acme?" works better than a keyword list. * Mention names and dates when you have them. The brain resolves people, projects, and time ranges, so "what did Ben say about the migration in June" narrows things down a lot. * Ask for sources when it matters. Answers cite the documents they came from, and you can open any of them in the dashboard. * If an agent seems to ignore the brain, check that the connector is enabled for the current chat. Claude and ChatGPT both let you turn connectors on and off per conversation. # Add a reaction Source: https://docs.hyperspell.com/api-reference/actions/add-a-reaction https://api.hyperspell.com/openapi.json post /actions/add_reaction Add an emoji reaction to a message on a connected integration. # Send a message Source: https://docs.hyperspell.com/api-reference/actions/send-a-message https://api.hyperspell.com/openapi.json post /actions/send_message Send a message to a channel or conversation on a connected integration. # Delete user Source: https://docs.hyperspell.com/api-reference/authentication/delete-user https://api.hyperspell.com/openapi.json delete /auth/delete Delete the calling user's data (GDPR erasure). Deletion is processed asynchronously. The endpoint returns ``202 Accepted`` with an identifier for the deletion request. # Get a user token Source: https://docs.hyperspell.com/api-reference/authentication/get-a-user-token https://api.hyperspell.com/openapi.json post /auth/user_token Use this endpoint to create a user token for a specific user. This token can be safely passed to your user-facing front-end. # Get Basic user data Source: https://docs.hyperspell.com/api-reference/authentication/get-basic-user-data https://api.hyperspell.com/openapi.json get /auth/me Endpoint to get basic user data. # List connections Source: https://docs.hyperspell.com/api-reference/connections/list-connections https://api.hyperspell.com/openapi.json get /connections/list List all connections for the user. # Revoke connection Source: https://docs.hyperspell.com/api-reference/connections/revoke-connection https://api.hyperspell.com/openapi.json delete /connections/{connection_id}/revoke Revoke Hyperspell's access to a provider and delete this user's stored data. Revocation and deletion are processed asynchronously, so the endpoint returns ``202 Accepted`` immediately. Repeated requests for the same app, user, and provider are safe. # Device Login Source: https://docs.hyperspell.com/api-reference/device-auth/device-login https://api.hyperspell.com/openapi.json post /auth/device-login Start a device login flow and return a code and approval URL. This endpoint is unauthenticated because the device has no credentials yet. An administrator must verify and approve the request before credentials are issued. # Device Poll Source: https://docs.hyperspell.com/api-reference/device-auth/device-poll https://api.hyperspell.com/openapi.json post /auth/device-poll Poll for device code approval. Returns a JWT when approved. # Delete emotional state Source: https://docs.hyperspell.com/api-reference/emotional-state/delete-emotional-state https://api.hyperspell.com/openapi.json delete /emotional-state Delete emotional state for the authenticated user. Associated indexed content is also deleted. Optionally filter by ``relationship_id`` to delete only a specific relationship's emotional state. # Get latest emotional state Source: https://docs.hyperspell.com/api-reference/emotional-state/get-latest-emotional-state https://api.hyperspell.com/openapi.json get /emotional-state Retrieve the most recent emotional state for the authenticated user. Optionally filter by `relationship_id` for per-relationship scoping. Returns null if no emotional state exists. # Get recent emotional states Source: https://docs.hyperspell.com/api-reference/emotional-state/get-recent-emotional-states https://api.hyperspell.com/openapi.json get /emotional-state/recent Return up to `limit` most recent emotional states, newest first. Optionally filter by ``relationship_id``. # Store emotional state Source: https://docs.hyperspell.com/api-reference/emotional-state/store-emotional-state https://api.hyperspell.com/openapi.json post /emotional-state Store a conversation transcript as emotional state and trigger indexing. Mood extraction happens asynchronously, so the returned record may initially contain a placeholder summary and update when processing completes. # Get Entity Source: https://docs.hyperspell.com/api-reference/entities/get-entity https://api.hyperspell.com/openapi.json get /entities/{entity_id} Fetch a single entity belonging to the current app. Returns 404 when the entity does not exist or is not visible to the app. # List Entities Source: https://docs.hyperspell.com/api-reference/entities/list-entities https://api.hyperspell.com/openapi.json get /entities List entities available to the current app. Results can be filtered by type, status, name, and supporting-document count. Use the returned cursor to retrieve the next page. # Search Entities Source: https://docs.hyperspell.com/api-reference/entities/search-entities https://api.hyperspell.com/openapi.json post /entities/search Search the current app's entities by meaning. # Get query result Source: https://docs.hyperspell.com/api-reference/evaluation/get-query-result https://api.hyperspell.com/openapi.json get /evaluate/query/{query_id} Retrieve the result of a previous query. # List prior queries Source: https://docs.hyperspell.com/api-reference/evaluation/list-prior-queries https://api.hyperspell.com/openapi.json get /evaluate/queries Paginate through all prior queries for the app, newest first. Requests scoped to a user only see that user's queries. App-wide requests see every query in the app and can filter by ``user_id``. # Score a highlight Source: https://docs.hyperspell.com/api-reference/evaluation/score-a-highlight https://api.hyperspell.com/openapi.json post /evaluate/highlight/{highlight_id} Score an individual highlight. # Score a query result Source: https://docs.hyperspell.com/api-reference/evaluation/score-a-query-result https://api.hyperspell.com/openapi.json post /evaluate/query/{query_id} Score the result of a query. # Batch-apply folder policies for a connection Source: https://docs.hyperspell.com/api-reference/folder-policies/batch-apply-folder-policies-for-a-connection https://api.hyperspell.com/openapi.json put /connections/{connection_id}/folder-policies Apply multiple folder-policy changes as one operation. The request is validated as a whole before any changes are applied. It triggers at most one resync and returns the connection's complete policy set. # Create a folder policy for a connection Source: https://docs.hyperspell.com/api-reference/folder-policies/create-a-folder-policy-for-a-connection https://api.hyperspell.com/openapi.json post /connections/{connection_id}/folder-policies Create or update a folder policy for a specific connection. # Delete a folder policy Source: https://docs.hyperspell.com/api-reference/folder-policies/delete-a-folder-policy https://api.hyperspell.com/openapi.json delete /connections/{connection_id}/folder-policies/{policy_id} Delete a folder policy for a specific connection. # List folder policies for a connection Source: https://docs.hyperspell.com/api-reference/folder-policies/list-folder-policies-for-a-connection https://api.hyperspell.com/openapi.json get /connections/{connection_id}/folder-policies List all folder policies for a specific connection. # List folders for a connection Source: https://docs.hyperspell.com/api-reference/folders/list-folders-for-a-connection https://api.hyperspell.com/openapi.json get /connections/{connection_id}/folders List one level of folders from the user's connected source. Returns folders decorated with their explicit folder policy (if any). Use parent_id to drill into subfolders. # Check crawl status for a URL Source: https://docs.hyperspell.com/api-reference/integrations/check-crawl-status-for-a-url https://api.hyperspell.com/openapi.json get /integrations/web_crawler/status Check whether a URL has been crawled and its current indexing status. # Crawl a website for indexed search Source: https://docs.hyperspell.com/api-reference/integrations/crawl-a-website-for-indexed-search https://api.hyperspell.com/openapi.json get /integrations/web_crawler/index Recursively crawl a website to make it available for indexed search. # Link an integration Source: https://docs.hyperspell.com/api-reference/integrations/link-an-integration https://api.hyperspell.com/openapi.json get /integrations/{integration_id}/connect Redirects to the connect URL to link an integration. # List all integrations Source: https://docs.hyperspell.com/api-reference/integrations/list-all-integrations https://api.hyperspell.com/openapi.json get /integrations/list List all integrations for the user. # List available channels Source: https://docs.hyperspell.com/api-reference/integrations/list-available-channels https://api.hyperspell.com/openapi.json get /integrations/{integration_id}/channels List available channels/chats for a connected integration. Also returns the connection's currently selected channel IDs. # Update per-connection user options (e.g., channel allowlist) Source: https://docs.hyperspell.com/api-reference/integrations/update-per-connection-user-options-eg-channel-allowlist https://api.hyperspell.com/openapi.json patch /integrations/{integration_id}/connections/{connection_id} Save per-user options on a connection owned by the authenticated user. Connections outside the current app cannot be updated. # API Introduction Source: https://docs.hyperspell.com/api-reference/introduction Add, connect, and search data with the Hyperspell API ## Welcome Use the Hyperspell API to add memories, connect data sources, and search your users' data using natural language. You can add data directly or let users connect services such as Notion, Gmail, and Slack. ## Authentication Hyperspell API requests use bearer-token authentication. Generate an API key in the [Hyperspell dashboard](https://app.hyperspell.com/api-keys), then send it as `Authorization: Bearer ` with every request. Keys created in the admin API Keys settings act for the whole organization. Keys created from Connect Agents act as the member who created them. See [Permissions](/core/permissions) for what each can see. # Fetch one resource live Source: https://docs.hyperspell.com/api-reference/live/fetch-one-resource-live https://api.hyperspell.com/openapi.json get /live/{source}/resources/{resource_id} Fetch one resource live by id. A single fetch may fan out into several resources (e.g. a thread → its messages); all are returned. Indexing is skipped for live-only sources and explained in the response notes. # List live-queryable sources Source: https://docs.hyperspell.com/api-reference/live/list-live-queryable-sources https://api.hyperspell.com/openapi.json get /live/sources List the user's connected sources and the live capabilities each supports. # List resources from a source live Source: https://docs.hyperspell.com/api-reference/live/list-resources-from-a-source-live https://api.hyperspell.com/openapi.json get /live/{source}/resources Page through a source's resources live (no indexing side effect). The cursor is opaque and integration-defined — pass back the ``next_cursor`` from the previous page verbatim. # Search a source live Source: https://docs.hyperspell.com/api-reference/live/search-a-source-live https://api.hyperspell.com/openapi.json post /live/{source}/search Search a source live for content that may not be indexed yet. With ``index=true``, each hit is queued for indexing (no-op for live-only sources like Google Calendar — see ``notes`` in the response). # Add a memory Source: https://docs.hyperspell.com/api-reference/memories/add-a-memory https://api.hyperspell.com/openapi.json post /memories/add Adds an arbitrary document to the index. This can be any text, email, call transcript, etc. The document will be processed and made available for querying once the processing is complete. # Add multiple memories Source: https://docs.hyperspell.com/api-reference/memories/add-multiple-memories https://api.hyperspell.com/openapi.json post /memories/add/bulk Adds multiple documents to the index in a single request. All items are validated before processing begins. If any item fails validation, the entire batch is rejected with a 422 error detailing which items failed and why. Maximum 100 items per request. Each item follows the same schema as the single-item /memories/add endpoint. # Approve a pending resource Source: https://docs.hyperspell.com/api-reference/memories/approve-a-pending-resource https://api.hyperspell.com/openapi.json post /memories/approve/{source}/{resource_id} Approve a pending-review resource for indexing. The resource moves to ``PENDING`` and is queued for indexing. # Delete memory Source: https://docs.hyperspell.com/api-reference/memories/delete-memory https://api.hyperspell.com/openapi.json delete /memories/delete/{source}/{resource_id} Delete a memory accessible to the authenticated credential. # Get memory Source: https://docs.hyperspell.com/api-reference/memories/get-memory https://api.hyperspell.com/openapi.json get /memories/get/{source}/{resource_id} Retrieve a document by provider and resource ID, including its full hyperdoc tree. # List memories Source: https://docs.hyperspell.com/api-reference/memories/list-memories https://api.hyperspell.com/openapi.json get /memories/list This endpoint allows you to paginate through all documents in the index. You can filter the documents by title, date, metadata, etc. # Query memories Source: https://docs.hyperspell.com/api-reference/memories/query-memories https://api.hyperspell.com/openapi.json post /memories/query Retrieves documents matching the query. # Reject a pending resource Source: https://docs.hyperspell.com/api-reference/memories/reject-a-pending-resource https://api.hyperspell.com/openapi.json post /memories/reject/{source}/{resource_id} Reject a pending-review resource. The resource moves to ``SKIPPED`` and will not be indexed. # Show indexing progress Source: https://docs.hyperspell.com/api-reference/memories/show-indexing-progress https://api.hyperspell.com/openapi.json get /memories/status This endpoint shows the indexing progress of documents, both by provider and total. # Update a memory Source: https://docs.hyperspell.com/api-reference/memories/update-a-memory https://api.hyperspell.com/openapi.json post /memories/update/{source}/{resource_id} Updates an existing document in the index. You can update the text, collection, title, and metadata. The document must already exist or a 404 will be returned. This works for documents from any source (vault, slack, gmail, etc.). To remove a collection, set it to null explicitly. # Upload a file Source: https://docs.hyperspell.com/api-reference/memories/upload-a-file https://api.hyperspell.com/openapi.json post /memories/upload This endpoint will upload a file to the index and return a resource_id. The file will be processed in the background and the memory will be available for querying once the processing is complete. You can use the `resource_id` to query the memory later, and check the status of the memory. The examples upload a local `notes.txt` file for a specific user. Set these environment variables before running them: - `HYPERSPELL_API_URL`: your API base URL, without a trailing slash. Use `https://api.hyperspell.com` for US apps or `https://api.eu.hyperspell.com` for EU apps. For a dedicated instance, use its API URL. - `HYPERSPELL_API_KEY`: your API key. - `HYPERSPELL_USER_ID`: the user who should own the uploaded memory. The `X-As-User` header selects the user when using an app-wide key. With a user-scoped key, omit this header or set it to that key's user ID. ```bash cURL curl --disable --fail-with-body --request POST "${HYPERSPELL_API_URL}/memories/upload" \ --header "Authorization: Bearer $HYPERSPELL_API_KEY" \ --header "X-As-User: $HYPERSPELL_USER_ID" \ --form 'file=@notes.txt;type=text/plain' \ --form 'metadata={"collection":"project-notes"}' ``` ```python Python import json import os import requests with open("notes.txt", "rb") as file: response = requests.post( f"{os.environ['HYPERSPELL_API_URL']}/memories/upload", headers={ "Authorization": f"Bearer {os.environ['HYPERSPELL_API_KEY']}", "X-As-User": os.environ["HYPERSPELL_USER_ID"], }, files={"file": ("notes.txt", file, "text/plain")}, data={"metadata": json.dumps({"collection": "project-notes"})}, ) response.raise_for_status() print(response.json()) ``` ```javascript JavaScript (Node.js) // Node.js 20+ (save as upload.mjs). import { readFile } from "node:fs/promises"; const form = new FormData(); form.append("file", new Blob([await readFile("notes.txt")], { type: "text/plain" }), "notes.txt"); form.append("metadata", JSON.stringify({ collection: "project-notes" })); const response = await fetch(`${process.env.HYPERSPELL_API_URL}/memories/upload`, { method: "POST", headers: { Authorization: `Bearer ${process.env.HYPERSPELL_API_KEY}`, "X-As-User": process.env.HYPERSPELL_USER_ID, }, body: form, }); if (!response.ok) { throw new Error(`Upload failed (${response.status}): ${await response.text()}`); } console.log(await response.json()); ``` # Ingest messages Source: https://docs.hyperspell.com/api-reference/messages/ingest-messages https://api.hyperspell.com/openapi.json post /messages Ingest real-time messages for immediate full-text search. # Issue a one-time exchange code for the current user JWT Source: https://docs.hyperspell.com/api-reference/oauth/issue-a-one-time-exchange-code-for-the-current-user-jwt https://api.hyperspell.com/openapi.json post /oauth/token-exchange/issue Exchange a user token for a short-lived, one-time connection code. Use the returned code to start Hyperspell Connect without placing the user token in a browser URL. Only user tokens are accepted. # Add an agent trace Source: https://docs.hyperspell.com/api-reference/traces/add-an-agent-trace https://api.hyperspell.com/openapi.json post /trace/add Add an agent trace/transcript to the index. Accepts traces as a string in Hyperdoc format (native), Vercel AI SDK format, or OpenClaw JSONL format. The format is auto-detected if not specified. **Hyperdoc format** (JSON array, snake_case with type discriminators): ```json {"history": "[{\"type\": \"trace_message\", \"role\": \"user\", \"text\": \"Hello\"}]"} ``` **Vercel AI SDK format** (JSON array, camelCase): ```json {"history": "[{\"role\": \"user\", \"content\": \"Hello\"}]"} ``` **OpenClaw JSONL format** (newline-delimited JSON): ```json {"history": "{\"type\":\"session\",\"id\":\"abc\"}\n{\"type\":\"message\",\"message\":{\"role\":\"user\",...}}"} ``` # List users Source: https://docs.hyperspell.com/api-reference/users/list-users https://api.hyperspell.com/openapi.json get /users List the app's users — distinct document owners with document counts. Each ``user_id`` is valid for the ``X-As-User`` header. ``display_name`` is included when available. Requires an app-scoped credential; user-scoped credentials cannot enumerate other users. # List vaults Source: https://docs.hyperspell.com/api-reference/vault/list-vaults https://api.hyperspell.com/openapi.json get /vault/list This endpoint lists all collections, and how many documents are in each collection. All documents that do not have a collection assigned are in the `null` collection. # Hyperspell Documentation Source: https://docs.hyperspell.com/core/introduction Set up your company brain and give your people and AI agents shared context. Hyperspell is your company's brain: a knowledge layer connecting the goals, decisions, processes, and resources your company already has to a growing fleet of AI agents. Set up your company brain in less than 5 minutes. Learn how to connect your AI agents to your company brain. Understand how Hyperspell handles permissions and access control. Learn more about Hyperspell and the concepts behind it. # Permissions Source: https://docs.hyperspell.com/core/permissions How Hyperspell decides who can see what, from the moment data arrives to the moment an agent answers. The most useful knowledge in a company lives in places not everyone should see: inboxes, direct messages, call notes. A brain that ignores this either leaks or gets switched off. Hyperspell's permission model is built to let people search everything the company knows without anything traveling further than it should. ## One brain, many views Everything is stored once, in one company brain. There are no separate personal or team copies. Each document carries a list of who may see it, and every question is answered from the documents the asker is allowed to see. Two people asking the same question can get different answers, because they see different slices of the same brain. Agents work the same way. When you connect Claude, ChatGPT, or a coding agent, it acts as you and sees only what you see. ## Shared and personal data Where a document comes from decides who sees it by default. Every integration is set up in one of two ways, and some tools support both. | | Shared integration | Personal integration | | ---------------------------- | ------------------------------------------------------ | ------------------------------------------------- | | Who connects it | An admin, once, with an API key or service account | Each person, with their own login | | Typical tools | Knowledge bases, project trackers, CRMs, shared drives | Email, calendars, direct messages, personal notes | | Who sees the data by default | Everyone in the organization | Only the person who connected it | Admins pick the mode for each tool during setup and can change it later in Settings. The choice matters because Hyperspell does not copy the permission lists of the source tools. A Google Drive folder that only three people could open in Drive becomes visible to the whole organization once it arrives through a shared integration. So the rule of thumb is simple: set up a tool as shared only when everything it contains may be seen by everyone. For tools where that is not true, use personal connections, and rely on [content rules](/advanced/content-rules) to share the parts that should travel. Today a document is visible either to the person who connected it or to everyone in the organization. Narrower audiences, such as a single team, are not yet available. Meeting-notes tools are the one exception: Gong, Fireflies, Fathom, Fellow, and Granola. Recordings often include one-on-ones, so a shared connection for these tools does not make its content visible to everyone automatically. If you want a company-wide meeting corpus, [tell us](mailto:hello@hyperspell.com) when you connect it and we will turn that on. ## How content rules change the defaults The defaults above are a starting point. [Content rules](/advanced/content-rules) let admins adjust them based on what a document says, rather than where it came from. ## When people leave When a member is removed from the organization: * Their identity and all their access are removed. Their connected agents stop working. * Documents only they could see are deleted. * Documents that were shared with the organization, or that other people also brought in, stay in the brain. The company keeps what the company paid for, and the person's private data does not linger. Disconnecting a single personal integration works the same way on a smaller scale. The content that integration brought in is removed, unless the same document also arrived through someone else's connection or a shared one. ## Where data is stored Data is stored in the region you chose when you created your account, either the United States or the European Union, and is never copied between regions. See [Regions and data residency](/resources/data-residency) for what runs where, and [Security](/resources/security) for encryption, backups, and our operational practices. ## In short * Everything is stored once. Access is decided per document, per person. * Shared integrations are visible to everyone. Personal integrations are private to the person who connected them. * Hyperspell does not mirror the source tool's permissions. Choose shared only for content the whole company may see. * Filter rules hold content back. Sharing rules offer personal content to the team, with the owner's consent. Filters always win. * Agents inherit the permissions of the person who connected them. * Every answer shows its sources. # Setup Source: https://docs.hyperspell.com/core/setup Set up your company brain, connect your tools, and give your first agent access. About five minutes, no code. Hyperspell turns the tools your company already uses into one searchable brain that people and AI agents can ask questions of. Setting it up is a short guided flow in the dashboard. This page walks through each step and explains the choices you make along the way. ## Before you start You need a work email address to sign up. Depending on which tools you want to connect, you may also need Admin access to the tools you plan to connect as shared integrations, since those use an API key or a service account rather than a personal login. The [integration pages](/integrations/overview) list what each tool needs. ## Set up the brain Sign up at [app.hyperspell.com](https://app.hyperspell.com). The first person from a company to sign up becomes its admin and goes through the setup flow below. People you invite later get a shorter version, described [further down](#for-invited-teammates). If your company needs data to stay in the European Union, sign up at [app.eu.hyperspell.com](https://app.eu.hyperspell.com) instead of the default US region. Everything else on this page is the same. See [Regions and data residency](/resources/data-residency). Enter your organization's name and pick a company size. The name is what your teammates will see when they join. You can change it later in Settings. Pick the data sources that should feed the brain. Tools are grouped by category, and a search box helps you find one quickly. Nothing is selected for you, and you need at least one tool to continue. Do not worry about being complete. You can add or remove tools at any time in Settings. A good first set is the two or three tools where most of your company's knowledge lives: usually a chat tool, a document store, and a project tracker. This is the step that decides who can see what. For each tool you picked, you choose how it connects: * A shared integration uses one credential for the whole company, usually an API key or a service account that an admin sets up once. Everything it brings in is visible to everyone in your organization. * A personal integration is connected by each teammate with their own login. What it brings in is private to that person by default. Some tools support both. Email and calendars only support personal connections, so their checkbox is fixed. We recommend shared integrations wherever a tool supports them, because the data becomes useful to the whole team immediately and nobody has to connect anything themselves. Choose shared only for tools whose content the whole company may see. Hyperspell does not copy the source tool's own permission settings, so a shared Google Drive is visible to everyone in your organization even if the folder was restricted in Drive. [Permissions](/core/permissions) explains this in detail, and [content rules](/advanced/content-rules) let you hold back specific categories of content. Meeting-notes tools are the one exception: Gong, Fireflies, Fathom, Fellow, and Granola. Recordings often include one-on-ones, so a shared connection for these tools does not make its content visible to everyone automatically. If you want a company-wide meeting corpus, [tell us](mailto:hello@hyperspell.com) when you connect it and we will turn that on. This step appears only if you set up at least one shared integration. For each one, click Connect and follow the instructions for that tool. Most ask for an API key or a service account file, and the [integration pages](/integrations/overview) show exactly where to find them. You can continue without connecting everything. Anything you skip stays listed under Settings, where you can connect it later. For each personal integration, click Connect and sign in with your own account. The sign-in opens in a popup, and the row updates when you return. Your teammates do the same for themselves when they join. Some tools let you narrow what gets indexed, for example which Slack channels or which Drive folders. Those pickers are available in Settings after setup. Give your AI agents access to the brain. Each row opens short instructions: * Claude, for Claude on the web, Claude Desktop, and Cowork. * ChatGPT, on the web and desktop. * MCP clients, for Claude Code, Codex, Cursor, and any other agent that speaks the Model Context Protocol. * CLI, a command line tool that keeps a Markdown copy of the brain on your computer for coding agents. * Slack, a workspace assistant you can mention in channels. This row appears once your Slack integration is connected. You can skip this step with Set up later and come back to it from Settings at any time. [Connecting agents](/agents/overview) covers each option in depth. Add teammates by email. Each invitee can be marked as an admin, which lets them manage integrations, content rules, members, and API keys. Everyone else joins as a member and can connect their own tools and agents. Click Finish to complete setup, or Skip for now to invite people later from Settings. Invitations go out by email, and each person is guided through connecting their own accounts when they accept. ## What happens next As soon as a tool is connected, Hyperspell starts reading from it. The first documents show up within a few minutes. Tools with a long history, such as a busy Slack workspace or years of email, take longer to index fully because the source tools limit how fast anyone can read from them. You do not have to wait for indexing to finish before asking questions. The Home page of the dashboard shows the newest memories as they arrive, so you can watch the brain fill up. Each integration has its own page listing the documents it brought in. The brain keeps itself up to date from then on. New messages, edited documents, and closed deals flow in automatically. ## For invited teammates People you invite see a shorter version of the setup flow, since the organization and its integrations already exist: 1. A welcome screen for your organization's brain. 2. Connect your personal tools. Each member signs in to the personal integrations the admin configured. Shared integrations need nothing from them. 3. A summary of what is already in the brain: how many memories, from how many documents, across how many integrations. 4. Connect your agents. The same options as above, so each person can connect their own Claude, ChatGPT, or coding agent. Every agent a person connects sees exactly what that person is allowed to see. ## Next steps Set up Claude, ChatGPT, coding agents, or the command line tool. Who sees what, and how shared and personal data differ. Keep sensitive categories out of the brain, and share personal content that the team should have. Narrow what gets indexed, add tools, and manage members. # ClickUp Source: https://docs.hyperspell.com/integrations/all/clickup Search through ClickUp tasks and projects # Overview The ClickUp integration allows you to search through your ClickUp tasks and projects. It supports both and . ## Authentication The ClickUp integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (API key) Each user connects their own ClickUp account by entering a ClickUp Personal API Token in Unified.to's hosted auth UI, available in Hyperspell as a personal connection without any additional setup. ### Shared connection An app admin can instead register a single **shared connection** using a service-account credential. Its data is synced once and made available to everyone in your app — no per-user connection required. A shared ClickUp connection needs the following field: A ClickUp Personal API Token with access to the workspaces you want to index. # Coda Source: https://docs.hyperspell.com/integrations/all/coda Search through Coda docs and pages # Overview The Coda integration allows you to search through your Coda docs and pages. It supports . ## Authentication The Coda integration is available in Hyperspell as a personal connection without any additional setup. Users connect by entering their Coda API token in Unified.to's hosted auth UI. ## Search Options The Coda integration does not support any custom search options. # Confluence Source: https://docs.hyperspell.com/integrations/all/confluence Search through Confluence pages and spaces # Overview The Confluence integration allows you to search through your Confluence pages and spaces. It supports . ## Authentication The Confluence integration requires an OAuth connection, and is available in Hyperspell as a personal connection without any additional setup. Note that during the OAuth flow, users will be asked to select which Confluence site they would like to give access to. ## Search Options The Confluence integration does not support any custom search options. # Dropbox Source: https://docs.hyperspell.com/integrations/all/dropbox Search through Dropbox files and folders # Overview The Dropbox integration allows you to search through your Dropbox files and folders. It supports both and . ## Authentication The Dropbox integration requires an OAuth connection, and is available in Hyperspell as a personal connection without any additional setup. Note that during the OAuth flow, users will be asked to select which Dropbox account they would like to give access to. # Fathom Source: https://docs.hyperspell.com/integrations/all/fathom Search through Fathom meeting recordings and transcripts # Overview The Fathom integration allows you to search through your Fathom meeting recordings and transcripts. It supports . ## Authentication The Fathom integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (API key) Each user connects their own Fathom account by entering their Fathom API key in Unified.to's hosted auth UI, available in Hyperspell as a personal connection without any additional setup. ### Shared connection An app admin can instead register a single **shared connection** using a service-account credential. Its data is synced once and made available to everyone in your app — no per-user connection required. A shared Fathom connection needs the following field: A Fathom API key with read access to the meetings you want to index. ## Search Options The Fathom integration does not support any custom search options. # Fellow Source: https://docs.hyperspell.com/integrations/all/fellow Search through Fellow meeting notes and transcripts # Overview The Fellow integration allows you to search through your Fellow meeting notes and transcripts. It supports . ## Authentication The Fellow integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (API key) Each user connects their own Fellow account by entering their Fellow workspace subdomain and API key in Unified.to's hosted auth UI, available in Hyperspell as a personal connection without any additional setup. ### Shared connection An app admin can instead register a single **shared connection** using a service-account credential. Its data is synced once and made available to everyone in your app — no per-user connection required. A shared Fellow connection needs the following fields: Your Fellow workspace subdomain — the `{subdomain}` in `https://{subdomain}.fellow.app`. A Fellow API key with read access to the meetings you want to index. ## Search Options The Fellow integration does not support any custom search options. # Fireflies Source: https://docs.hyperspell.com/integrations/all/fireflies Search through Fireflies meeting recordings and transcripts # Overview The Fireflies integration allows you to search through your Fireflies meeting recordings and transcripts. It supports . ## Authentication The Fireflies integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (API key) Each user connects their own Fireflies account by entering their Fireflies API key in Unified.to's hosted auth UI, available in Hyperspell as a personal connection without any additional setup. ### Shared connection An app admin can instead register a single **shared connection** using a service-account credential. Its data is synced once and made available to everyone in your app — no per-user connection required. A shared Fireflies connection needs the following field: A Fireflies API key with read access to the meetings you want to index. ## Search Options The Fireflies integration does not support any custom search options. # GitHub Source: https://docs.hyperspell.com/integrations/all/github Search through GitHub repositories and code # Overview The GitHub integration allows you to search through GitHub repositories and code. It supports both and . ## Authentication The GitHub integration requires an OAuth connection, and is available in Hyperspell as a personal connection without any additional setup. Note that during the OAuth flow, users will be asked to select which repositories they would like to give access to. # GitLab Source: https://docs.hyperspell.com/integrations/all/gitlab Search through GitLab repositories and code # Overview The GitLab integration allows you to search through GitLab repositories and code. It supports both and . ## Authentication The GitLab integration requires an OAuth connection, and is available in Hyperspell as a personal connection without any additional setup. Note that during the OAuth flow, users will be asked to select which repositories they would like to give access to. # Gong Source: https://docs.hyperspell.com/integrations/all/gong Search through Gong call recordings and transcripts # Overview The Gong integration allows you to search through your Gong call recordings and transcripts. It supports . ## Authentication The Gong integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (API key) Each user connects their own Gong account by entering their Gong credentials in Unified.to's hosted auth UI, available in Hyperspell as a personal connection without any additional setup. ### Shared connection An app admin can instead register a single **shared connection** using service-account credentials. Its data is synced once and made available to everyone in your app — no per-user connection required. A shared Gong connection needs the following fields: Your Gong API access key. The access key secret that pairs with the access key above. Your Gong domain, used to build the API base URL (e.g. `https://{domain}.api.gong.io`). ## Search Options The Gong integration does not support any custom search options. # Google Calendar Source: https://docs.hyperspell.com/integrations/all/google_calendar Answer schedule questions from Google Calendar, read live at the moment someone asks # Overview The Google Calendar integration answers schedule questions such as "what's on my calendar on Thursday?", "when do I next meet Priya?", or "who is in the planning review tomorrow?". It supports only. Live only means Hyperspell reads events from Google Calendar at the moment a question is asked and does not store them. Calendars change too often for a stored copy to stay truthful, and a schedule answer that is a day old is worse than no answer. The trade-off is that calendar events never become part of the company brain: they are not indexed, do not appear in the memories browser, and content rules do not apply to them. ## Authentication Google Calendar is a personal integration. Each person connects their own Google account through an OAuth sign-in, and Hyperspell asks for read-only access to their calendars and events. There is no shared connection, because a calendar belongs to a person rather than to the company. Events are fetched with the connecting person's own access at query time, so each person, and every agent they connect, sees only their own calendar. Nothing about anyone's schedule is visible to colleagues through the brain. ### Dealing with Google access issues If, while connecting to a Google Service using OAuth, you get an error about "This app is blocked", you need an admin to unblock it. This app is blocked Go to [admin.google.com](https://admin.google.com) Go to Security → Access and data control → API controls Click Manage Third-Party App Access (under "App access control") Click Add app → OAuth App Name Or Client ID Paste the client ID: ``` 918787848500-ghmdrurivrpf8s48btbmfnkfglo61il8.apps.googleusercontent.com ``` This is the client ID of the Hyperspell OAuth app. Select the app in the results, choose All users (or the relevant OU/group), click Continue Set access to Trusted ("Can access all Google services") → Configure / Save ## What a query returns When someone asks a schedule question, Hyperspell lists the events in the relevant time window and returns each one with: * The title, start, and end. * The location and the meeting link, such as a Google Meet link. * The organizer and attendees. * The event description. A few details worth knowing: * If the question names a date or range, that is the window Hyperspell searches. A question without dates, such as "what is on my calendar?", covers the past seven days and the next sixty, up to 100 events sorted by start time. * Recurring events come back as the specific occurrence inside the window, not the series. Asking about Thursday returns Thursday's instance of the weekly all-hands, with Thursday's date. * Events without a start time are skipped, since they cannot answer a schedule question. ## Search options The Google Calendar integration does not support any custom search options. ## Limitations * Free and busy questions such as "is Priya free at 3pm?" are not supported yet. The brain sees events, not availability. * Because nothing is stored, Hyperspell cannot answer questions about past attendance beyond what a live listing of the requested window shows. # Google Drive Source: https://docs.hyperspell.com/integrations/all/google_drive Search through Google Drive files and folders # Overview The Google Drive integration allows you to search through your Google Drive files and folders. Google Docs, Sheets, and Slides are indexed through this integration — there is no separate connection for them. It supports both and . ## Authentication The Google Drive integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (OAuth) Each user connects their own Google Drive account through an OAuth flow, available in Hyperspell as a personal connection without any additional setup. During the OAuth flow, users select which Google Drive folders they want to give access to. ### Shared connection An app admin can instead register a single **shared connection** using a Google Cloud service-account key. Its data is synced once and made available to everyone in your app — no per-user OAuth required. The corpus is exactly what you share with the service account's email address (Shared Drives it belongs to, plus any directly-shared files and folders). To create the service account and share content with it: Navigate to Google Cloud Project Creation and create a new project. Go to Drive API page and enable the Drive API for your project. Visit Service Accounts page and select Create service account. Set the Service Account ID to hyperspell and click Create and Close. Click on the service account you just created (e.g. hyperspell@\.iam.gserviceaccount.com) and copy its email address — you'll need it later. Go to the Keys tab, click Add Key, and choose JSON. This will download a JSON key file. Creating a JSON private key for the hyperspell service account Extract the private key from the downloaded JSON file with the following terminal command: ```bash theme={null} plutil -extract private_key raw -o - .json ``` Go to Google Drive and find the content you want to share (e.g., a shared drive). Click the triple dots and choose Manage members (or Share). Sharing a Google Drive shared drive with the hyperspell service account email Enter the service account's email address and click Done. Then register the shared connection with the following fields: The service account's email address, copied in step 5. The private key extracted in step 7. ### Dealing with Google access issues If, while connecting to a Google Service using OAuth, you get an error about "This app is blocked", you need an admin to unblock it. This app is blocked Go to [admin.google.com](https://admin.google.com) Go to Security → Access and data control → API controls Click Manage Third-Party App Access (under "App access control") Click Add app → OAuth App Name Or Client ID Paste the client ID: ``` 918787848500-ghmdrurivrpf8s48btbmfnkfglo61il8.apps.googleusercontent.com ``` This is the client ID of the Hyperspell OAuth app. Select the app in the results, choose All users (or the relevant OU/group), click Continue Set access to Trusted ("Can access all Google services") → Configure / Save # Gmail Source: https://docs.hyperspell.com/integrations/all/google_mail Query emails from Gmail # Overview The Gmail integration allows you to query emails from Gmail. It supports both and . ## Authentication The Gmail integration requires an OAuth connection, and is available in Hyperspell as a personal connection without any additional setup. Note that during the OAuth flow, users will be asked to choose which Google account they would like to connect. ### Dealing with Google access issues If, while connecting to a Google Service using OAuth, you get an error about "This app is blocked", you need an admin to unblock it. This app is blocked Go to [admin.google.com](https://admin.google.com) Go to Security → Access and data control → API controls Click Manage Third-Party App Access (under "App access control") Click Add app → OAuth App Name Or Client ID Paste the client ID: ``` 918787848500-ghmdrurivrpf8s48btbmfnkfglo61il8.apps.googleusercontent.com ``` This is the client ID of the Hyperspell OAuth app. Select the app in the results, choose All users (or the relevant OU/group), click Continue Set access to Trusted ("Can access all Google services") → Configure / Save # Granola Source: https://docs.hyperspell.com/integrations/all/granola Search through Granola meeting notes and transcripts # Overview The Granola integration allows you to search through your Granola meeting notes and transcripts. It supports . ## Authentication The Granola integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (API key) Each user connects their own Granola account by entering their Granola API key in Unified.to's hosted auth UI, available in Hyperspell as a personal connection without any additional setup. ### Shared connection An app admin can instead register a single **shared connection** using a Granola **Workspace API key**. Its data is synced once and made available to everyone in your app — no per-user connection required. To create the Workspace API key: 1. Open the Granola app and navigate to **Settings**. 2. Under **Connectors**, choose **Workspace API keys**: Granola settings showing Personal API keys and Workspace API keys options 3. Click **Create new key** and choose no expiration date. Then register the shared connection with the following field: Your Granola Workspace API key. ## Search Options The Granola integration does not support any custom search options. # HubSpot Source: https://docs.hyperspell.com/integrations/all/hubspot Search through HubSpot contacts, companies, and deals # Overview The HubSpot integration allows you to search through HubSpot contacts, companies, and deals. It supports both and . ## Authentication The HubSpot integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (OAuth) Each user connects their own HubSpot account through an OAuth flow, available in Hyperspell as a personal connection without any additional setup. During the OAuth flow, users select which HubSpot objects they want to give access to. ### Shared connection An app admin can instead register a single **shared connection** using a HubSpot **Service Key**. Its data is synced once and made available to everyone in your app — no per-user OAuth required. To create the Service Key: 1. Navigate to [https://app.hubspot.com](https://app.hubspot.com), select **Development** in the side bar, and click **Keys**. Creating a HubSpot Service Key with the crm.objects contacts, companies, and deals read scopes 2. Click **Create Service Key**. 3. Add the following scopes: * `crm.objects.contacts.read` * `crm.objects.companies.read` * `crm.objects.deals.read` 4. Click **Create**. Creating a HubSpot Service Key with the crm.objects contacts, companies, and deals read scopes Then register the shared connection with the following field: Your HubSpot Service Key. # Jira Source: https://docs.hyperspell.com/integrations/all/jira Search through Jira issues and projects # Overview The Jira integration allows you to search through your Jira issues and projects. It supports both and . ## Authentication The Jira integration requires an OAuth connection, and is available in Hyperspell as a personal connection without any additional setup. Note that during the OAuth flow, users will be asked to select which Jira projects they would like to give access to. # Lightfield Source: https://docs.hyperspell.com/integrations/all/lightfield Search through Lightfield accounts, contacts, and opportunities # Overview The Lightfield integration lets you search across Lightfield accounts (companies), contacts, and opportunities (deals) by default. Activities (notes / calls / meetings / tasks) are available as an opt-in. It supports both and . ## Authentication The Lightfield integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (API key) Each user connects their own Lightfield account by entering their Lightfield API key in Unified.to's hosted auth UI, available in Hyperspell as a personal connection without any additional setup. ### Shared connection An app admin can instead register a single **shared connection** using a service-account credential. Its data is synced once and made available to everyone in your app — no per-user connection required. A shared Lightfield connection needs the following field: A Lightfield API key with read access to the records you want to index. ## Configuration Which Lightfield object types are synced is controlled by the `object_types` index option, set per app rather than during the connection flow. The default — `contacts,companies,deals` — covers the most common search use cases. To also index activities (notes, calls, meetings, tasks), include `events` in the `object_types` value. # Linear Source: https://docs.hyperspell.com/integrations/all/linear Search through Linear issues and projects # Overview The Linear integration allows you to search through your Linear issues and projects. It supports both and . ## Authentication The Linear integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (OAuth) Each user connects their own Linear account through an OAuth flow, available in Hyperspell as a personal connection without any additional setup. During the OAuth flow, users select which Linear workspace they want to give access to. ### Shared connection An app admin can instead register a single **shared connection** using a service-account credential. Its data is synced once and made available to everyone in your app — no per-user OAuth required. A shared Linear connection needs the following field: A Linear API key with read access to the workspaces you want to index. # Notion Source: https://docs.hyperspell.com/integrations/all/notion Query Notion pages and databases # Overview The Notion integration allows you to query and index Notion pages and databases. It supports both and . ## Authentication The Notion integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (OAuth) Each user connects their own Notion account through an OAuth flow, available in Hyperspell as a personal connection without any additional setup. During the OAuth flow, users select which pages in their Notion workspace they want to give access to. ### Shared connection An app admin can instead register a single **shared connection** using a Notion **Access Token**. Its data is synced once and made available to everyone in your app — no per-user OAuth required. To create the Access Token: 1. Go to [https://app.notion.com/developers/connections](https://app.notion.com/developers/connections). 2. Click **New connection**, enter a name, select **Access token** as the authentication method, then click **Create connection**: Creating a new Notion connection with the Access token authentication method selected 3. Open the **Content access** tab and click **Add pages & databases** to select which pages the connection can access. We recommend selecting your team workspace — all subpages are added automatically: Notion Content access tab showing the option to add pages and databases 4. Back in the **Configuration** tab, copy the **Access Token**. Then register the shared connection with the following field: Your Notion Access Token. ## Search Options The Notion integration does not support any custom search options. ## Resources The Notion integration returns `Document` resources: The unique identifier of the page or database The provider that fetched the document, which is `notion` if this integration is used to query or index it. The title of the page A summary of the document that can be fed directly into LLMs. When retrieved from the `/query` endpoint, this may summarize only the sections of the document returned as highlights (i.e., parts relevant to your query). Otherwise, it will summarize the entire document. A structured representation of the page's content. This field is only returned if the resource is returned from the `/documents/get` endpoint. If the website is returned from the `/query` endpoint, this field will be empty and the `highlights` field will contain the relevant sections of the website. A list of highlights from the page relevant to the query. This field is only returned if the resource is returned from the `/query` endpoint. # Microsoft Outlook Source: https://docs.hyperspell.com/integrations/all/outlook Search through Microsoft Outlook email conversations # Overview The Microsoft Outlook integration indexes email conversations for . Calendar events are not included in this integration. ## Authentication The Microsoft Outlook integration requires an OAuth connection, and is available in Hyperspell as a personal connection without any additional setup. Note that during the OAuth flow, users will be asked to select which Outlook account they would like to give access to. # Pylon Source: https://docs.hyperspell.com/integrations/all/pylon Search through Pylon support tickets # Overview The Pylon integration allows you to search through your Pylon support tickets, including their notes. It supports . ## Authentication The Pylon integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (API key) Each user connects their own Pylon account by entering their Pylon API key in Unified.to's hosted auth UI, available in Hyperspell as a personal connection without any additional setup. ### Shared connection An app admin can instead register a single **shared connection** using a service-account credential. Its data is synced once and made available to everyone in your app — no per-user connection required. A shared Pylon connection needs the following field: A Pylon API key with read access to the tickets you want to index. ## Search Options The Pylon integration does not support any custom search options. # Salesforce Source: https://docs.hyperspell.com/integrations/all/salesforce Search through Salesforce records and data # Overview The Salesforce integration allows you to search through Salesforce records and data. It supports both and . ## Authentication The Salesforce integration can be set up as a **personal connection** or as a **shared connection**. ### Personal connection (OAuth) Each user connects their own Salesforce account through an OAuth flow, available in Hyperspell as a personal connection without any additional setup. During the OAuth flow, users select which Salesforce objects they want to give access to. ### Shared connection An app admin can instead register a single **shared connection** using a service-account credential. Its data is synced once and made available to everyone in your app — no per-user OAuth required. A shared Salesforce connection needs the following fields: Your Salesforce connected-app Client ID (Consumer Key). The Client Secret (Consumer Secret) that pairs with the Client ID above. # Slack Source: https://docs.hyperspell.com/integrations/all/slack Query Slack conversations and messages # Overview The Slack integration allows you to query and index Slack conversations and messages. It only supports . ## Authentication The Slack integration requires an OAuth connection, and is available in Hyperspell as a personal connection without any additional setup. ## Search Options The Slack integration does not support any custom search options. ## Resources The Slack integration returns `Conversation` resources: The unique identifier of the conversation, provided by Slack. The provider that fetched the conversation, which is `slack` if this integration is used to query or index it. A summary of the conversation that can be fed directly into LLMs. When retrieved from the `/query` endpoint, this may summarize only the parts of the conversation returned as highlights (i.e., parts relevant to your query). Otherwise, it will summarize the entire conversation. A list of people in this conversation A list of Messages in this conversation. This field is only returned if the resource is returned from the `/documents/get` endpoint. If the conversation is returned from the `/query` endpoint, this field will be empty and the `highlights` field will contain the relevant messages of the conversation. A list of highlights from the conversation relevant to the query. This field is only returned if the resource is returned from the `/query` endpoint. # Vault Source: https://docs.hyperspell.com/integrations/all/vault Upload and search through memories manually added to Hyperspell # Overview The Vault integration allows you to upload and search through memories manually added to Hyperspell. It only supports . ## Authentication The Vault integration does not require any authentication and is available to all users. ## Search Options Following options are available for the `options` parameter of `vault`: The collection to search through. If not provided, all collections will be searched. ## Resources The Vault integration returns `Document` resources: The unique identifier of the page or database The provider that fetched the document, which is set when the document is uploaded. The title of the page A summary of the document that can be fed directly into LLMs. When retrieved from the `/query` endpoint, this may summarize only the sections of the document returned as highlights (i.e., parts relevant to your query). Otherwise, it will summarize the entire document. A structured representation of the page's content. This field is only returned if the resource is returned from the `/documents/get` endpoint. If the website is returned from the `/query` endpoint, this field will be empty and the `highlights` field will contain the relevant sections of the website. A list of highlights from the page relevant to the query. This field is only returned if the resource is returned from the `/query` endpoint. # Web Crawler Source: https://docs.hyperspell.com/integrations/all/web_crawler Get answers from websites # Overview The Web Crawler integration allows you to extract information from websites. While the integration offers both and , we highly recommend indexing a website first before you query it: larger websites can take several minutes to index, and the live search will be limited to the front page. ## Authentication The Web Crawler integration does not require any authentication and is available to all users. ## Search Options Following options are available for the `options` parameter of `web_crawler`: The URL of the website to crawl. Trailing slashes are ignored. The maximum depth of the website to crawl. 0 means only the root page will be queried, 1 means the root page and all pages linked from it will be queried, and so on. ## Resources The Web Crawler integration returns `Website` resources: The unique identifier of the website, typically the URL. The provider that fetched the website, which is `web_crawler` if this integration is used to query or index it. The URL of the website The title of the website, extracted from the HTML title tag. The description of the website, extracted from the HTML meta description tag or Open Graph descriptions. The image URL of the website, extracted from the HTML meta description tag or Open Graph images. The language of the website, extracted from the HTML meta language tag. The favicon URL of the website, extracted from the HTML head. A summary of the document that can be fed directly into LLMs. When retrieved from the `/query` endpoint, this may summarize only the sections of the document returned as highlights (i.e., parts relevant to your query). Otherwise, it will summarize the entire document. A structured representation of the website's content. This field is only returned if the resource is returned from the `/documents/get` endpoint. If the website is returned from the `/query` endpoint, this field will be empty and the `highlights` field will contain the relevant sections of the website. A list of highlights from the website relevant to the query. This field is only returned if the resource is returned from the `/query` endpoint. ## Additional Endpoints ### Index a website before querying it `GET /integrations/web_crawler/index` Call this endpoint to index a website for indexed search. The website will be crawled recursively and added to the search index. The maximum depth of the website to crawl. 0 means only the root page will be queried, 1 means the root page and all pages linked from it will be queried, and so on. The maximum number of pages to crawl. # Available Integrations Source: https://docs.hyperspell.com/integrations/overview ## Popular Integrations ## All Integrations # Changelog Source: https://docs.hyperspell.com/resources/changelog New updates and improvements *** `GET /memories/list` now returns document **envelopes** by default — `title`, `source`, `status`, `collection`, `metadata` and the timestamps, plus the document frame under `document` with its body (`children`) omitted. Listing a source whose documents are large is dramatically faster as a result: a single conversation document can hold an entire channel's message history, and a page of those took tens of seconds to return. Pass `include_body=true` to get the full document tree back, and keep `size` small when you do. To read one document in full, use `GET /memories/get/{source}/{resource_id}`, which is unchanged. Query responses now distinguish *why* a requested source is missing from the results. A source that matched nothing keeps the existing `NoResultsForSource` warning; a source whose results were merely outranked by other sources now reports a new `SourceResultsOutranked` warning instead, including how many candidate results it had. The `errors[]` shape is unchanged — this is an additive new error code, so existing integrations keep working. Connecting Claude and ChatGPT on the web is now first-class. The onboarding "Connect your agents" step has one-click walkthroughs for both, and the [MCP docs](/agents/mcp) cover the custom-connector OAuth flow for each — point either client at `https://api.hyperspell.com/mcp` and log in with your Hyperspell account, no API key needed. (ChatGPT's OAuth connector registration is rolling out.) You can now add Hyperspell to Claude as a [custom connector](/agents/mcp) — point Claude at `https://api.hyperspell.com/mcp` and log in with your Hyperspell dashboard account. No API key needed, and the connection is scoped to you. Hyperspell Connect now supports a `providers` parameter to filter which integrations are shown. This lets you show only specific integrations to your users (e.g., `?providers=slack,notion`). You can now add multiple memories in a single request using the new `/memories/add/bulk` endpoint. You can now add custom metadata to your memories, and query them in your queries. The API now supports evaluating queries and highlights. You can now use Webhooks to get notified when new memories are created. You can now customize Hyperspell Connect page to match your app's branding. The [Web Crawler](/integrations/all/web_crawler) now lets you specify the maximum depth and number of pages to crawl when you index a website. The new `/auth/delete` endpoint deletes all user data, including all memories and stored connections. This can't be undone. Improved file upload handling and made sure that memories created from files also have a `title` attribute. The `/memories/list` endpoint now also returns the title of each memory. Added an new endpoint to delete specific memories. Also lets you weight data sources in your queries, so you can influence which documents are used to answer a query. Consolidated our offerings and API endpoints. The old endpoints under `/documents` are now under `/memories`. Additionally, you can now choose which model to use to answer queries — we default to Llama 3.1 8B for speed and efficiency, but more complex queries can benefit from a different model Added a native integration with [AgentStack](https://agentstack.sh) The [MCP server](/agents/mcp) got an upgrade! You can now use it to query your data from any MCP client. You can now run it directly with `npx` or via a client like [Claude Desktop](https://www.anthropic.com/products/claude-desktop). You can now use the `X-As-User` header to query data as a specific user while using an API key as your authentication. This saves a round trip to the server to generate a user token. We rolled out our new infrastructure that dramatically reduces the latency of our query endpoint. Most queries against indexed data should now be less than 250ms (plus extra time if you request an answer). We heard that our web app was a bit slow, so we dramatically improved the performance. We also improved handling of spreadsheets and PDFS. No more waitlist! You can now sign up and start using Hyperspell. Our [Python](https://pypi.org/project/hyperspell/) and [TypeScript](https://www.npmjs.com/package/hyperspell) SDKs are now available and you can use them in your project. The installation is as easy as: ```sh Python theme={null} # Or use poetry, uv, ... pip install hyperspell ``` ```sh TypeScript theme={null} # Or use yarn, pnpm, ... npm install @hyperspell/hyperspell ``` The SDKs are fully typed and come with a comprehensive documentation: ```python Python theme={null} from hyperspell import Hyperspell client = Hyperspell(api_key="YOUR_APP_TOKEN") ``` ```typescript TypeScript theme={null} import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'YOUR_APP_TOKEN' }); ``` # Regions & Data Residency Source: https://docs.hyperspell.com/resources/data-residency Choose where your data is stored and processed — United States or European Union. Hyperspell runs as two fully independent **regions** (data-residency cells): the default **United States** region and a **European Union** region hosted in AWS Europe (Ireland). Each region is a separate, isolated stack on its own domains. You choose a region when you create your account, and everything under that account — documents, embeddings, and queries — is stored and processed in that region. Regions are isolated. An account, its API keys, and its data belong to exactly one region — there is no cross-region access, and data is never replicated between regions. ## Endpoints Use the endpoints for the region your account was created in. | Service | United States (default) | European Union | | --------- | -------------------------------- | ----------------------------------- | | API | `https://api.hyperspell.com` | `https://api.eu.hyperspell.com` | | Dashboard | `https://app.hyperspell.com` | `https://app.eu.hyperspell.com` | | Connect | `https://connect.hyperspell.com` | `https://connect.eu.hyperspell.com` | ## Using the EU region ### SDKs Point the client at the EU API by setting the base URL: ```python Python theme={null} from hyperspell import Hyperspell client = Hyperspell( api_key="API_KEY", user_id="YOUR_USER_ID", base_url="https://api.eu.hyperspell.com", ) ``` ```typescript TypeScript theme={null} import Hyperspell from '@hyperspell/hyperspell'; const client = new Hyperspell({ apiKey: 'API_KEY', userID: 'YOUR_USER_ID', baseURL: 'https://api.eu.hyperspell.com', }); ``` ### REST Call the EU host directly: ```bash cURL theme={null} curl -X POST "https://api.eu.hyperspell.com/memories/query" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "what is a borogove?", "sources": ["vault"] }' ``` ### Connect Exchange an EU user token through the EU API, then send users to the EU Connect domain. The API and Connect hosts must stay in the same region: ```bash cURL theme={null} curl -X POST "https://api.eu.hyperspell.com/oauth/token-exchange/issue" \ -H "Authorization: Bearer " ``` ```html theme={null} Connect your accounts ``` An API key is valid only in the region it was created in. A key issued from `app.hyperspell.com` will not authenticate against `api.eu.hyperspell.com`, and vice-versa. A one-time code issued by the US API likewise cannot be redeemed by the EU Connect app. ## What stays in region In the EU region, all of your **content** is stored and processed in AWS Europe (Ireland) and never leaves the EU: Your documents, extracted text, chunks, and vector embeddings live in EU-region Postgres and object storage. Embeddings are generated by an embedding model running in-region. Summarization, entity extraction, and answer generation run on Amazon Bedrock using EU inference profiles. Hyperspell does not call any model endpoint outside the EU for EU-region content. Custom `answer_model` selection (see the [API reference](/api-reference/introduction)) is limited to models available in the EU — choosing one that isn't returns an error rather than routing your request outside the region. Point-in-time backups of EU-region data are stored and replicated only within the EU (across Availability Zones in Europe (Ireland)), never to another region. ## Operational services A small number of operational services process account metadata, usage events, and error diagnostics rather than your stored documents and memories: * **Authentication** (Clerk) — user identities and sign-in are operated from the United States under the **EU-US Data Privacy Framework**. * **Error monitoring and product analytics** (PostHog) — events are sent to the project for the account's region. EU-region events are processed by the EU PostHog project. See [Security](/resources/security) for Hyperspell's broader security and compliance practices. # Glossary Source: https://docs.hyperspell.com/resources/glossary The terms you will meet in the Hyperspell dashboard, in your agents, and in these docs. Hyperspell borrows a few words from everyday work and gives them a precise meaning. This page defines them. Terms link to each other, so you can start anywhere. ## Company brain The company brain is the knowledge layer between your workspace tools and the people and AI agents who need what those tools contain. It includes the [memory network](#memory-network) built from your [documents](#documents), and the [pages](#pages) Hyperspell generates from that network. ## Sources Sources are where your data lives today: Slack, Gmail, Notion, Google Drive, Granola, HubSpot, and so on. Hyperspell reads from sources to build the brain. ## Connections A connection is what a user creates when they enable an integration. It stores the credentials Hyperspell uses to read from the source on that user's behalf, or on behalf of the whole organization for a shared integration. A shared integration has one connection. A personal integration can have several connections per user, for example two Gmail accounts. ### Shared connections Shared connections hold data that all or most people in the company already have access to: internal knowledge bases, ticketing systems, CRMs. An admin connects them once, usually with an API key or a service account. Their content is visible to everyone in the organization by default. ### Personal connections Personal connections are connected by each [user](#user) individually, usually through an OAuth sign-in. Email, calendars, and direct messages are typical examples. Their content is visible only to the person who connected them by default. ## Documents A document is a piece of data from a source, converted into Hyperspell's own document format. A document may be an email thread, a Slack channel, a CRM contact with its notes and history, an uploaded PDF, or a web page. Documents are meant to be self-contained. A single Slack message that says "Yes" is useless without the question above it, which is why Hyperspell treats a channel, not a message, as the document. Documents are synced and updated automatically from the connected sources. ## Memories Memories are what Hyperspell extracts from [documents](#documents) during [ingestion](#ingestion). They come in a few kinds: * Facts, which are statements about the world. * User preferences. * Procedures, which tell an agent how to do something. * Learnings, which are answers to earlier questions. When someone asks "What projects did Ben work on in Q2?", Hyperspell resolves who Ben is, interprets Q2 as a date range, finds the relevant projects, and compiles an answer. That answer is stored as a memory, so the next time someone asks a similar question the result may be there right away. ## Memory network The memory network is Hyperspell's version of a knowledge graph. It connects extracted [memories](#memories) with their source [documents](#documents) and with [entities](#entities) such as people or organizations. Most links in the network are unlabeled. They say "this entity is relevant to this document, and so to every memory extracted from it." Their purpose is to help retrieval find relevant information faster by narrowing a query to the entities it is about, rather than to record every relationship between them. ## Entities Entities are the named things your data refers to. Hyperspell tracks three kinds: * People. * Work streams, a broader term than projects. It covers routine processes, team procedures, and long-running tasks that do not fit neatly into a project. A work stream is one or more people working towards an outcome. * Organizations, such as vendors and customers. A named entity is one mentioned in text, as in "Josh said we should ship by the end of the week". A linked entity is one that arrives through structured data: the sender of an email, a customer record in a connected CRM, or an [external account](#external-accounts) on a connected service. ## Content-based rules Content rules decide what spreads through the company brain and what stays put. There are two kinds. Both are set up by an organization admin. ### Content-based filters Filter rules keep content from spreading. They apply to content that would otherwise be shared with the whole company. When a filter rule matches a document, the document is held back from the company brain. Admins write filter rules for the categories that must never spread, such as compensation, HR matters, legal disputes, or credentials. ### Content-based sharing Sharing rules do the opposite. Content from a [personal connection](#personal-connections) is private by default. A sharing rule offers to share personal content with the rest of the organization when it matches, such as a customer call or a vendor conversation. Each person decides for themselves which sharing rules to turn on for their own connections. Only rules a person has opted into are applied to their content. See [Content rules](/advanced/content-rules) for how the two kinds are applied together. ## Pages People and agents can query the [memory network](#memory-network) directly, but it is often more useful to collect everything about one subject in one place. Pages are those pre-compiled summaries, one per project, work stream, person, or other subject. The reasoning behind pages comes from the three axes of [quality](#quality). Retrieval systems are good at surfacing relevant information, but they cannot promise completeness, and correctness is hard to check in the moment. Compiling a subject into a page ahead of time makes it possible to review both. ## Quality Hyperspell measures the quality of a company brain along three axes: 1. Correctness. Is the information true? 2. Relevance. Does it matter to the task at hand? 3. Completeness. Is everything needed for the task included? Relevance and completeness depend on context. So does correctness, more often than you would expect. Take "We closed the deal with Microsoft." It is true for the sales team, false for finance until the money arrives, and unclear for legal while signatures are still outstanding. # Security Source: https://docs.hyperspell.com/resources/security An overview of Hyperspell's security features and practices. ## Governance Hyperspell establishes policies and controls, monitors compliance with those controls, and proves the security and compliance to third-party auditors. Our policies are based on the following foundational principles: Access should be limited to only those with a legitimate business need, based on the principle of least privilege. Security controls should be applied consistently across all areas of the enterprise. Security controls should be implemented and layered according to the principle of defense-in-depth. The implementation of controls should be iterative, continuously improving effectiveness and decreasing friction. ​ ## Data Protection All datastores are encrypted at rest. Sensitive resources and tables also use row-level encryption. Hyperspell uses TLS 1.3 or higher everywhere data is transmitted over potentially insecure networks. Hyperspell backs-up all production data using a point-in-time approach. Backups are persisted for 30 days, and are globally replicated for resiliency against regional disasters. For data-residency regions such as the EU, backups remain within that region — see [Regions & Data Residency](/resources/data-residency). ## Operational Security Hyperspell provides comprehensive security training to all employees upon onboarding and annually. Hyperspell conducts threat briefings with employees to inform them of important security and safety-related updates that require special attention or action. Hyperspell employees are granted access to applications based on their role, and automatically deprovisioned upon termination of their employment. Further access must be approved according to the policies set for each application. Multi-factor authentication is required for all employees to access company applications. ​ ## Responsible Disclosure To report a vulnerability, please contact us for a [Responsible Disclosure](mailto:hello@hyperspell.com).