Memories

The actual data—where the magic happens 🧠

Memories are pieces of information stored by a bot. This is where you store everything your AI needs to remember.

Create Memory

memory = client.memories.create({
    'bot_id': 'bot_xyz789',
    'content': 'User prefers Python and loves clean code'
})

print(f"Memory ID: {memory['id']}")

Search Memories (Semantic)

The most powerful feature 🔍

results = client.memories.search({
    'bot_id': 'bot_xyz789',
    'query': 'programming language preferences',
    'limit': 5  # Top 5 most relevant
})

for result in results:
    print(f"- {result['content']}")

Magic: Semantic search understands meaning, not just keywords!

# You stored: "User loves Python and FastAPI"
# You can find with ANY of these:
"programming language""favorite framework""tech stack""what does user like"

List Memories

# All memories for a bot
memories = client.memories.list({
    'bot_id': 'bot_xyz789'
})

print(f"Total: {len(memories)}")

Get Memory

memory = client.memories.get('mem_123456')
print(memory['content'])

Update Memory

updated = client.memories.update({
    'id': 'mem_123456',
    'content': 'Updated content here'
})

Delete Memory

client.memories.delete('mem_123456')

Best Practices

Write Natural Language

# ✅ Good - Natural and searchable
client.memories.create({
    'bot_id': bot_id,
    'content': 'Sarah from Acme Corp is the CTO, interested in API integration, prefers technical docs, timezone EST'
})

# ❌ Bad - Too structured  
client.memories.create({
    'bot_id': bot_id,
    'content': 'name:Sarah;company:Acme;role:CTO'
})

Include Context

# ✅ Good - Has who, what, when, why
client.memories.create({
    'bot_id': bot_id,
    'content': 'Customer John reported slow API on 2025-01-15 at 3PM EST. Issue was database timeout. Fixed by adding index.'
})

# ❌ Bad - Missing context
client.memories.create({
    'bot_id': bot_id,
    'content': 'API slow'
})

Don't Store Sensitive Data

# ❌ Bad - Never store passwords/keys!
client.memories.create({
    'bot_id': bot_id,
    'content': 'User password: hunter2'
})

# ✅ Good - Store references
client.memories.create({
    'bot_id': bot_id,
    'content': 'User has password set, last changed 2025-01-15'
})

Common Patterns

User Preferences

def store_user_preference(bot_id: str, preference: str):
    """Store a user preference"""
    return client.memories.create({
        'bot_id': bot_id,
        'content': f"User preference: {preference}"
    })

def get_user_preferences(bot_id: str):
    """Get all preferences"""
    return client.memories.search({
        'bot_id': bot_id,
        'query': 'user preferences',
        'limit': 10
    })

Conversation History

def add_to_conversation(bot_id: str, role: str, message: str):
    """Store conversation message"""
    return client.memories.create({
        'bot_id': bot_id,
        'content': f"[{role}]: {message}"
    })

def get_conversation_context(bot_id: str, topic: str):
    """Get relevant conversation history"""
    return client.memories.search({
        'bot_id': bot_id,
        'query': topic,
        'limit': 5
    })

Knowledge Base

def add_knowledge(bot_id: str, category: str, content: str):
    """Add to knowledge base"""
    return client.memories.create({
        'bot_id': bot_id,
        'content': f"[{category}] {content}"
    })

def search_knowledge(bot_id: str, question: str):
    """Search knowledge base"""
    return client.memories.search({
        'bot_id': bot_id,
        'query': question,
        'limit': 3
    })

Advanced Usage

Batch Create

from concurrent.futures import ThreadPoolExecutor

memories_to_store = [
    "User loves Python",
    "User prefers dark mode",
    "User timezone is EST"
]

def store_memory(content):
    return client.memories.create({
        'bot_id': bot_id,
        'content': content
    })

with ThreadPoolExecutor(max_workers=5) as executor:
    results = list(executor.map(store_memory, memories_to_store))

print(f"Stored {len(results)} memories")
def smart_search(bot_id: str, query: str, min_relevance: float = 0.7):
    """Search with relevance filtering"""
    results = client.memories.search({
        'bot_id': bot_id,
        'query': query,
        'limit': 20
    })
    
    # Filter by relevance (if SDK provides scores)
    # For now, just return top results
    return results[:5]

Memory Management

def cleanup_old_memories(bot_id: str, days_old: int = 30):
    """Delete memories older than X days"""
    from datetime import datetime, timedelta
    
    cutoff = datetime.now() - timedelta(days=days_old)
    memories = client.memories.list({'bot_id': bot_id})
    
    deleted = 0
    for memory in memories:
        created = datetime.fromisoformat(memory['created_at'])
        if created < cutoff:
            client.memories.delete(memory['id'])
            deleted += 1
    
    print(f"Deleted {deleted} old memories")

Memory Limits

  • Size: Up to 10KB per memory
  • Count: Unlimited memories per bot
  • Search: Up to 100 results per query

Tips & Tricks

  1. Store summaries, not raw data - Compress large content
  2. Use semantic search liberally - It's smarter than you think
  3. Include timestamps - "on 2025-01-15" helps with context
  4. Be specific - "User prefers dark mode" > "User likes dark"
  5. Test your queries - Make sure you can find what you store

Next: Async Usage → | Examples →