Memory Architecture¶

Overview¶

Archety uses Supermemory as its primary memory service, with mem0 available as a legacy fallback. The memory system provides persistent, cross-session context for AI personas to remember user information, trips, preferences, and conversation history.

Why Supermemory Over mem0¶

We migrated from mem0 to Supermemory in December 2025. Here's the comparison:

Feature	Supermemory	mem0
Latency	<300ms (25x faster)	2-8 seconds
User Profiles	Built-in static/dynamic facts	Manual implementation
Knowledge Graph	Automatic entity relationships	Not available
Smart Forgetting	Automatic temporal decay	Manual cleanup
Container Tags	Multi-dimensional filtering	Single namespace string
Token Limits	More generous	100k tokens, 2k metadata
Cost	Competitive	Higher at scale

Key Benefits¶

User Profiles for Cross-Session Context
Supermemory automatically maintains user profiles with static facts (name, preferences) and dynamic facts (current activities, trips)
This solves the "Sage forgets my trip the next day" problem
Profiles are injected into system prompts for every conversation
Knowledge Graph
Automatic entity extraction and relationship mapping
"User mentioned friend Sarah who lives in Tokyo" creates linked entities
Better context retrieval for complex queries
Performance
Sub-300ms latency vs 2-8 second waits with mem0
Better user experience, especially for real-time chat
Container Tags
More flexible than single namespace strings
Can filter by multiple dimensions: ["user_+15551234567", "persona_sage", "type_trip"]

Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
├─────────────────────────────────────────────────────────────┤
│  TwoStageHandler    TripPlanner    GroupFeatures            │
│       │                 │               │                    │
│       └────────────────┼───────────────┘                    │
│                        ▼                                     │
│              get_memory_service()                            │
│                        │                                     │
│         ┌──────────────┼──────────────┐                     │
│         ▼              │              ▼                      │
│  SupermemoryService    │      MemoryService (mem0)          │
│  (Primary)             │      (Legacy Fallback)             │
│         │              │              │                      │
└─────────┼──────────────┼──────────────┼─────────────────────┘
          │              │              │
          ▼              │              ▼
   Supermemory API       │        mem0 API
                         │
              Feature Flag: use_supermemory

Service Selection¶

The memory service is selected based on configuration in app/config.py:

# Feature flag (default: True)
use_supermemory: bool = True

# API keys
supermemory_api_key: Optional[str] = None  # Primary
mem0_api_key: Optional[str] = None         # Fallback

Selection logic in app/memory/__init__.py: 1. If use_supermemory=True AND supermemory_api_key is set → Use Supermemory 2. Else if mem0_api_key is set → Use mem0 (legacy) 3. Else → Raise error

Namespace Isolation¶

Supermemory (Container Tags)¶

# Direct messages: user + persona isolation
container_tags = ["user_+15551234567", "persona_sage"]

# Group chats: group-level isolation
container_tags = ["group_iMessage;+;chat123456"]

mem0 (Legacy - Namespace Strings)¶

# Direct: "{user_id}_{persona_id}"
namespace = "+15551234567_sage"

# Group: "group_{chat_guid}"
namespace = "group_iMessage;+;chat123456"

Key Features¶

1. User Profiles (Supermemory Only)¶

# Get user profile for system prompt injection
profile = memory_service.get_user_profile(
    user_id="+15551234567",
    persona_id="sage"
)

# Returns structured profile:
{
    "static_facts": ["Name: John", "Lives in: San Francisco"],
    "dynamic_facts": ["Planning trip to Tokyo (Dec 10-15)"],
    "interests": ["photography", "Japanese food"],
    "preferences": ["prefers morning messages"]
}

2. Trip Memory Persistence¶

# Save trip to user profile for cross-session recall
memory_service.add_trip_memory(
    user_id="+15551234567",
    persona_id="sage",
    trip_destination="Tokyo",
    trip_dates="Dec 10-15, 2025",
    venue_count=12,
    trip_id="session_abc123"
)

3. Memory Search¶

# Search with semantic similarity
results = memory_service.search_memories(
    query="coffee preferences",
    user_id="+15551234567",
    persona_id="sage",
    limit=5
)

Configuration¶

Environment Variables¶

# Supermemory (Primary)
SUPERMEMORY_API_KEY=sm_your_api_key_here
USE_SUPERMEMORY=true  # Feature flag

# mem0 (Legacy Fallback)
MEM0_API_KEY=your_mem0_key  # Optional, for fallback

Railway Setup¶

# Set Supermemory key
railway variables set SUPERMEMORY_API_KEY=sm_your_key

# Optional: Keep mem0 as fallback
railway variables set MEM0_API_KEY=your_mem0_key

Ingestion Safeguards¶

To prevent oversized payloads (learned from mem0 incidents):

Text Limits: Summarizes text above 8k chars with head/tail excerpt
Metadata Limits: Prunes metadata above ~1.9k chars
Logging: Warns when truncation occurs for debugging
Async Processing: Large artifacts processed in background

See app/memory/supermemory_service.py for implementation.

Migration Guide¶

From mem0 to Supermemory¶

Set API Key:
```
export SUPERMEMORY_API_KEY=sm_your_key
```
Enable Feature Flag (already default):
```
use_supermemory: bool = True
```
Deploy: Existing mem0 memories remain accessible via fallback

Backward Compatibility¶

get_memory_service() returns whichever service is active
Both services implement the same interface
Fallback to mem0 if Supermemory unavailable

Files¶

File	Purpose
`app/memory/__init__.py`	Factory function, service selection
`app/memory/supermemory_service.py`	Supermemory implementation
`app/memory/event_tracker.py`	Proactive "I Remember" event detection
`app/memory/query_synthesizer.py`	Multi-query auxiliary question generation
`app/memory/memory_maintenance.py`	Nightly deduplication service
`app/memory/mem0_service.py`	mem0 legacy implementation
`app/config.py`	Configuration and feature flags

EVENT_TRACKER.md - Proactive "I Remember" moments
MULTI_QUERY_MEMORY.md - Tolan-inspired memory retrieval
MEMORY_DEDUPLICATION.md - Nightly cleanup

Testing¶

# Test memory service initialization
python -c "
from app.memory import get_memory_service
service = get_memory_service()
print(f'Using: {type(service).__name__}')
"

# Expected output with Supermemory configured:
# Using: SupermemoryService

Troubleshooting¶

"No memory service configured"¶

Ensure either SUPERMEMORY_API_KEY or MEM0_API_KEY is set

Falling back to mem0 unexpectedly¶

Check SUPERMEMORY_API_KEY is set correctly
Check USE_SUPERMEMORY is not set to false

Slow memory operations¶

Supermemory should be <300ms
If using mem0 fallback, 2-8s is expected

Last Updated: December 2025 Migration Status: Supermemory is primary, mem0 is legacy fallback