What is a Memory?
A Memory is a structured reflection on one or more events. While events are raw data, memories are interpreted — they capture what mattered about an interaction.
Memories are created automatically by the Dreamer synthesis pipeline, which processes batches of events and generates concise, meaningful summaries.
Memory Properties
| Field | Type | Description |
|---|---|---|
summary | string | Compact narrative essence of the memory |
importance | float | Recall priority (0.0–1.0) |
confidence | float | Stability/certainty (0.0–1.0) |
state | enum | ACTIVE, DECAYING, or ARCHIVED |
time_start | datetime | When the source events began |
time_end | datetime | When the source events ended |
meta | object | Flexible metadata (topics, tags) |
Four-Factor Recall System
When assembling a memory pack, Elephantasm scores memories using four factors:
- Importance — How significant was this memory? Set by the synthesis pipeline based on content analysis.
- Confidence — How stable is this memory? New memories start with moderate confidence; repeated reinforcement increases it.
- Recency — How recent is this memory? More recent memories score higher, with exponential decay.
- Decay — How much has this memory faded? Unused memories gradually decay; recalled memories are reinforced.
The pack compiler combines these into a composite score to rank which memories make it into the context window.
Memory Lifecycle
Memories move through three states:
ACTIVE → DECAYING → ARCHIVED
- Active — Currently relevant. Included in memory pack scoring.
- Decaying — Losing relevance. Still scored but with a penalty.
- Archived — No longer active. Preserved for provenance but excluded from packs.
The Dreamer handles state transitions automatically based on access patterns and decay scores.
Provenance
Every memory links back to its source events via the MemoryEvent junction table. This creates a full audit trail:
- Which events contributed to a memory?
- How strong was each event's contribution? (
link_strength) - When was the link created?
Provenance is automatic. The synthesis pipeline creates links when it generates memories — no manual wiring needed.
How Memories Are Created
You don't create memories directly. The pipeline is:
- You call
extract()to capture events - The Dreamer runs periodically (or is triggered)
- It batches recent unsynthesized events
- An LLM generates structured memory summaries
- Memories are stored with importance/confidence scores
- Links to source events are recorded for provenance
The next inject() call will include these new memories in the compiled pack.