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
memory = MemoryStackClient(
api_key="your_api_key",
user_id="user_123"
)
# Create a new memory
result = memory.create_memory(
content="User prefers detailed technical explanations",
memory_type="preference",
metadata={
"category": "communication_style",
"confidence": "high"
}
)
# Initial state
print(f"Importance: {result['importance']}") # 0.5 (default)
print(f"Access count: {result['access_count']}") # 0
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
# Explicitly reinforce a memory
memory.reinforce_memory(
memory_id="mem_123",
boost=0.1 # Increase importance by 0.1
)
# Automatic reinforcement happens when:
# 1. Memory appears in search results
results = memory.search_memories(query="preferences")
# ✓ All returned memories are automatically reinforced
# 2. Memory is explicitly retrieved
mem = memory.get_memory(memory_id="mem_123")
# ✓ Memory is reinforced
# 3. Memory is used in AI context
# ✓ Memories used in prompts are tracked and reinforcedStage 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.
# Set custom decay rate
memory.create_memory(
content="Critical system password",
memory_type="credential",
metadata={
"decay_rate": 0.01 # Very slow decay
}
)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
# Configure auto-maintenance
memory.configure_auto_maintenance(
enabled=True,
schedule="daily", # Run daily cleanup
min_importance=0.1, # Archive below this threshold
action="archive" # or "delete"
)
# Manual cleanup
result = memory.cleanup_memories(
min_importance=0.15,
older_than_days=90,
action="archive"
)
print(f"Archived: {result['archived_count']} memories")
print(f"Deleted: {result['deleted_count']} memories")Archive
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 memory_os import MemoryOSClient
memory = MemoryOSClient(
api_key="your_api_key",
user_id="user_123"
)
# 1. Create memory
mem = memory.create_memory(
content="User prefers Python",
memory_type="preference"
)
print(f"Created with importance: {mem['importance']}")
# 2. Use memory (automatic reinforcement)
results = memory.search_memories(query="programming")
# Memory is automatically reinforced when retrieved
# 3. Manual reinforcement for critical info
memory.reinforce_memory(
memory_id=mem['id'],
boost=0.2
)
# 4. Check memory health
stats = memory.get_memory_stats()
print(f"Average importance: {stats['avg_importance']}")
print(f"Decaying memories: {stats['decaying_count']}")
# 5. Run maintenance
memory.run_maintenance(
decay_memories=True,
consolidate_duplicates=True,
archive_old=True
)
# 6. Monitor lifecycle
timeline = memory.get_memory_timeline(
memory_id=mem['id']
)
for event in timeline:
print(f"{event['timestamp']}: {event['action']}")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