> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Hyperspell

> Trace Hyperspell memory operations with Respan — full observability over store, retrieve, and context management.

[Hyperspell](https://hyperspell.com/) is a memory management platform for AI applications, providing persistent memory and context management for LLM-powered products. Respan gives you full observability over how context is stored, retrieved, and used across conversations.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Tracing

> **Note**
>
> Hyperspell doesn't expose a Python instrumentor. Wrap your memory operations in `@task` and `@workflow` decorators to trace them with Respan.

## Setup

#### Install dependencies

```bash
pip install respan-ai hyperspell
```

#### Set environment variables

```bash
export HYPERSPELL_API_KEY="YOUR_HYPERSPELL_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

`HYPERSPELL_API_KEY` is used for memory operations. `RESPAN_API_KEY` is used to export traces to Respan.

#### Initialize and run

```python
import os
from hyperspell import Hyperspell
from respan import Respan, workflow, task

respan = Respan()
client = Hyperspell(api_key=os.environ["HYPERSPELL_API_KEY"])

@task(name="store_memory")
def store_memory(user_id: str, content: str):
    return client.memories.create(user_id=user_id, content=content)

@task(name="retrieve_memory")
def retrieve_memory(user_id: str, query: str):
    return client.memories.search(user_id=user_id, query=query)

@workflow(name="memory_workflow")
def memory_workflow():
    store_memory("user_123", "I prefer Python over JavaScript.")
    return retrieve_memory("user_123", "programming language preference")

print(memory_workflow())
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your memory workflow with store, retrieve, and search spans.

## Configuration

| Parameter             | Type           | Default | Description                                |
| --------------------- | -------------- | ------- | ------------------------------------------ |
| `api_key`             | `str \| None`  | `None`  | Falls back to `RESPAN_API_KEY` env var.    |
| `base_url`            | `str \| None`  | `None`  | Falls back to `RESPAN_BASE_URL` env var.   |
| `customer_identifier` | `str \| None`  | `None`  | Default customer identifier for all spans. |
| `metadata`            | `dict \| None` | `None`  | Default metadata attached to all spans.    |
| `environment`         | `str \| None`  | `None`  | Environment tag (e.g. `"production"`).     |

## Attributes

### With propagate_attributes

```python
from respan import Respan, propagate_attributes

respan = Respan()

def handle_request(user_id: str, query: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        return retrieve_memory(user_id, query)
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |