botbook/src/06-gbdialog/keyword-set-bot-memory.md

SET BOT MEMORY

Store persistent key-value data at the bot level that persists across all conversations.

Syntax

SET BOT MEMORY key, value

Parameters

Parameter	Type	Description
key	String	Unique identifier for the memory item
value	String	Value to store (can be any string data)

Description

The SET BOT MEMORY keyword stores data that is:

• Persistent across all user sessions
• Shared between all users of the same bot
• Stored in the database permanently
• Available until explicitly updated or cleared

Bot memory is useful for:

• Configuration settings
• Global counters and statistics
• Shared state between users
• Bot-wide preferences
• Cached data that applies to all conversations

Examples

Store Simple Values

SET BOT MEMORY "welcome_message", "Hello! Welcome to our service."
SET BOT MEMORY "support_email", "support@example.com"
SET BOT MEMORY "business_hours", "9 AM - 5 PM EST"

Store Counters

current_count = GET BOT MEMORY "visitor_count"
IF current_count = "" THEN
    current_count = "0"
END IF
new_count = VAL(current_count) + 1
SET BOT MEMORY "visitor_count", STR(new_count)
TALK "You are visitor number " + STR(new_count)

Store JSON Data

user_data = '{"name": "John", "level": 5, "points": 1200}'
SET BOT MEMORY "user_profile", user_data

Dynamic Keys

today = FORMAT(NOW(), "YYYY-MM-DD")
daily_key = "stats_" + today
SET BOT MEMORY daily_key, "25"

Configuration Management

' Store bot configuration
SET BOT MEMORY "max_retries", "3"
SET BOT MEMORY "timeout_seconds", "30"
SET BOT MEMORY "api_version", "v2"

' Later, read configuration
max_retries = GET BOT MEMORY "max_retries"
timeout = GET BOT MEMORY "timeout_seconds"

Database Storage

Bot memories are stored in the bot_memories table:

• id: UUID primary key
• bot_id: Reference to the bot
• key: Memory key (indexed for fast lookup)
• value: Memory value (text)
• created_at: Timestamp of creation
• updated_at: Timestamp of last update

Performance Considerations

• Keys are indexed for fast retrieval
• Values are stored as text (no size limit in PostgreSQL)
• Updates are asynchronous to avoid blocking
• Consider using structured keys for organization

Best Practices

1. Use Descriptive Keys: Make keys self-documenting

   SET BOT MEMORY "config:email:smtp_server", "mail.example.com"
   SET BOT MEMORY "stats:daily:2024-01-15", "150"
   

2. Handle Missing Values: Always check if memory exists

   value = GET BOT MEMORY "some_key"
   IF value = "" THEN
       ' Initialize with default
       SET BOT MEMORY "some_key", "default_value"
       value = "default_value"
   END IF
   

3. Avoid Sensitive Data: Don't store passwords or tokens

   ' BAD: Don't do this
   ' SET BOT MEMORY "admin_password", "secret123"
   
   ' GOOD: Store non-sensitive config
   SET BOT MEMORY "admin_email", "admin@example.com"
   

4. Structure Complex Data: Use JSON for complex structures

   settings = '{"theme": "dark", "language": "en", "notifications": true}'
   SET BOT MEMORY "user_preferences", settings
   

5. Clean Up Old Data: Remove unused memories periodically

   ' Remove old daily stats
   old_date = FORMAT(DATE_ADD(NOW(), -30, "days"), "YYYY-MM-DD")
   SET BOT MEMORY "stats_" + old_date, ""
   

Differences from User Memory

Aspect	Bot Memory	User Memory
Scope	All users of the bot	Single user
Persistence	Permanent	Session or permanent
Use Case	Global settings	Personal data
Access	Any conversation	User's conversations only

Error Handling

• If database connection fails, operation is logged but doesn't crash
• Invalid bot IDs are logged as errors
• Duplicate keys update existing values
• Empty keys are not allowed

Related Keywords

• GET BOT MEMORY - Retrieve stored bot memory
• SET - Set user-scoped variables
• REMEMBER - Store user-specific memories

Implementation

Located in src/basic/keywords/bot_memory.rs

The implementation:

• Uses async database operations
• Handles updates atomically with transactions
• Validates bot ID format
• Logs all operations for debugging