# Hyperspell

> 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.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://docs.hyperspell.com/usage/permissions).

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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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