Memory Tiers & Lifecycle
How memories are prioritized and how they age over time.
Not all memories are equally important. A critical business rule matters more than a passing observation from weeks ago. CrabShack uses a tier system to keep the most useful memories readily available while gradually archiving ones that are no longer relevant.
The Four Tiers
| Tier | Behavior | Best For |
|---|---|---|
| Hot | Always included in every conversation, regardless of topic | Your most important, frequently-used memories — core business rules, key preferences, critical facts |
| Warm | Included when the conversation topic is reasonably relevant | Recent and moderately-used memories that are still actively useful |
| Cold | Included only when the conversation is highly relevant | Older or less-used memories that might still be valuable in the right context |
| Archive | Never included in conversations | Memories preserved for your reference but no longer actively used by agents |
How Memories Move Between Tiers
New memories start in the Hot or Warm tier based on their importance. Over time, memories that aren't being used are automatically moved to lower tiers:
- Hot to Warm — after 7 days without being recalled, and fewer than 5 total uses
- Warm to Cold — after 30 days without being recalled
- Cold to Archive — after 90 days without being recalled
This means memories that continue to be relevant stay in higher tiers, while unused memories naturally fade into the background. The system is self-maintaining — you don't need to manually organize memories unless you want to.
You create a memory: "All invoices must include the project code." For the first few weeks, this memory is recalled frequently as your agent handles billing-related conversations. It stays in the Hot tier. Months later, your invoicing process changes and this memory stops being recalled. After 7 days of inactivity with fewer than 5 total uses, it moves to Warm. If it continues to go unused, it eventually moves to Cold and then Archive.
Manual Tier Overrides
You can move a memory to any tier manually from the Memory dashboard. This is useful when:
- You want to pin an important memory to the Hot tier so it's always available
- You want to archive a memory that's no longer relevant without waiting for the automatic transition
- You want to promote a Cold or Archived memory back to a higher tier because it's become relevant again
Manual tier changes override the automatic lifecycle. A memory you've pinned to Hot will stay there until you move it or it meets the automatic demotion criteria.
Why Tiers Matter
Your agent has a limited amount of context it can work with in any given conversation. If every memory were included every time, the agent would spend most of its context budget on memories rather than the actual conversation. The tier system ensures that:
- The most valuable memories always get priority
- Relevant memories are included when they matter
- Stale memories don't waste context space
The Hot tier limit (default: 20) controls how many memories can be in the always-included tier. You can adjust this in Configuration based on your needs — higher means more context from memories but less room for other content.
Memory Cap
CrabShack has a configurable limit on the total number of memories (default: 10,000). When this limit is approached, the system automatically archives the lowest-priority Cold memories to make room. This prevents unbounded growth while preserving your most valuable memories.
For most users, the default limit is more than sufficient. See Configuration to adjust it if needed.