Hyperspell

Authentication Type: API Key or JWT Token

Description: Add long-term memory to your AI applications. Store, retrieve, and manage documents, emails, call transcripts, and other text for semantic search and context retrieval.

Beta Tool: Please contact support to get this Beta tool added to your account.

Authentication

To authenticate, you'll need a Hyperspell API key from Hyperspell.

Use the Authorization: Bearer <api_key> header for authentication.

Optional: When using an API Key, set the X-As-User header to act as a specific user. JWT User Tokens are always scoped to a specific user.

Memories

Add Memory

Add a document to the memory index for later retrieval.

Operation Type: Mutation (Write)

Parameters:

• text string (required): Complete text of the document (text, email, call transcript, etc.)
• collection string (required): Collection name for organizing memories. For agent-specific memories, use underscore_lower_case format (e.g., "reality_defender_agent")
• resourceId string (optional): Resource ID for the document. Generates new ID if omitted.
• title string (optional): Document title
• date string (optional): Document creation/update date (ISO 8601)
• metadata object (optional): Custom metadata for filtering
  • Keys: alphanumeric, max 64 characters
  • Values: string, number, or boolean

Returns:

• source string: Document provider (always "vault")
• resourceId string: Unique resource identifier
• status string: Processing status (pending, processing, completed, failed)

Example Usage:

{
  "text": "Meeting notes from Q4 planning session. Key decisions: 1. Launch new product in March 2. Increase marketing budget by 20% 3. Hire 5 new engineers",
  "collection": "meeting_notes_agent",
  "title": "Q4 Planning Session",
  "date": "2024-01-15T14:00:00Z",
  "metadata": {
    "department": "product",
    "meeting_type": "planning",
    "quarter": "Q4"
  }
}

Update Memory

Update an existing document in the memory index.

Operation Type: Mutation (Write)

Parameters:

• resourceId string (required): Resource ID to update
• text string (optional): Updated document text
• collection string (optional): Updated collection name
• title string (optional): Updated title
• metadata object (optional): Updated metadata

Returns:

• success boolean: Whether the update was successful
• message string (nullable): Additional details

Example Usage:

{
  "resourceId": "doc_abc123xyz",
  "text": "Updated meeting notes with action items completed.",
  "title": "Q4 Planning Session (Updated)"
}

Query Memories

Search for relevant memories using semantic search. Always returns an AI-generated answer based on retrieved memories.

Operation Type: Query (Read)

Parameters:

• query string (required): The search query to find relevant memories
• model string (optional): Model to use for generating answers (default: "llama-3.1"). Options include "llama-3.1", "claude-3-5-sonnet", "gpt-4o"
• sources array (optional): Array of sources to search (e.g., ["vault"]). Defaults to all available sources.
• collections array (optional): Array of collection names to filter by. For agent-specific memories, use underscore_lower_case format (e.g., ["reality_defender_agent"])
• after string (optional): Only return memories after this ISO 8601 timestamp
• before string (optional): Only return memories before this ISO 8601 timestamp
• maxResults number (optional): Maximum number of results to return (default: 10)

Returns:

• answer string (nullable): AI-generated answer based on retrieved memories
• results array: Array of matching memories
  • resourceId string: Unique identifier of the memory
  • source string: Source of the memory
  • text string: Text content of the memory
  • title string (nullable): Title of the memory
  • collection string (nullable): Collection the memory belongs to
  • date string (nullable): Timestamp of the memory
  • score number (nullable): Relevance score of the result
  • metadata object (nullable): Metadata attached to the memory

Example Usage:

{
  "query": "What were the key decisions from the Q4 planning meeting?",
  "model": "llama-3.1",
  "collections": ["meeting_notes_agent"],
  "maxResults": 5
}

List Memories

List all memories stored in Hyperspell.

Operation Type: Query (Read)

Parameters:

• size number (optional): Number of memories to return (default: 50)

Returns:

• memories array: Array of memories (metadata only, use Get Memory for full text)
  • resourceId string: Unique identifier of the memory
  • source string: Source of the memory
  • title string (nullable): Title of the memory
  • collection string (nullable): Collection the memory belongs to
  • date string (nullable): Timestamp of the memory
  • metadata object (nullable): Metadata attached to the memory

Example Usage:

{
  "size": 100
}

Get Memory

Retrieve a specific memory by its resource ID.

Operation Type: Query (Read)

Parameters:

• resourceId string (required): Unique resource identifier

Returns:

• resourceId string: Resource identifier
• source string: Document provider
• text string: Full text content of the memory
• title string (nullable): Document title
• collection string (nullable): Collection name
• date string (nullable): Timestamp
• metadata object (nullable): Document metadata

Example Usage:

{
  "resourceId": "doc_abc123xyz"
}

Delete Memory

Delete a memory from Hyperspell. This permanently removes the memory and cannot be undone.

Operation Type: Mutation (Write)

Parameters:

• resourceId string (required): The unique identifier of the memory to delete

Returns:

• success boolean: Whether the memory was deleted successfully
• message string (nullable): Additional message or error details

Example Usage:

{
  "resourceId": "doc_abc123xyz"
}

Common Use Cases

AI Assistants:

• Give AI assistants access to historical conversations
• Store and retrieve user preferences and context
• Build personalized AI experiences with memory

Knowledge Management:

• Index meeting notes, documents, and emails
• Enable semantic search across organizational knowledge
• Retrieve relevant context for AI-powered answers

Call Analytics:

• Store call transcripts for later analysis
• Search across historical conversations
• Extract insights from customer interactions

Document Processing:

• Index documents for semantic retrieval
• Build RAG (Retrieval Augmented Generation) systems
• Power AI search across large document collections