Memory & State

LeafMesh automatically manages all session state, conversation history, and agent data in its store (Redis by default, or Postgres). You configure the store in .env and LeafMesh handles everything else.

Store Configuration

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

# .env
# redis | postgres
LEAFMESH_STORE=redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=your-password
# Session TTL in seconds (7 days, the default)
REDIS_SESSION_TTL=604800
# General data TTL in seconds (1h)
REDIS_DEFAULT_TTL=3600

Variable	Default when unset	What it sets
`LEAFMESH_AGENCY_NAME`	none	The agency's name in the store; `LeafMesh.from_store()` starts this agency
`LEAFMESH_STORE`	`redis`	`redis` or `postgres`
Redis
`REDIS_URL`	none	The whole server in one URL, e.g. `redis://user:pw@host:6379/4`. `rediss://` turns TLS on. The single names below fill in anything it leaves out.
`REDIS_HOST`	`localhost`	Server host
`REDIS_PORT`	`6379`	Server port
`REDIS_PASSWORD`	none	Server password
`REDIS_DB`	`0`	Database number
`REDIS_DEFAULT_TTL`	`3600` (1 hour)	Lifetime of general data (yields, mesh communications), seconds
`REDIS_SESSION_TTL`	`604800` (7 days)	Lifetime of sessions and conversation history, seconds
`REDIS_SSL`	`false`	Set `true` to require TLS
`REDIS_SSL_CERT_REQS`	`required`	Certificate check: `required`, `optional` or `none`
`REDIS_SSL_CA_CERTS`	none	Path to the CA bundle
`REDIS_SSL_CERTFILE`, `REDIS_SSL_KEYFILE`	none	Client certificate and key (mutual TLS)
`REDIS_SSL_CHECK_HOSTNAME`	`true`	Check the server hostname against its certificate
`REDIS_CLUSTER_NODES`	none	Comma-separated `host:port` list. Setting it turns on Redis Cluster mode.
Postgres
`DATABASE_URL`	none	The whole server in one URL, e.g. `postgresql://user:pw@host:5432/db?sslmode=require`. The single names below fill in anything it leaves out.
`POSTGRES_HOST`	`localhost`	Server host
`POSTGRES_PORT`	`5432`	Server port
`POSTGRES_DB`	`leafmesh`	Database name
`POSTGRES_USER`, `POSTGRES_PASSWORD`	none	Credentials
`POSTGRES_SSLMODE`	unset (the driver's own default)	Postgres SSL mode
`POSTGRES_DEFAULT_TTL`	`3600` (1 hour)	Lifetime of general data, seconds
`POSTGRES_SESSION_TTL`	`604800` (7 days)	Lifetime of sessions, seconds
`POSTGRES_POOL_MIN`	`1`	Smallest connection pool size
`POSTGRES_POOL_MAX`	`10`	Largest connection pool size

Set only what you need; the rest keep their defaults. Studio shows whether the store 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. See Persistence for details.

What Gets Stored Automatically

LeafMesh automatically persists:

Data	Description	TTL
Session metadata	Session state and lifecycle	`REDIS_SESSION_TTL` (7 days)
Conversation history	Messages between user and agents	`REDIS_SESSION_TTL` (7 days)
Agent yields	Structured output from each agent	`REDIS_DEFAULT_TTL` (1h)
Mesh communications	Agent-to-agent call data	`REDIS_DEFAULT_TTL` (1h)
Manager decisions	Coordination decisions	`REDIS_DEFAULT_TTL` (1h)

You do not need to manually store or retrieve any of this data. LeafMesh reads and writes it as part of the normal request pipeline.

Inspecting Data

Browse session activity, agent details, and the global event feed in Studio's Sessions, Agents, and Activity tabs. For programmatic access from Python use the SDK:

analytics = Studio's Dashboard (HTTP)
agents    = leafmesh.list_agents()

Reading Upstream Yields in Intelligence Functions

In intelligence functions, upstream agent yields are passed as input_data:

async def downstream_agent(llm_response, input_data, context):
    # input_data contains the upstream agent's yields
    upstream_result = input_data.get("analysis")
    return llm_response

This happens automatically based on your can_call routing rules in YAML. When agent A calls agent B, agent A's yields become agent B's input_data.

Smart Memory

Agents can load relevant context from past interactions before executing. Configure the memory field on any agent:

agents:
  support_agent:
    name: "support_agent"
    memory:
      strategy: "hybrid"           # "recent" | "relevant" | "hybrid"
      limit: 10                    # Max posts to load
      cross_session: true          # Recall from other sessions
      relevance_weight: 0.6        # Tunable relevance weight
      recency_weight: 0.4          # Tunable recency weight
      decay_hours: 168             # Memory decay half-life (tunable)

Memory is loaded automatically before agent execution — no code needed. The strategy controls how posts are selected:

"recent": Last N posts, chronological order (current session only)
"relevant": All posts scored against current input, top N returned
"hybrid": Current session always included, cross-session ranked by a tunable relevance + recency blend

The exact weights and decay half-life are configurable per agent — see the link below for tuning guidance.

See Smart Memory Strategies for detailed configuration and tuning.

Session Continuity

Pass the same session_id to mesh_call to maintain conversation context:

# First message — creates a new session
result1 = await leafmesh.mesh_call("support", {"message": "My API is down"}, session_id="user_123")

# Follow-up — continues the same session with full history
result2 = await leafmesh.mesh_call("support", {"message": "It's the payments API"}, session_id="user_123")

LeafMesh automatically loads conversation history from Redis and includes it in the LLM prompt for context continuity.

Analytics

Get aggregated usage statistics:

Aggregated analytics, cache metrics, and per-session event streams are available in Studio's Dashboard and session inspector — operator UI, not part of the customer Python or HTTP surface.

Next Steps

Redis Integration — Redis configuration details
State Management — State patterns
Short-Term Memory — Session management

LeafMesh — Memory system reference