Overview

The HyperFlow AI Key-Value Store provides persistent storage for HyperFlow applications. It is commonly accessed within a flow-graph via the Key-Value Store node, allowing you to add persistent storage and retrieval of any data-flow value within your flows.

The Python-enabled nodes all have programmatic access to this same key-value store allowing you to save and retrieve data across different node executions and flow runs and interact coordinate this persistent state use with nodes such as the Key-value Store node in your flows. This is useful for maintaining state, caching results, and sharing data between nodes.

See more details about the capabilities and characteristics of the key-value store in the Key-Value Store Node Reference.

Basic Usage

Storing Values

# Store a simple value
keyValueStore.insert("user_preference", "dark_mode")

# Store complex data
keyValueStore.insert("config", {
    "threshold": 0.8,
    "enabled": True,
    "tags": ["production", "v2"]
})

Retrieving Values

# Get a value
preference = keyValueStore.retrieve("user_preference")
# Returns: "dark_mode" or None if not found

# Check if value exists before using
config = keyValueStore.retrieve("config")
if config:
    threshold = config["threshold"]
else:
    # Use default
    threshold = 0.5

Deleting Values

# Delete a single key
keyValueStore.remove("temp_cache")

# Delete with wildcard pattern
keyValueStore.remove("temp_*")  # Removes all keys starting with "temp_"

# Clear all cache entries
keyValueStore.remove("cache_*")

Entity Isolation (New)

Store and retrieve data isolated by entity (user, organization, etc.):

# Store data for a specific user
user_id = input1  # e.g., "user123"
keyValueStore.insert("preferences", {
    "theme": "dark",
    "language": "en"
}, entity_id=user_id)

# Retrieve user-specific data
prefs = keyValueStore.retrieve("preferences", entity_id=user_id)

# Different users have isolated storage
for user in ["alice", "bob"]:
    score = keyValueStore.retrieve("high_score", entity_id=user)
    if score:
        print(f"{user}: {score}")

# List keys for a specific entity
user_keys = keyValueStore.list_keys(entity_id=user_id)
print(f"Keys for {user_id}: {user_keys}")

# Delete all data for an entity
for key in keyValueStore.list_keys(entity_id=user_id):
    keyValueStore.remove(key, entity_id=user_id)

Advanced Features

Working with Lists

# Initialize a list
keyValueStore.insert("task_queue", [])

# Append to list
queue = keyValueStore.retrieve("task_queue") or []
queue.append({"task": "process_image", "id": 123})
keyValueStore.insert("task_queue", queue)

# Pop from list
queue = keyValueStore.retrieve("task_queue") or []
if queue:
    task = queue.pop(0)  # Get first task
    keyValueStore.insert("task_queue", queue)
    # Process task...

Working with Counters

# Increment a counter
current = keyValueStore.retrieve("visit_count") or 0
keyValueStore.insert("visit_count", current + 1)

# Track multiple counters
counters = keyValueStore.retrieve("counters") or {}
counters["page_views"] = counters.get("page_views", 0) + 1
counters["api_calls"] = counters.get("api_calls", 0) + 1
keyValueStore.insert("counters", counters)

# Per-user counters
user_id = input1
count_key = f"login_count"
count = keyValueStore.retrieve(count_key, entity_id=user_id) or 0
keyValueStore.insert(count_key, count + 1, entity_id=user_id)

Listing Keys