From 19b2a0ab8959534cfa4e2dccf30d9080e667def0 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:47:50 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 +++ README.md | 3 + commands/hype.md | 26 +++++ plugin.lock.json | 65 +++++++++++++ skills/setup/SKILL.md | 93 ++++++++++++++++++ skills/setup/connect_memories.md | 116 +++++++++++++++++++++++ skills/setup/no_sdk.md | 3 + skills/setup/upload_memories_directly.md | 3 + skills/setup/vercel_ai_sdk.md | 43 +++++++++ 9 files changed, 366 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/hype.md create mode 100644 plugin.lock.json create mode 100644 skills/setup/SKILL.md create mode 100644 skills/setup/connect_memories.md create mode 100644 skills/setup/no_sdk.md create mode 100644 skills/setup/upload_memories_directly.md create mode 100644 skills/setup/vercel_ai_sdk.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..94cd710 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "setup", + "description": "Custom skills and plugins that lets you integrate Hyperspell into your code project.", + "version": "1.0.0", + "author": { + "name": "Hyperspell" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..ba81df1 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# setup + +Custom skills and plugins that lets you integrate Hyperspell into your code project. diff --git a/commands/hype.md b/commands/hype.md new file mode 100644 index 0000000..dae4dac --- /dev/null +++ b/commands/hype.md @@ -0,0 +1,26 @@ +--- +description: Guide the user through integrating hyperspell +argument-hint: [api-key] +--- + +# Hype Command + +First, display the following message to the user, replace YOUR PROJECT with the project they're currently working on. Make sure the formatting of the box stays intact. + +``` +╭──╮ +│ │ ╭───────────────────────────────────────────────────╮ +@ @ │ It looks like you’re integrating Hyperspell into │ +││ ││ <─┤ . I can help you with that. │ +││ ││ ╰───────────────────────────────────────────────────╯ +│╰─╯│ +╰───╯ + +Hyperspell is the memory & context layer for AI agents and apps. This Claude Code skill will help you set up Hyperspell in your project, explain how things work, and get you up and running in less than five minutes. + +``` + +When the user evoked this command, they may have passed the folowwing api key as an argument: '$1' + +Use the **Setting up Hyperspell** skill to integrate hyperspell into this project. If the api key is present, use that during the skill step that configures the API key. + diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..938f1bf --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,65 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:hyperspell/claude:setup", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "00c0ad90fb578589f6be3f6587ff05c7ce4437aa", + "treeHash": "bbff72f495667d198a9661c749ec84d4c68195c6d3c9be1821bf1c151b9bbd31", + "generatedAt": "2025-11-28T10:17:37.923608Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "setup", + "description": "Custom skills and plugins that lets you integrate Hyperspell into your code project.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "48f01b213cc4031b6d2a156fb81268eab6a1b7f70124fb83bc3325a92513a02b" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "df542ef62a41ba7b00e3d94a94cad48144c82b30489d08c322d36b25e5442c7d" + }, + { + "path": "commands/hype.md", + "sha256": "a6fd43aa7202121d5aab18b241e47ffb16c7f0b226a48644f1967d8d49420fd0" + }, + { + "path": "skills/setup/vercel_ai_sdk.md", + "sha256": "64885b2f4baf4bf1292a686139c579c9552e7fbdcc6be898f77dc3f507b83e18" + }, + { + "path": "skills/setup/connect_memories.md", + "sha256": "2463b70581f6a4a654f0df1710547b3062c8c9b3ee5491c9a670d29065ec8ea3" + }, + { + "path": "skills/setup/upload_memories_directly.md", + "sha256": "3bb9d92ad91ef806045120a2052816faccf90e3e7d136ae1906da609946b3dd8" + }, + { + "path": "skills/setup/SKILL.md", + "sha256": "c2c889c98e3af1345603af342a73e4736cdf20e43fa0ecc4b3d7ba5f1651c0c8" + }, + { + "path": "skills/setup/no_sdk.md", + "sha256": "95e724971ec154ab1fdf3ea205cca857fdad54e9d1345913210e364d8ebb2b6d" + } + ], + "dirSha256": "bbff72f495667d198a9661c749ec84d4c68195c6d3c9be1821bf1c151b9bbd31" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md new file mode 100644 index 0000000..21bb824 --- /dev/null +++ b/skills/setup/SKILL.md @@ -0,0 +1,93 @@ +--- +name: Setting up Hyperspell +description: Guide the user through integrating Hyperspell into their project +allowed-tools: Bash, Read, Grep, Glob, Write, Edit, TodoWrite +--- + +# Setup Hyperspell + +## Instructions + +Copy this checklist and track your progress: + +``` +Implementation Progress: +- [ ] Step 1: Install the SDK +- [ ] Step 2: Configure the API Key +- [ ] Step 3: Add memories +- [ ] Step 4: Search Memories +- [ ] Step 5: Wrapping up +``` + +Run the following command and note the output as $START_TIME: + +```sh +date -u +%Y-%m-%dT%H:%M:%SZ +``` + +### Step 1: Install the Hyperspell SDK + +Then, determine whether the hyperspell SDK is already installed. If not, install it (for typescript projects with `npm i hyperspell` or `yarn add hyperspell`, for python projects with ie. `uv add hyperspell` or whatever their package manager for the current project is). + +### Step 2: Configure the API Key + +When the user evoked this command, they may have passed the folowwing api key as an argument: '$1' + +If that string is blank, tell the user to go to https://app.hyperspell.com/api-keys to create an API key and paste it here. + +Then put it in .env.local (or .env if it doesn't exist) as `HYPERSPELL_API_KEY`. + +If this project contains an `.env.example`, also put a dummy key in there (`HYPERSPELL_API_KEY=hs-0-xxxxxxxxxxxxxxxxxxxxxx`) + +### Step 3: Asking how the user wants to add memories + +Hyperspell is a memory and context layer for AI agents and apps. Memories typically come from two sources: + +* Your project's end-user connects their accounts (ie. Gmail, Slack, ...) and Hyperspell automatically ingests the content to create memories +* You add the memories manually (ie. through file uploads or tracking conversations). + +Display the following explanation to the user (replace `` with the name of this project): + +``` +Hyperspell can create memory from a wide number of different sources, including e-mail, Slack, documents, chat transcripts, or uploaded files. + +Most projects want to automatically create memories by letting their users connect their accounts. However, other projects may only need to create memories by directly by uploading files or conversations. How do you want to create memories in ? +``` + +Then, ask the user how they want to ingest memories. Offer this multiple choice menu: + +- I want to connect my user's accounts automatically +- I want to add memories directly (upload files or conversations) + +Based on their choice, follow the instructions in ./connect_memories.md or ./upload_memories_directly.md + +### Step 4: Asking how the user wants to use memories + +Display the following message to your user: + +``` +Now that we've created a way to get new memories into Hyperspell, we also need to access them at the right time to give your app the necessary context. Let me analyse your code base and determine the best way to do so. +``` + +Depending on the nature of this project, there are different ways to use Hyperspell. Determine if this project is using a third party SDK to manage their core agent loops and follow the appropriate instructions: + +- For the Vercel AI sdk (the `ai` package in package.json), follow the instructions in ./vercel_ai_sdk.md +- If this project is not using any third-party SDKs, follow the instructions in ./no_sdk.md + +## Step 5: Wrapping up + +Run the following command again: + +```sh +date -u +%Y-%m-%dT%H:%M:%SZ +``` + +Compare the output with $START_TIME and calculate how many minutes have passed since we started this skill as DURATION. + +Then, euphorically congratulate the user (by name if you know), they've just implemented hyperspell in less than minutes. + +Display the following message: + +``` +This is just the beginning of your journey with Hyperspell. As your project grows, Hyperspell grows with you. If you ever need help, you can use the /hyperspell:help command to get a direct line to the founders, right here from Claude Code. +``` diff --git a/skills/setup/connect_memories.md b/skills/setup/connect_memories.md new file mode 100644 index 0000000..fb5dadc --- /dev/null +++ b/skills/setup/connect_memories.md @@ -0,0 +1,116 @@ +# Integrate the Hyperspell SDK to let your users connect their accounts. + +Before Hyperspell can automatically ingest your user's data, they need to connect their accounts. + +To do so, we need to do two things: + +1. Initialize the SDK and generate a user token that we can safely pass the the OAuth flow +2. Put a button into your app that opens the Hyperspell Connect page that lets users connect their accounts + +Add the following two tasks to your checklist as subtasks of `Add memories`: + +``` +- [ ] Step 1: Get available integrations +- [ ] Step 2: Initialize the SDK +- [ ] Step 3: Add a Connect button +``` + +## 1. Get available integrations + +Use the API key you set up earlier to get the available integrations for this project: + +```sh +curl --request GET \ + --url https://api.hyperspell.com/integrations/list \ + --header 'Authorization: Bearer API_KEY' +``` + +Note the `provider` name for each integration. + + +## 2. Initialize the SDK + +When we're initializing the SDK, we will pass a user ID to it to identify the currently logged in user. If there doesn't seem to be any user management, we will use the user id `anonymous` instead. + +First, examine the code base to determine how to get the currently logged in user in a server-side action. + +Create a typescript file with a server side action in an appropriate directory (ie `src/actions/hyperspell.ts`) and add the following code — modify it to fit the project, and replace `PROVIDERS` with an array of the providers you retrieved in step 1. + +```typescript +'use server' + +import Hyperspell from 'hyperspell'; + +export async function getUserToken() { + const userId = ... // Write code to get the ID of the currently logged in user here — you might have to import other modules + + const hyperspell = new Hyperspell({ apiKey: process.env.HYPERSPELL_API_KEY }); + const response = await hyperspell.auth.userToken({user_id: userId}); + return response.token; +} + +export async function search(query: string, answer: boolean = true) { + const userId = ... // Write code to get the ID of the currently logged in user here — you might have to import other modules + const hyperspell = new Hyperspell({ apiKey: process.env.HYPERSPELL_API_KEY, userID: userId }); + + const response = await hyperspell.memories.search({ + query, + answer, + sources = ; + }); + return response.answer; +} +``` + + +## 3. Add a Connect button + +Display the following message to your user: + +``` +We will now add a button to your project that opens Hyperspell Connect. On this page, your users can connect their account. We will use the `userToken` from the code to securely identify your user on this page. +``` + +Replace `` with an oxford comma separate list of providers we just fetched. + +Then, we need to find an appropriate place to place the button. Analyize the codebase to determine if it has any of the following: + +- A Settings menu / dropdown on the main page +- A settings page or modal +- An onboarding flow +- A chat UI that has the option to add a custom action or button close to the input area. + +Based on what you find, offer the user a multiple choice menu to ask where to put the button (and offer other that lets the user describe it themselves.) + +After you determined where to put the button, find the file that contains the component which should contain the button. In this file, import our `getUserToken()` action, ie with + +```typescript +import { getUserToken } from '@/actions/hyperspell'; +``` + +(Modify the import path depending on where you put the file). + +in the component that renders the button, we need to determine the URL of the current page to use as a redirect url — determine how to use this projects router + +first create the target URL like this: + +```typescript +const token = getUserToken(); +const connectUrl = `https://connect.hyperspell.com?token=${token}&redirect_uri=${window.location.href}; +``` + +If the project already has built-in button components, use that one. If it has other buttons that are style with ie. tailwind css, copy the style from other buttons. At worst, simply use an `` element and style it yourself. As a `href` use the `connectUrl` we constructed. + +Also display the Hyperspell logo as an icon on the button, using the common way this is done in this project. You can use this SVG as the logo (replace the fill color with something appropriate for the button). + +```xml + + + +``` + +Finally, display the following message to the user: + +``` +Great, I've created a button that lets your users connet their accounts. Feel free to try it out right now! +``` diff --git a/skills/setup/no_sdk.md b/skills/setup/no_sdk.md new file mode 100644 index 0000000..9de4e91 --- /dev/null +++ b/skills/setup/no_sdk.md @@ -0,0 +1,3 @@ +# Using Hyperspell without third-party agent SDKs + +Nothing to do here. \ No newline at end of file diff --git a/skills/setup/upload_memories_directly.md b/skills/setup/upload_memories_directly.md new file mode 100644 index 0000000..2a26be8 --- /dev/null +++ b/skills/setup/upload_memories_directly.md @@ -0,0 +1,3 @@ +# Integrate the Hyperspell SDK to add memories manually + +Just say "derp!" \ No newline at end of file diff --git a/skills/setup/vercel_ai_sdk.md b/skills/setup/vercel_ai_sdk.md new file mode 100644 index 0000000..cad7b4d --- /dev/null +++ b/skills/setup/vercel_ai_sdk.md @@ -0,0 +1,43 @@ +# Using Hyperspell with the Vercel AI SDK + +When integrating with the Vercel AI SDK, we will expose Hyperspell as a tool. + +## Create the hyperspell tool + +Find the appropriate place to add new tools. If this project already has a directory or file where tools are being managed, put our new tool there. Otherwise, you can put the tool in the same file that makes the actual call to the agent. Add the following code, make sure to implement the hyperspell tool verbatim. + +```typescript +import { tool } from "ai"; +import { z } from 'zod'; +import { search } from "@/app/actions/hyperspell"; + +const memories = tool({ + name: "memories", + description: "Search connected memories for information. ALWAYS use this before answering the user's question.", + inputSchema: z.object({ + query: z.string().describe("The query to search for. Formulate it as a question."), + }), + execute: async ({ query }) => { + return await search(query, true); + }, +}) +``` + +Adjust the import path for the `search` function to match the place you create the actions in the previous step. + +## Add the hyperspell tool to the agent + +The agent is typically called with either the `streamText` or `generateText` methods from the `ai` package. Find that call, Import the hyperspell tool if it's not in the same file, and add the `tools` parameter like this. + +```typescript +streamText({ + model: openai("gpt-5-nano"), + messages, + tools: { memories }, // add hyperspell as a new entry if there are already existing tools + stopWhen: stepCountIs(5), +}); +``` + +Make sure that `stopWhen` is set and has a stepCount of at least 5 — if it is already set to a higher number, don't change it. + +Done. \ No newline at end of file