Redis Integration

Redis is the platform's default state backend for business-logic data: sessions, conversation history, agent yields, mesh communications, and coordination decisions. Redis is configured in .env and works automatically — no direct Redis calls are needed in your application code.

Postgres is also supported. LeafMesh can run its business-logic state on Postgres instead of Redis with the same behavior and guarantees — see Persistence (Redis or Postgres). Everything on this page applies to the Redis backend; the choice is a deployment setting, not a code change.

Configuration

From 2.4.482 Redis is set only in .env, never in the YAML. A persistence: or top-level redis: block in config.yaml is no longer read (LeafMesh logs a warning at boot and ignores it).

# .env
LEAFMESH_AGENCY_NAME=my-agency
LEAFMESH_STORE=redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=your-password
# 1 hour for general data
REDIS_DEFAULT_TTL=3600
# 7 days for sessions (the default)
REDIS_SESSION_TTL=604800

You can also name the whole server in one URL, REDIS_URL=redis://user:pw@host:6379/4 (rediss:// turns TLS on); the single names above fill in anything the URL leaves out.

Set only what you need; the rest keep their defaults (localhost, 6379, database 0, data 1 hour, sessions 7 days). Studio shows whether Redis is reachable under Infrastructure → Datastores, which also shows its latency, the server, the settings in force and which .env names set them — never the address or password. The full list of store variables is on Persistence.

TLS / Encryption in Transit

For SOC 2 / ISO 27001 deployments, Redis traffic must be encrypted. Set REDIS_SSL=true and point REDIS_SSL_CA_CERTS at your CA bundle:

# .env
REDIS_HOST=redis.example.com
# Common rediss:// port
REDIS_PORT=6380
REDIS_SSL=true
# Reject untrusted certs
REDIS_SSL_CERT_REQS=required
REDIS_SSL_CA_CERTS=/etc/ssl/certs/redis-ca.crt
REDIS_SSL_CHECK_HOSTNAME=true

Mutual TLS — set REDIS_SSL_CERTFILE + REDIS_SSL_KEYFILE to authenticate LeafMesh to Redis. REDIS_SSL_CERT_REQS=none exists for development only and disables peer verification entirely.

Auto-Storage

LeafMesh automatically persists all state without explicit save calls:

Data	TTL
Session metadata	`REDIS_SESSION_TTL`
Conversation history	`REDIS_SESSION_TTL`
Agent yields	`REDIS_DEFAULT_TTL`
Mesh communications	`REDIS_DEFAULT_TTL`
Coordination analyses	`REDIS_DEFAULT_TTL`
Coordination decisions	`REDIS_DEFAULT_TTL`

How It Works

When you call await leafmesh.mesh_call(...), LeafMesh handles all persistence automatically:

Session load/create — Looks up or creates the session by session_id
History retrieval — Loads recent conversation messages for LLM context
Yield storage — After agent execution, stores structured yields
Conversation recording — Appends the exchange (role, content, timestamp, agent name)
Mesh forwarding — Records mesh communication data when can_call triggers downstream agents

Inspecting Session Data

Browse sessions in Studio's Sessions tab, or query session state via the platform's REST API.

Redis Cluster

For high-volume deployments, list the cluster nodes in .env. Setting REDIS_CLUSTER_NODES is what turns cluster mode on:

# .env
LEAFMESH_AGENCY_NAME=my-agency
LEAFMESH_STORE=redis
REDIS_CLUSTER_NODES=redis-1:6379,redis-2:6379,redis-3:6379

LeafMesh connects to the cluster and handles node routing transparently.

Event Backbone

LeafMesh uses Redis as its event backbone for in-cluster coordination. You don't interact with the event topology directly — the platform handles it for you. See Event System for the customer-facing event model.

Requirements

Redis 6.0+ minimum
Redis 7.0+ recommended (improved performance and memory efficiency)
Network connectivity from LeafMesh to Redis

Next Steps

Short-Term Memory — Session and state management
State Management — State patterns in intelligence functions
Event System — Redis Streams architecture

LeafMesh — Redis-backed persistence