Memory Lifecycle
Memories aren't static - they evolve over time, just like human memory. Learn how memories are created, reinforced, decay, and eventually forgotten.
The Lifecycle Journey
Memorystack mimics how human memory works. Important memories get stronger with use, while unused memories gradually fade. This creates a natural, adaptive memory system that focuses on what matters.
Stage 1: Creation
When new information is encountered, it's stored as a memory with an initial importance score. The system automatically generates embeddings and extracts metadata.
Creating a Memory
from memorystack import MemoryStackClient
client = MemoryStackClient(api_key="your_api_key")
# Create a new memory
result = client.add(
"User prefers detailed technical explanations",
user_id="user_123",
metadata={
"type": "preference",
"category": "communication_style",
"confidence": "high"
}
)
# Initial state
print(f"Memory ID: {result['id']}")
print(f"Created: {result['created_at']}") # NowInitial Properties
- • Importance: 0.5 (neutral starting point)
- • Access Count: 0 (never accessed)
- • Last Accessed: null
- • Decay Rate: Standard (configurable)
Stage 2: Reinforcement
Each time a memory is accessed (retrieved in search results, explicitly fetched, or used in context), it gets stronger. The importance score increases, making it more likely to be retrieved in the future.
How Reinforcement Works
Manual Reinforcement
# Automatic reinforcement happens when:
# 1. Memory appears in search results
results = client.search("preferences", user_id="user_123")
# ✓ All returned memories are automatically reinforced
# 2. Memory is explicitly retrieved
memories = client.list_memories(user_id="user_123")
# ✓ Accessed memories are tracked
# 3. Memory is used in AI context
# ✓ Memories used in prompts are tracked and reinforced
# The system automatically tracks access patterns
# and adjusts importance scores accordinglyStage 3: Decay
Memories that aren't accessed gradually lose importance. This mimics natural forgetting and ensures your memory system stays focused on relevant information.
Decay Over Time
⚙️ Configurable Decay
Decay rates can be customized per memory type or globally. Critical memories can have slower decay rates.
# Mark critical memories with metadata
client.add(
"Critical system configuration",
user_id="user_123",
metadata={
"type": "credential",
"priority": "critical"
}
)Stage 4: Archival & Cleanup
When memories reach very low importance (< 0.1), they can be automatically archived or deleted. This keeps your memory system clean and focused.
Automatic Maintenance
# List memories to review for cleanup
memories = client.list_memories(user_id="user_123", limit=100)
# Identify old or low-value memories
for mem in memories['memories']:
created = mem.get('created_at')
# Check if memory is old or rarely accessed
# Then delete if needed
if should_cleanup(mem):
client.delete_memory(memory_id=mem['id'])
print(f"Deleted: {mem['id']}")
# The system also runs automatic maintenance
# to consolidate similar memories and manage storageArchive
Memories are moved to cold storage but can be restored if needed.
Delete
Memories are permanently removed from the system.
Lifecycle Management
Complete Example
from memorystack import MemoryStackClient
client = MemoryStackClient(api_key="your_api_key")
# 1. Create memory
mem = client.add(
"User prefers Python",
user_id="user_123",
metadata={"type": "preference"}
)
print(f"Created memory: {mem['id']}")
# 2. Use memory (automatic reinforcement)
results = client.search("programming", user_id="user_123")
# Memory is automatically reinforced when retrieved
# 3. Check memory stats
stats = client.get_stats(user_id="user_123")
print(f"Total memories: {stats['totals']['total_memories']}")
# 4. List memories to review
memories = client.list_memories(user_id="user_123", limit=20)
for m in memories['memories']:
print(f" - {m['content'][:50]}...")
# 5. Update a memory if needed
client.update_memory(
memory_id=mem['id'],
content="User strongly prefers Python for all projects"
)
# 6. Delete old memories when needed
# client.delete_memory(memory_id="old_mem_id")Best Practices
✅ Do
- • Enable automatic maintenance
- • Monitor memory health regularly
- • Set appropriate decay rates per type
- • Archive before deleting
- • Track important memories manually
❌ Don't
- • Let memories accumulate indefinitely
- • Use same decay rate for all types
- • Delete without archiving first
- • Ignore low-importance memories
- • Over-reinforce everything