Ensoul

Memory System

Ensoul's memory system enables personas to maintain coherent, contextual conversations that can span multiple sessions. Through semantic search, personas remember not just what was said, but what it meant.

★

Semantic Understanding

Personas recall memories based on meaning, not keyword matching. When a user mentions "planning a trip," the system retrieves related travel preferences, past destinations, and expressed interests — even if those exact words were never used.

Three-Tier Architecture

Memory is organized into three complementary tiers, each serving a distinct purpose in maintaining persona continuity and contextual awareness.

Tier 1Short-Term
Sliding window of recent turns
max 20 turns
Tier 2Working
Active topic, entities, emotional tone
live state
Tier 3Long-Term
Persistent facts via semantic vectors
384-dim embeddings
Consolidation extracts & embeds key information

Short-Term Memory

Recent conversation turns in a sliding window. Provides immediate context for the current conversation.

Working Memory

Current topic, tracked entities, emotional tone, and conversation state. The persona's active mental context.

Long-Term Memory

Persistent facts, preferences, and experiences with semantic search. Enables cross-session continuity.

Short-Term Memory

A sliding window buffer that maintains recent conversation context within token limits. Automatically truncates old turns when the buffer is full. This provides the immediate context that makes conversations feel natural.

Short-term memory is managed automatically. The system maintains a window of recent conversation turns to keep responses contextually grounded.

Working Memory

Tracks the current conversation state: topics, entities, user intent, and emotional context. This is the persona's active mental model of the ongoing interaction.

Working memory maintains the persona's active awareness — what's being discussed, who's involved, the emotional tone, and what the user seems to need. This updates in real-time as the conversation flows.

Long-Term Memory

Persistent storage for facts, preferences, and experiences. Each memory is embedded as a vector for semantic search, enabling retrieval based on meaning rather than exact keyword matches.

Memory Types

FACTLearned facts about the user
PREFERENCELikes, dislikes, and tendencies
EXPERIENCEPast interaction summaries
ENTITYPeople, places, things mentioned
TOPICTopics discussed over time
EMOTIONALEmotional context and reactions

Importance Levels

CRITICALNever forget (name, key relationships)
HIGHCore preferences and goals
MEDIUMGeneral facts and experiences
LOWTransient mentions

Bloom Modes

Ensoul offers three memory generation modes (called "bloom modes") that control the depth and cost of memory generation:

Fast

Instant extraction, no cost. Best for high-volume scenarios.

Enhanced

Intelligent extraction with good quality/cost balance. Captures facts, entities, and emotional context.

Premium

Deep extraction with nuanced understanding. Best for high-value conversations.

You can configure the default bloom mode per domain or select it per batch job in the Studio UI under Memories > Generate Batch.

Shared Memories

When personas interact (via multi-chat or simulations), they can form shared memories — dual-perspective records of the same interaction. Each persona stores their own perspective of the shared event.

•
Dual perspective: Each participant stores their own interpretation of the interaction
•
Relationship building: Shared memories create bonds between personas that influence future interactions
•
Network effects: Over time, shared memories form a social network that can be visualized and analyzed

Memory Consolidation

When short-term memory grows large, consolidation extracts important information and stores it in long-term memory. This process:

Consolidation automatically distills important information — facts, preferences, relationships, and emotional context — from conversations into long-term storage.

  • Extracts key facts, preferences, and relationships from conversation history
  • Generates a rolling summary of the conversation
  • Embeds extracted memories for future semantic search
  • Clears the short-term buffer to make room for new interactions

Best Practices

Choose appropriate bloom modes
Use Fast for bulk generation, Enhanced for general use, Premium for high-value conversations.
Let consolidation happen naturally
The system consolidates automatically when buffers fill. Don't manually trigger it unless you have a specific reason.
Set appropriate importance levels
Reserve HIGH/CRITICAL for information that should persist indefinitely. User's name should be CRITICAL; general topics should be LOW.
Monitor memory usage
In Studio, view individual persona memory pages to see what's being retained and adjust bloom modes as needed.

Next Steps

Core Concepts
Understand domains, personas, and evolution
Domain Architecture
Configure memory templates per domain
How It Works
See memory in the full inference pipeline
API Reference
Memory management via REST API