🗄️ Traylinx Cortex - Database Schema & Data Flow¶
Version: 2.1.0
Last Updated: December 3, 2025
📚 Navigation: Main README | Docs Index | Quick Reference | Integration Guide
This document provides visual diagrams of the database structure and data flows in Traylinx Cortex.
📊 Entity Relationship Diagram (ERD)¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ TRAYLINX CORTEX DATABASE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ sessions │ │ langgraph_ │ │
│ ├─────────────────────┤ │ checkpoints │ │
│ │ PK id (UUID) │◄───────►├─────────────────────┤ │
│ │ user_id │ 1:1 │ PK thread_id │◄── Maps to session_id │
│ │ app_id │ │ checkpoint (JSONB)│ │
│ │ agent_id │ │ created_at │ │
│ │ title │ │ updated_at │ │
│ │ created_at │ └─────────────────────┘ │
│ │ updated_at │ │
│ │ metadata (JSONB) │ │
│ └──────────┬──────────┘ │
│ │ │
│ │ 1:N │
│ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ messages │ │ memories │ │
│ ├─────────────────────┤ ├─────────────────────┤ │
│ │ PK id (UUID) │◄────────────────►│ PK id (UUID) │ │
│ │ FK session_id │ N:1 │ user_id │ │
│ │ role │ │ app_id │ │
│ │ content │ │ content │ │
│ │ content_sanitized│ │ embedding (1024) │◄── pgvector │
│ │ token_count │ │ FK source_message_id│ │
│ │ created_at │ │ importance_score │ │
│ └──────────┬──────────┘ │ valid_at │ │
│ │ │ tags[] │ │
│ │ N:1 │ created_at │ │
│ ▼ └─────────────────────┘ │
│ ┌─────────────────────┐ │
│ │ usage_logs │ │
│ ├─────────────────────┤ │
│ │ PK id (UUID) │ │
│ │ FK session_id │ │
│ │ user_id │ │
│ │ model │ │
│ │ tokens_in │ │
│ │ tokens_out │ │
│ │ cost_usd │ │
│ │ created_at │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
🔴 Redis Short-Term Memory (STM)¶
┌─────────────────────────────────────────────────────────────┐
│ REDIS (STM Cache) │
├─────────────────────────────────────────────────────────────┤
│ │
│ Key Pattern: session:{session_id}:messages │
│ Data Type: LIST │
│ TTL: 24 hours (auto-expire) │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Example Data: │ │
│ │ │ │
│ │ [ │ │
│ │ { │ │
│ │ "role": "user", │ │
│ │ "content": "Hello, my name is Sebastian", │ │
│ │ "tokens": 7 │ │
│ │ }, │ │
│ │ { │ │
│ │ "role": "assistant", │ │
│ │ "content": "Hi Sebastian! How can I help?", │ │
│ │ "tokens": 9 │ │
│ │ }, │ │
│ │ { │ │
│ │ "role": "user", │ │
│ │ "content": "I'm planning a trip to Tokyo", │ │
│ │ "tokens": 8 │ │
│ │ } │ │
│ │ ] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Operations: │
│ • RPUSH - Append new message │
│ • LRANGE - Get recent messages (token-bounded) │
│ • DEL - Clear session STM │
│ • EXPIRE - Set 24h TTL │
│ │
└─────────────────────────────────────────────────────────────┘
🔄 Data Flow Diagram¶
Chat Request Flow¶
┌──────────────────────────────────────────────────────────────────────────────────────┐
│ CHAT REQUEST FLOW │
└──────────────────────────────────────────────────────────────────────────────────────┘
┌──────────┐
│ Client │
└────┬─────┘
│
│ POST /v1/chat
│ {session_id, message, user_id}
▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ CORTEX API (FastAPI) │
│ │
│ 1. Validate Sentinel token │
│ 2. Check session exists │
│ 3. Scrub PII from message │
└──────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ LANGGRAPH ORCHESTRATOR │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ RETRIEVE │───►│ AUGMENT │───►│ CALL │───►│ SAVE │ │
│ │ MEMORY │ │ PROMPT │ │ MODEL │ │ STATE │ │
│ └──────┬──────┘ └─────────────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Redis (STM) │ │ LiteLLM │ │ PostgreSQL │ │
│ │ PostgreSQL │ │ ┌───────┐ │ │ (messages) │ │
│ │ (LTM) │ │ │GPT-4o │ │ │ │ │
│ └─────────────┘ │ │Claude │ │ │ Redis (STM) │ │
│ │ │Llama │ │ └─────────────┘ │
│ │ └───────┘ │ │
│ └─────────────┘ │
│ │ │
│ ┌─────────────┐◄───────────────────────────────────────────────┘ │
│ │ ENQUEUE │ │
│ │CONSOLIDATION│───► Celery Task Queue │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────┐
│ RESPONSE TO CLIENT │
│ │
│ Streaming (SSE): │
│ event: message │
│ data: {"chunk": "Sure", "id": "..."}│
│ │
│ event: done │
│ data: {"status": "completed", ...} │
└───────────────────────────────────────┘
Background Consolidation Flow¶
┌──────────────────────────────────────────────────────────────────────────────────────┐
│ BACKGROUND CONSOLIDATION FLOW │
└──────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ Celery Worker │
└────────┬────────┘
│
│ consolidate_memory task
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ Step 1: CHECK TOKEN BUDGET │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ SELECT SUM(token_count) FROM messages WHERE session_id = ? │ │
│ │ │ │
│ │ if total_tokens > 4000: │ │
│ │ → Summarize oldest 50% of messages │ │
│ │ → Archive summary to LTM │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 2: EXTRACT FACTS │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Prompt to GPT-4o-mini: │ │
│ │ "Extract facts about the user from this conversation..." │ │
│ │ │ │
│ │ Output: ["User's name is Sebastian", "Planning trip to Tokyo"] │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 3: GENERATE EMBEDDINGS │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ For each fact: │ │
│ │ embedding = embed(fact, model=EMBEDDING_MODEL) │ │
│ │ → Vector dimensions based on model (default: 1024) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 4: STORE IN MEMORIES TABLE │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ INSERT INTO memories (user_id, app_id, content, embedding, ...) │ │
│ │ VALUES (?, ?, ?, ?, ...) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 5: GENERATE SESSION TITLE (if missing) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ if session.title IS NULL: │ │
│ │ title = GPT-4o-mini("Generate 3-5 word title...") │ │
│ │ UPDATE sessions SET title = ? WHERE id = ? │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
📝 Table Relationships¶
| From | To | Relationship | Foreign Key | Description |
|---|---|---|---|---|
sessions |
messages |
1:N | messages.session_id |
One session has many messages |
sessions |
usage_logs |
1:N | usage_logs.session_id |
One session has many usage records |
sessions |
langgraph_checkpoints |
1:1 | thread_id = session_id |
LangGraph state persistence |
messages |
memories |
1:N | memories.source_message_id |
One message can generate multiple facts |
🔑 Key Design Decisions¶
1. Multi-Tenancy¶
Both sessions and memories include app_id to isolate data between different applications using Cortex.
-- All queries must filter by app_id
SELECT * FROM memories
WHERE user_id = ? AND app_id = ?
ORDER BY embedding <=> query_embedding
LIMIT 10;
2. Dual Content Storage¶
Messages store both original and sanitized content:
- content - Original message (encrypted at rest)
- content_sanitized - PII-redacted version (used for LLM and search)
3. User-Scoped Long-Term Memory¶
Memories are tied to user_id, NOT session_id:
- Facts persist across multiple conversations
- User can start new session but AI still remembers them
Session 1: "My name is Sebastian" → Memory created for user_123
Session 2: "What is my name?" → Memory retrieved → "Sebastian"
4. Vector Search with pgvector¶
The memories.embedding column uses:
- Dimension: Configurable via EMBEDDING_DIMENSIONS env var (default: 1024 for mistral-embed)
- Index: HNSW (Hierarchical Navigable Small World)
- Distance: Cosine similarity
Common embedding dimensions by model:
- mistral-embed: 1024 (default)
- text-embedding-004 (Gemini): 768
- text-embedding-3-small (OpenAI): 1536
- text-embedding-3-large (OpenAI): 3072
-- Fast approximate nearest neighbor search
SELECT content, 1 - (embedding <=> query_embedding) AS similarity
FROM memories
WHERE user_id = ? AND app_id = ?
ORDER BY embedding <=> query_embedding
LIMIT 10;
5. Redis for Hot Data¶
Short-Term Memory uses Redis LIST: - Speed: Sub-millisecond read/write - TTL: 24 hours auto-expire for inactive sessions - Token Budgeting: Load messages until 4,000 token limit reached
📊 Index Summary¶
| Table | Index | Type | Purpose |
|---|---|---|---|
sessions |
idx_sessions_user |
B-tree | Fast user lookup |
messages |
idx_messages_session |
B-tree | Fast message retrieval |
memories |
idx_memories_embedding |
HNSW | Vector similarity search |
memories |
idx_memories_user |
B-tree | Fast user lookup |
usage_logs |
idx_usage_user_date |
B-tree | Cost reporting queries |
🔒 Data Lifecycle¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DATA LIFECYCLE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Redis STM ──────────────────────────────────────────────────────────────────► │
│ │ Expires after 24h │
│ │ │
│ │ PostgreSQL messages ─────────────────────────────────────────────────────► │
│ │ │ Deleted when session expires │
│ │ │ (30 days inactive) │
│ │ │ │
│ │ │ PostgreSQL memories ──────────────────────────────────────────────────► │
│ │ │ Persists forever (user facts) │
│ │ │ │
│ │ │ PostgreSQL usage_logs ────────────────────────────────────────────────► │
│ │ │ Retained for billing/analytics │
│ │ │ │
│ └──┴──────────────────────────────────────────────────────────────────────────┘│
│ │
│ Timeline: │
│ ├─ 0h: Message received, stored in Redis + PostgreSQL │
│ ├─ 0h: Background job extracts facts → memories table │
│ ├─ 24h: Redis STM expires (PostgreSQL backup remains) │
│ ├─ 30d: Session deleted (messages + usage_logs cascade deleted) │
│ └─ ∞: Memories persist (user knowledge base) │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
See Also: - specs_v2_final.md - Complete SQL DDL statements - implementation_plan_v2_final.md - Migration scripts - ./QUICK_REFERENCE.md - Schema summary table
**[← Integration Guide](././integration_guide.md)** | **[Docs Index](./README.md)** | **[Main README](../README.md)**