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

1 import os
2 from hyperspell import Hyperspell
3 from respan import Respan, workflow, task
4 
5 respan = Respan()
6 client = Hyperspell(api_key=os.environ["HYPERSPELL_API_KEY"])
7 
8 @task(name="store_memory")
9 def store_memory(user_id: str, content: str):
10     return client.memories.create(user_id=user_id, content=content)
11 
12 @task(name="retrieve_memory")
13 def retrieve_memory(user_id: str, query: str):
14     return client.memories.search(user_id=user_id, query=query)
15 
16 @workflow(name="memory_workflow")
17 def memory_workflow():
18     store_memory("user_123", "I prefer Python over JavaScript.")
19     return retrieve_memory("user_123", "programming language preference")
20 
21 print(memory_workflow())
22 respan.flush()

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

1 from respan import Respan, propagate_attributes
2 
3 respan = Respan()
4 
5 def handle_request(user_id: str, query: str):
6     with propagate_attributes(
7         customer_identifier=user_id,
8         thread_identifier="conv_abc_123",
9         metadata={"plan": "pro"},
10     ):
11         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.