Skip to content

Commit da0ca3f

Browse files
authored
Add Valkey session manager documentation (#334)
- Add strands-valkey-session-manager to community session managers - Document high-performance Redis/Valkey-based session storage - Include installation, usage examples, and configuration details
1 parent fa1bc88 commit da0ca3f

File tree

2 files changed

+103
-0
lines changed

2 files changed

+103
-0
lines changed
Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Strands Valkey Session Manager
2+
3+
{{ community_contribution_banner }}
4+
5+
The [Strands Valkey Session Manager](https://github.com/jeromevdl/strands-valkey-session-manager) is a high-performance session manager for Strands Agents that uses Valkey/Redis for persistent storage. Valkey is a very-low latency cache that enables agents to maintain conversation history and state across multiple interactions, even in distributed environments.
6+
7+
Tested with Amazon ElastiCache Serverless (Redis 7.1, Valkey 8.1), ElastiCache (Redis 7.1, Valkey 8.2), and Upstash.
8+
9+
## Installation
10+
11+
```bash
12+
pip install strands-valkey-session-manager
13+
```
14+
15+
## Usage
16+
17+
### Basic Setup
18+
19+
```python
20+
from strands import Agent
21+
from strands_valkey_session_manager import ValkeySessionManager
22+
from uuid import uuid4
23+
import valkey
24+
25+
# Create a Valkey client
26+
client = valkey.Valkey(host="localhost", port=6379, decode_responses=True)
27+
28+
# Create a session manager with a unique session ID
29+
session_id = str(uuid4())
30+
session_manager = ValkeySessionManager(
31+
session_id=session_id,
32+
client=client
33+
)
34+
35+
# Create an agent with the session manager
36+
agent = Agent(session_manager=session_manager)
37+
38+
# Use the agent - all messages are automatically persisted
39+
agent("Hello! Tell me about Valkey.")
40+
41+
# The conversation is now stored in Valkey and can be resumed later using the same session_id
42+
43+
# Display conversation history
44+
messages = session_manager.list_messages(session_id, agent.agent_id)
45+
for msg in messages:
46+
role = msg.message["role"]
47+
content = msg.message["content"][0]["text"]
48+
print(f"** {role.upper()}**: {content}")
49+
```
50+
51+
## Key Features
52+
53+
- **Persistent Sessions**: Store agent conversations and state in Valkey/Redis
54+
- **Distributed Ready**: Share sessions across multiple application instances
55+
- **High Performance**: Leverage Valkey's speed for fast session operations
56+
- **JSON Storage**: Native JSON support for complex data structures
57+
- **Automatic Cleanup**: Built-in session management and cleanup capabilities
58+
59+
## Configuration
60+
61+
### ValkeySessionManager Parameters
62+
63+
- `session_id`: Unique identifier for the session
64+
- `client`: Configured Valkey client instance (only synchronous versions are supported)
65+
66+
### Storage Structure
67+
68+
The ValkeySessionManager stores data using the following key structure:
69+
70+
```
71+
session:<session_id> # Session metadata
72+
session:<session_id>:agent:<agent_id> # Agent state and metadata
73+
session:<session_id>:agent:<agent_id>:message:<message_id> # Individual messages
74+
```
75+
76+
## Available Methods
77+
78+
The following methods are used transparently by Strands:
79+
80+
- `create_session(session)`: Create a new session
81+
- `read_session(session_id)`: Retrieve session data
82+
- `delete_session(session_id)`: Remove session and all associated data
83+
- `create_agent(session_id, agent)`: Store agent in session
84+
- `read_agent(session_id, agent_id)`: Retrieve agent data
85+
- `update_agent(session_id, agent)`: Update agent state
86+
- `create_message(session_id, agent_id, message)`: Store message
87+
- `read_message(session_id, agent_id, message_id)`: Retrieve message
88+
- `update_message(session_id, agent_id, message)`: Update message
89+
- `list_messages(session_id, agent_id, limit=None)`: List all messages
90+
91+
## Requirements
92+
93+
- Python 3.10+
94+
- Valkey/Redis server
95+
- strands-agents >= 1.0.0
96+
- valkey >= 6.0.0
97+
98+
## References
99+
100+
- **PyPI**: [strands-valkey-session-manager](https://pypi.org/project/strands-valkey-session-manager/)
101+
- **GitHub**: [jeromevdl/strands-valkey-session-manager](https://github.com/jeromevdl/strands-valkey-session-manager)
102+
- **Issues**: Report bugs and feature requests in the [GitHub repository](https://github.com/jeromevdl/strands-valkey-session-manager/issues)

mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ nav:
163163
- Fireworks AI: community/model-providers/fireworksai.md
164164
- Session Managers:
165165
- Amazon AgentCore Memory: community/session-managers/agentcore-memory.md
166+
- Valkey/Redis: community/session-managers/strands-valkey-session-manager.md
166167

167168
- Contribute ❤️: https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md
168169
- API Reference:

0 commit comments

Comments
 (0)