Hyperspell

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 .

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

Paste this into your coding agent:


Help me set up Respan tracing with the Hyperspell integration.
Follow https://www.respan.ai/docs/integrations/hyperspell.md

Setup

Install dependencies

Terminal


pip install respan-ai hyperspell

Set environment variables

Terminal


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