REMEMBER / RECALL Keywords

The REMEMBER and RECALL keywords provide a powerful time-based memory system for storing and retrieving data associated with users. Unlike standard memory operations, REMEMBER supports automatic expiration of stored values.

Syntax

REMEMBER

REMEMBER key, value, duration

RECALL

result = RECALL key

Parameters

REMEMBER Parameters

Duration Formats

Examples

Basic Usage

' Remember user's preferred language for 30 days
REMEMBER "preferred_language", "Spanish", "30 days"

' Later, recall the preference
language = RECALL "preferred_language"
TALK "Your language preference is: " + language

Session-Based Memory

' Remember a temporary verification code for 5 minutes
code = RANDOM(100000, 999999)
REMEMBER "verification_code", code, "5 minutes"
TALK "Your verification code is: " + code

' Verify the code later
HEAR user_code
stored_code = RECALL "verification_code"

IF user_code = stored_code THEN
    TALK "Code verified successfully!"
ELSE
    TALK "Invalid or expired code."
END IF

Storing Complex Data

' Store user preferences as an array
preferences = ["dark_mode", "notifications_on", "english"]
REMEMBER "user_preferences", preferences, "1 year"

' Store a shopping cart temporarily
cart = ["item1", "item2", "item3"]
REMEMBER "shopping_cart", cart, "2 hours"

Permanent Storage

' Store important user information permanently
REMEMBER "account_created", NOW(), "forever"
REMEMBER "user_tier", "premium", "permanent"

Promotional Campaigns

' Track if user has seen a promotional message
has_seen = RECALL "promo_summer_2024"

IF has_seen = null THEN
    TALK "🎉 Special summer offer: 20% off all products!"
    REMEMBER "promo_summer_2024", true, "30 days"
END IF

Rate Limiting

' Simple rate limiting for API calls
call_count = RECALL "api_calls_today"

IF call_count = null THEN
    call_count = 0
END IF

IF call_count >= 100 THEN
    TALK "You've reached your daily API limit. Please try again tomorrow."
ELSE
    call_count = call_count + 1
    REMEMBER "api_calls_today", call_count, "24 hours"
    ' Process the API call
END IF

How It Works

1. Storage: Data is stored in the bot_memories database table with:

   • User ID and Bot ID association
   • JSON-serialized value
   • Creation timestamp
   • Optional expiration timestamp

2. Retrieval: When RECALL is called:

   • System checks if the key exists for the user/bot combination
   • Verifies the entry hasn’t expired
   • Returns the value or null if not found/expired

3. Automatic Cleanup: Expired entries are not returned and can be periodically cleaned up by maintenance tasks.

Database Schema

The REMEMBER keyword uses the following database structure:

CREATE TABLE bot_memories (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    bot_id TEXT NOT NULL,
    session_id TEXT,
    key TEXT NOT NULL,
    value JSONB NOT NULL,
    created_at TEXT NOT NULL,
    expires_at TEXT,
    UNIQUE(user_id, bot_id, key)
);

Comparison with Other Memory Keywords

Best Practices

1. Use descriptive keys: Choose meaningful key names like "last_login" instead of "ll".

2. Set appropriate durations: Match the duration to your use case:

   • Session data: minutes to hours
   • Preferences: weeks to months
   • Important data: forever

3. Handle null values: Always check if RECALL returns null:

   value = RECALL "some_key"
   IF value = null THEN
       ' Handle missing/expired data
   END IF
   

4. Avoid storing sensitive data: Don’t store passwords, API keys, or other secrets.

Error Handling

' REMEMBER returns a confirmation message on success
result = REMEMBER "key", "value", "1 day"
' result = "Remembered 'key' for 1 day"

' RECALL returns null if key doesn't exist or has expired
value = RECALL "nonexistent_key"
' value = null

Related Keywords

• SET USER MEMORY - Permanent user-scoped storage
• GET USER MEMORY - Retrieve permanent user data
• SET BOT MEMORY - Bot-wide storage
• GET BOT MEMORY - Retrieve bot-wide data

See Also

• Memory Management
• User Session Handling