What is a Memory Pack?
A Memory Pack is the compiled output of inject() — a deterministic snapshot of your agent's relevant context, ready for LLM injection.
Unlike vector similarity search that returns nearest neighbors, memory packs are assembled using scoring algorithms across multiple layers.
Architecture
┌─────────────┐ inject() ┌─────────────────┐
│ │ ←───────────────── │ │
│ Your App │ │ Elephantasm │
│ │ ─────────────────→ │ │
└─────────────┘ extract() └─────────────────┘
│
▼
┌───────────────┐
│ Dreamer │
│ (background) │
└───────────────┘
│
▼
Events → Memories → Knowledge → Identity
Pack Contents
A memory pack contains up to five layers:
| Layer | Purpose |
|---|---|
| Session Memories | Recent context from the current session |
| Long-Term Memories | Relevant past memories, scored by the four-factor system |
| Knowledge | Extracted insights and canonicalized truths |
| Identity | Agent personality, behavioral fingerprint |
| Temporal Context | Time-aware bridging (e.g., "3 days since last interaction") |
Using Memory Packs
from elephantasm import inject
pack = inject()
if pack:
# Full formatted prompt (all layers combined)
system_prompt = f"You are a helpful assistant.\n\n{pack.as_prompt()}"
# Access individual layers
print(pack.identity) # Identity context
print(pack.session_memories) # Recent session memories
print(pack.long_term_memories) # Relevant past memories
print(pack.knowledge) # Extracted insights
print(pack.temporal_context) # Time bridgingMemoryPack Structure
class MemoryPack:
session_memories: list[ScoredMemory] # Recent session context
long_term_memories: list[ScoredMemory] # Relevant past memories
knowledge: list[ScoredKnowledge] # Extracted insights
identity: IdentityContext # Agent personality
temporal_context: TemporalContext # Time-aware bridging
token_count: int # Current token usage
max_tokens: int # Token budget
def as_prompt(self) -> str: # Formatted for LLM injectionDeterministic Assembly
Memory packs are assembled deterministically — given the same state, the same pack is produced. The scoring algorithm:
- Selects memories based on four-factor scores (importance, confidence, recency, decay)
- Ranks by composite score
- Fits within the token budget (most relevant first)
- Compiles all layers into a structured prompt
inject() returns null/None when no memory packs exist yet (e.g., for a brand-new anima with no events). Always check for null before calling asPrompt().