Hyperspell | Respan Docs

Hyperspell 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 and grab an API key.

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

Tracing

Hyperspell doesn’t expose a Python instrumentor. Wrap your memory operations in @task and @workflow decorators to trace them with Respan.

Setup

Install dependencies

pip install respan-ai hyperspell

Set environment variables

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

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

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.