Understanding Memories
Memories are the fundamental building blocks of Memory OS. Learn how they work, what makes them special, and how to use them effectively.
What is a Memory?
A memory is a piece of information that your AI can store, retrieve, and reason about. Unlike traditional databases that store static data, memories are designed for AI systems that need to understand context, make connections, and evolve their understanding over time.
Think of memories as "smart data" - they're not just stored, they're understood.
Traditional Database Record
text: "User likes Python"
timestamp: 2024-01-15
Static data that requires exact matches to find.
Memory OS Memory
embedding: [0.1, -0.3, 0.8, ...]
connections: ["programming", "data"]
importance: 0.85
Semantic understanding that can be found by meaning, not just keywords.
Anatomy of a Memory
Core Components
Content
The actual information - text, facts, observations, or insights.
"Sarah prefers technical explanations and is working on API integration"Memory Type
Categorizes the memory for better organization and retrieval.
Semantic Embedding
A vector representation that captures the meaning, enabling semantic search.
[0.1, -0.3, 0.8, 0.2, ...] (1536 dimensions)Metadata
Additional context like timestamps, importance scores, and custom tags.
{
"timestamp": "2024-01-15T10:30:00Z",
"importance": 0.85,
"source": "chat_conversation",
"confidence": "high"
}Types of Memories
Different types of information require different handling. Memory OS supports various memory types, each optimized for specific use cases:
Conversation
Dialogue history, questions asked, and responses given.
"Assistant explained exponential backoff"
Preference
User preferences, communication styles, and personal choices.
"Likes dark mode interfaces"
Fact
Objective information, data points, and established knowledge.
"Company uses Python for backend"
Insight
Derived understanding, patterns, and synthesized knowledge.
"Prefers code examples over theory"
💡 Pro Tip: Custom Memory Types
You can create custom memory types for your specific use case: "research_finding", "bug_report", "feature_request", etc.
Memory Lifecycle
Memories aren't static - they have a lifecycle that mirrors how human memory works:
Creation
When new information is encountered, it's processed and stored as a memory with semantic embeddings.
memory_client.create_memory(
content="User prefers Python",
memory_type="preference"
)Retrieval
Memories are retrieved based on semantic similarity, not just keyword matching.
# Query: "programming languages"
# Finds: "User prefers Python" (semantic match)Reinforcement
Frequently accessed memories become stronger and more important over time.
# Each access increases importance score
importance: 0.5 → 0.7 → 0.85Decay
Unused memories gradually become less important, mimicking natural forgetting.
# Automatic decay over time
importance: 0.8 → 0.6 → 0.3 (if unused)The Power of Semantic Search
Traditional databases require exact matches. Memory OS understands meaning. This is what makes AI memory truly intelligent.
Traditional Search
Semantic Search
🔍 Real Example
A user asks: "What do you know about my coding preferences?"
Memory OS finds: "prefers Python", "likes clean code", "uses VS Code", "interested in machine learning" - even though none of these contain the exact words "coding preferences".
Memory in Action: Code Examples
Creating Memories
from memorystack import MemoryStackClient
# Initialize client
memory = MemoryStackClient(
api_key="your_api_key",
user_id="user_123"
)
# Store a conversation
memory.create_memory(
content="User asked about API rate limits and seemed confused",
memory_type="conversation",
metadata={
"topic": "api",
"sentiment": "confused",
"importance": 0.7
}
)
# Store a preference
memory.create_memory(
content="User prefers detailed technical explanations with code examples",
memory_type="preference",
metadata={
"category": "communication_style",
"confidence": "high"
}
)
# Store a fact
memory.create_memory(
content="User is a senior Python developer at TechCorp",
memory_type="fact",
metadata={
"verified": True,
"source": "user_profile"
}
)Searching Memories
# Semantic search - finds related concepts
results = memory.search_memories(
query="programming experience",
limit=5
)
# Filter by memory type
preferences = memory.search_memories(
query="communication",
memory_type="preference",
limit=3
)
# Search with metadata filters
recent_conversations = memory.search_memories(
query="API questions",
memory_type="conversation",
metadata_filter={
"topic": "api",
"timestamp": "> 2024-01-01"
}
)
# Process results
for result in results['results']:
print(f"Content: {result['content']}")
print(f"Relevance: {result['relevance_score']}")
print(f"Type: {result['memory_type']}")
print("---")Building Context for AI
def get_user_context(user_message: str) -> str:
"""Build rich context for AI responses"""
# Get relevant memories
memories = memory.search_memories(
query=user_message,
limit=10
)
# Organize by type
context = {
"preferences": [],
"facts": [],
"recent_conversations": []
}
for mem in memories['results']:
mem_type = mem['memory_type']
if mem_type == "preference":
context["preferences"].append(mem['content'])
elif mem_type == "fact":
context["facts"].append(mem['content'])
elif mem_type == "conversation":
context["recent_conversations"].append(mem['content'])
# Build context string
context_str = f"""
User Preferences:
{chr(10).join(context['preferences'])}
Known Facts:
{chr(10).join(context['facts'])}
Recent Conversations:
{chr(10).join(context['recent_conversations'][:3])}
"""
return context_str
# Use in AI prompt
user_message = "Can you help me with authentication?"
context = get_user_context(user_message)
ai_prompt = f"""
Context about the user:
{context}
User's current question: {user_message}
Provide a helpful response that takes into account their preferences and background.
"""Best Practices
✅ Do
- • Use descriptive, natural language content
- • Include relevant metadata for filtering
- • Choose appropriate memory types
- • Store both user input and AI responses
- • Use semantic search for better retrieval
❌ Don't
- • Store raw data without context
- • Use overly technical or cryptic content
- • Ignore memory types (use "general" sparingly)
- • Store duplicate information unnecessarily
- • Rely only on keyword-based searches
💡 Pro Tips
Quality over Quantity: Better to have fewer, well-crafted memories than many low-quality ones.
Context is King: Include enough context so the memory makes sense when retrieved later.
Metadata Matters: Rich metadata enables powerful filtering and organization.
Test Your Queries: Regularly test how well your memories are retrieved with different queries.