┌─────────────────────────────────────────────────────────────────────────┐
│                           CLIENT APPLICATIONS                            │
│                  (Chat apps, IDEs, Voice assistants, etc.)              │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         HYPERTHYME API GATEWAY                           │
│                                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │    REST     │  │   GraphQL   │  │     MCP     │  │  WebSocket  │    │
│  │  Endpoints  │  │  Endpoints  │  │   Server    │  │   (Stream)  │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         HYPERTHYME CORE ENGINE                           │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                      MIDDLEWARE ORCHESTRATOR                       │  │
│  │                                                                   │  │
│  │  • Request routing          • Context assembly                    │  │
│  │  • User session management  • Token budget management             │  │
│  │  • Logging coordination     • Response handling                   │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                  │                                      │
│         ┌────────────────────────┼────────────────────────┐            │
│         ▼                        ▼                        ▼            │
│  ┌─────────────┐         ┌─────────────┐         ┌─────────────┐       │
│  │   LOGGER    │         │  RETRIEVER  │         │  INJECTOR   │       │
│  │             │         │             │         │             │       │
│  │ • Capture   │         │ • Search    │         │ • Build     │       │
│  │ • Parse     │         │ • Rank      │         │ • Format    │       │
│  │ • Store     │         │ • Expand    │         │ • Inject    │       │
│  └─────────────┘         └─────────────┘         └─────────────┘       │
│         │                        │                        │            │
└─────────┼────────────────────────┼────────────────────────┼────────────┘
          │                        │                        │
          ▼                        ▼                        ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           DATA LAYER                                     │
│                                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │  Knowledge  │  │    RAG      │  │   Recall    │  │  Defining   │    │
│  │    Graph    │  │  (Vectors)  │  │   Files     │  │  Memories   │    │
│  │             │  │             │  │             │  │             │    │
│  │  Neo4j /    │  │  pgvector / │  │  S3 / Local │  │ PostgreSQL  │    │
│  │  PostgreSQL │  │  Pinecone   │  │  Filesystem │  │             │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           AI MODEL LAYER                                 │
│                                                                         │
│         ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐       │
│         │ Claude  │    │   GPT   │    │ Gemini  │    │  Local  │       │
│         │   API   │    │   API   │    │   API   │    │  (Ollama)│       │
│         └─────────┘    └─────────┘    └─────────┘    └─────────┘       │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

User Message → API Gateway → Middleware → Logger
                                           │
                    ┌──────────────────────┼──────────────────────┐
                    ▼                      ▼                      ▼
              Append to              Update KG with          Check for
              active Recall          new entities            Defining Memory
              File transcript        mentioned               triggers
                    │                      │                      │
                    └──────────────────────┴──────────────────────┘
                                           │
                                           ▼
                              If threshold reached (50K tokens):
                              • Finalize Recall File
                              • Generate summary
                              • Extract keywords
                              • Create embeddings
                              • Start new Recall File

User Query → API Gateway → Middleware → Retriever
                                           │
                    ┌──────────────────────┴──────────────────────┐
                    ▼                                             ▼
              Knowledge Graph                              Defining Memory
              Navigation                                   Index Check
                    │                                             │
                    ▼                                             │
              Keyword Search                                      │
              on candidates                                       │
                    │                                             │
                    ▼                                             │
              RAG Search on                                       │
              summaries                                           │
                    │                                             │
                    ▼                                             │
              Load transcripts                                    │
              from top matches                                    │
                    │                                             │
                    └──────────────────────┬──────────────────────┘
                                           │
                                           ▼
                                    Injector builds
                                    context package
                                           │
                                           ▼
                                    Send to AI Model
                                    with injected context

api_gateway:
  host: 0.0.0.0
  port: 8000
  rate_limit:
    requests_per_minute: 60
    burst: 10
  timeout_seconds: 30
  max_request_size_mb: 10

@dataclass
class UserSession:
    user_id: str
    active_recall_file_id: str
    current_token_count: int
    last_activity: datetime
    warm_nodes: list[str]  # KG nodes currently warmed

def allocate_token_budget(
    model: str,
    user_message_tokens: int,
    system_prompt_tokens: int
) -> dict:
    """
    Determine how many tokens to allocate for memory context.
    """
    model_limits = {
        "claude-3-opus": 200000,
        "claude-3-sonnet": 200000,
        "gpt-4-turbo": 128000,
        "gpt-4o": 128000,
        "gemini-1.5-pro": 1000000,
    }
    
    max_context = model_limits.get(model, 100000)
    reserved_for_response = 4096
    
    available = max_context - user_message_tokens - system_prompt_tokens - reserved_for_response
    
    # Allocate up to 25% of available for memory, max 8000 tokens
    memory_budget = min(available * 0.25, 8000)
    
    return {
        "memory_budget": int(memory_budget),
        "remaining_for_conversation": available - memory_budget
    }

async def log_message(
    user_id: str,
    role: str,  # "user" or "assistant"
    content: str,
    artifacts: list[Artifact] = None,
    metadata: dict = None
) -> LogResult:
    """
    Log a message to the user's active Recall File.
    """
    session = get_session(user_id)
    
    # Calculate tokens
    tokens = count_tokens(content)
    session.current_token_count += tokens
    
    # Append to transcript
    await append_to_transcript(
        recall_file_id=session.active_recall_file_id,
        entry=TranscriptEntry(
            timestamp=datetime.utcnow(),
            role=role,
            content=content,
            tokens=tokens
        )
    )
    
    # Store artifacts if present
    if artifacts:
        await store_artifacts(session.active_recall_file_id, artifacts)
    
    # Check for Defining Memory triggers
    if role == "user":
        defining_memory = await detect_defining_memory(content)
        if defining_memory:
            await store_defining_memory(user_id, defining_memory, session.active_recall_file_id)
    
    # Check if threshold reached
    if session.current_token_count >= RECALL_FILE_TOKEN_THRESHOLD:
        await finalize_recall_file(session)
        await start_new_recall_file(session)
    
    return LogResult(
        recall_file_id=session.active_recall_file_id,
        tokens_logged=tokens,
        total_tokens=session.current_token_count
    )

async def finalize_recall_file(session: UserSession):
    """
    Complete a Recall File when token threshold is reached.
    """
    recall_file = await get_recall_file(session.active_recall_file_id)
    
    # Generate summary using AI
    transcript = await load_transcript(recall_file.id)
    summary = await generate_summary(transcript)
    await save_summary(recall_file.id, summary)
    
    # Extract keywords
    keywords = await extract_keywords(transcript, summary)
    await save_keywords(recall_file.id, keywords)
    
    # Generate embedding from summary
    embedding = await embed_text(summary)
    await store_embedding(recall_file.id, embedding)
    
    # Update Knowledge Graph
    entities = await extract_entities(transcript)
    await update_knowledge_graph(session.user_id, recall_file.id, entities)
    
    # Compress artifacts
    await compress_artifacts(recall_file.id)
    
    # Mark as finalized
    recall_file.status = "finalized"
    recall_file.finalized_at = datetime.utcnow()
    await save_recall_file(recall_file)

async def retrieve_memories(
    user_id: str,
    query: str,
    max_results: int = 5,
    include_defining: bool = True
) -> RetrievalResult:
    """
    Execute the full retrieval cascade.
    """
    results = []
    
    # Stage 1: Check Defining Memories
    if include_defining:
        defining = await search_defining_memories(user_id, query)
        if defining:
            results.extend(defining)
    
    # Stage 2: Knowledge Graph Navigation
    relevant_nodes = await find_relevant_nodes(user_id, query)
    candidate_recall_files = await get_recall_files_for_nodes(relevant_nodes)
    
    # Stage 3: Keyword Search
    if candidate_recall_files:
        keyword_matches = await keyword_search(
            query=query,
            recall_file_ids=[rf.id for rf in candidate_recall_files]
        )
        candidate_recall_files = rerank_by_keywords(candidate_recall_files, keyword_matches)
    
    # Stage 4: Semantic Search (RAG)
    query_embedding = await embed_text(query)
    semantic_matches = await vector_search(
        embedding=query_embedding,
        user_id=user_id,
        candidate_ids=[rf.id for rf in candidate_recall_files] if candidate_recall_files else None,
        limit=max_results * 2
    )
    
    # Stage 5: Load and Rank
    for match in semantic_matches[:max_results]:
        recall_file = await get_recall_file(match.recall_file_id)
        
        # Load summary for quick context
        summary = await load_summary(recall_file.id)
        
        # Optionally load relevant transcript section
        if match.score > 0.85:  # High confidence
            transcript = await load_transcript(recall_file.id)
        else:
            transcript = None
        
        results.append(MemoryResult(
            recall_file_id=recall_file.id,
            topic=recall_file.topic,
            date=recall_file.created_at,
            summary=summary,
            transcript_excerpt=transcript,
            relevance_score=match.score
        ))
    
    # Warm the neighborhood for future queries
    if relevant_nodes:
        asyncio.create_task(warm_neighborhood(relevant_nodes))
    
    return RetrievalResult(
        memories=results,
        nodes_searched=len(relevant_nodes),
        recall_files_considered=len(candidate_recall_files)
    )

async def build_enhanced_prompt(
    user_message: str,
    memories: list[MemoryResult],
    system_prompt: str,
    token_budget: int,
    model: str
) -> EnhancedPrompt:
    """
    Build a prompt with memory context injected.
    """
    # Format memories for injection
    memory_sections = []
    tokens_used = 0
    
    for memory in memories:
        # Prefer summary if budget is tight
        if tokens_used + count_tokens(memory.summary) <= token_budget:
            section = format_memory_section(memory, include_transcript=False)
            section_tokens = count_tokens(section)
            
            # Add transcript if we have budget and it's highly relevant
            if memory.transcript_excerpt and memory.relevance_score > 0.85:
                with_transcript = format_memory_section(memory, include_transcript=True)
                transcript_tokens = count_tokens(with_transcript)
                
                if tokens_used + transcript_tokens <= token_budget:
                    section = with_transcript
                    section_tokens = transcript_tokens
            
            memory_sections.append(section)
            tokens_used += section_tokens
        else:
            break  # Budget exhausted
    
    # Build final prompt
    memory_context = "\n\n".join(memory_sections)
    
    enhanced_prompt = PROMPT_TEMPLATE.format(
        system_prompt=system_prompt,
        memory_context=memory_context,
        user_message=user_message
    )
    
    return EnhancedPrompt(
        content=enhanced_prompt,
        memory_tokens_used=tokens_used,
        memories_included=len(memory_sections)
    )

PROMPT_TEMPLATE = """
{system_prompt}

## Relevant Context from Previous Conversations

{memory_context}

---

## Current Message

{user_message}
"""

class NodeType(Enum):
    PROJECT = "project"      # Major work streams
    TOPIC = "topic"          # Subjects within projects
    CONCEPT = "concept"      # Abstract ideas spanning projects
    ENTITY = "entity"        # People, companies, products
    RECALL_FILE = "recall_file"  # Leaf nodes (archives)

class EdgeType(Enum):
    CONTAINS = "contains"           # Hierarchical parent-child
    RELATES_TO = "relates_to"       # Semantic connection
    DISCUSSED_IN = "discussed_in"   # Links to Recall Files
    MENTIONS = "mentions"           # Entity references
    SUPERSEDES = "supersedes"       # Temporal versioning

async def find_relevant_nodes(
    user_id: str,
    query: str,
    max_depth: int = 2
) -> list[Node]:
    """
    Find nodes relevant to a query.
    """
    # Extract potential topic/entity mentions
    mentions = await extract_mentions(query)
    
    # Find matching nodes
    matching_nodes = []
    for mention in mentions:
        nodes = await graph_db.find_nodes(
            user_id=user_id,
            name_contains=mention,
            fuzzy=True
        )
        matching_nodes.extend(nodes)
    
    # Expand to neighborhood
    expanded = set()
    for node in matching_nodes:
        neighborhood = await graph_db.get_neighborhood(
            node_id=node.id,
            depth=max_depth
        )
        expanded.update(neighborhood)
    
    return list(expanded)

async def get_recall_files_for_nodes(nodes: list[Node]) -> list[RecallFile]:
    """
    Get all Recall Files linked to a set of nodes.
    """
    recall_file_ids = set()
    
    for node in nodes:
        edges = await graph_db.get_edges(
            source_id=node.id,
            edge_type=EdgeType.DISCUSSED_IN
        )
        for edge in edges:
            recall_file_ids.add(edge.target_id)
    
    return await batch_get_recall_files(list(recall_file_ids))

DEFINING_MEMORY_PATTERNS = {
    "decision": [
        r"I('ve| have) decided",
        r"we('re| are) going with",
        r"final decision",
        r"I('m| am) committing to",
        r"let's do",
        r"I choose",
    ],
    "milestone": [
        r"we launched",
        r"it's done",
        r"I finished",
        r"completed",
        r"shipped",
        r"released",
        r"went live",
    ],
    "event": [
        r"I('m| am) starting",
        r"got the job",
        r"closed the deal",
        r"signed the contract",
        r"I('m| am) getting married",
        r"we('re| are) having a baby",
    ],
    "turning_point": [
        r"this changes everything",
        r"I realized",
        r"from now on",
        r"never again",
        r"turning point",
    ],
}

async def detect_defining_memory(content: str) -> DefiningMemory | None:
    """
    Check if content contains a defining memory.
    """
    content_lower = content.lower()
    
    for memory_type, patterns in DEFINING_MEMORY_PATTERNS.items():
        for pattern in patterns:
            if re.search(pattern, content_lower):
                # Extract surrounding context
                context = extract_context_window(content, pattern)
                
                # Generate summary using AI
                summary = await summarize_defining_moment(content, memory_type)
                
                return DefiningMemory(
                    type=memory_type,
                    summary=summary,
                    context=context,
                    detected_at=datetime.utcnow(),
                    confidence=0.8  # Pattern-based detection
                )
    
    return None

-- Enable required extensions
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pgvector";
CREATE EXTENSION IF NOT EXISTS "pg_trgm";  -- For fuzzy text search

-- Users table
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    external_id VARCHAR(255) UNIQUE NOT NULL,  -- ID from auth provider
    email VARCHAR(255),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    settings JSONB DEFAULT '{}'::jsonb
);

CREATE INDEX idx_users_external_id ON users(external_id);

-- Recall Files table
CREATE TABLE recall_files (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    folder_name VARCHAR(255) NOT NULL,
    topic VARCHAR(255),
    status VARCHAR(50) DEFAULT 'active',  -- 'active', 'finalized', 'archived'
    storage_state VARCHAR(50) DEFAULT 'hot',  -- 'hot', 'warm', 'cold'
    token_count INTEGER DEFAULT 0,
    
    -- File paths (relative to user's storage root)
    summary_path TEXT,
    keywords_path TEXT,
    transcript_path TEXT,
    artifacts_path TEXT,
    
    -- Timestamps
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    finalized_at TIMESTAMP WITH TIME ZONE,
    last_accessed_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    
    -- Metadata
    metadata JSONB DEFAULT '{}'::jsonb,
    
    CONSTRAINT unique_folder_per_user UNIQUE (user_id, folder_name)
);

CREATE INDEX idx_recall_files_user_id ON recall_files(user_id);
CREATE INDEX idx_recall_files_status ON recall_files(status);
CREATE INDEX idx_recall_files_storage_state ON recall_files(storage_state);
CREATE INDEX idx_recall_files_last_accessed ON recall_files(last_accessed_at);
CREATE INDEX idx_recall_files_topic ON recall_files USING gin(topic gin_trgm_ops);

-- Knowledge Graph Nodes
CREATE TABLE kg_nodes (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    name VARCHAR(255) NOT NULL,
    node_type VARCHAR(50) NOT NULL,  -- 'project', 'topic', 'concept', 'entity'
    description TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    last_accessed_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    metadata JSONB DEFAULT '{}'::jsonb,
    
    CONSTRAINT unique_node_name_per_user UNIQUE (user_id, name, node_type)
);

CREATE INDEX idx_kg_nodes_user_id ON kg_nodes(user_id);
CREATE INDEX idx_kg_nodes_type ON kg_nodes(node_type);
CREATE INDEX idx_kg_nodes_name ON kg_nodes USING gin(name gin_trgm_ops);

-- Knowledge Graph Edges
CREATE TABLE kg_edges (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    source_node_id UUID NOT NULL REFERENCES kg_nodes(id) ON DELETE CASCADE,
    target_node_id UUID NOT NULL REFERENCES kg_nodes(id) ON DELETE CASCADE,
    edge_type VARCHAR(50) NOT NULL,  -- 'contains', 'relates_to', 'discussed_in', etc.
    weight FLOAT DEFAULT 1.0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    metadata JSONB DEFAULT '{}'::jsonb,
    
    CONSTRAINT unique_edge UNIQUE (source_node_id, target_node_id, edge_type)
);

CREATE INDEX idx_kg_edges_source ON kg_edges(source_node_id);
CREATE INDEX idx_kg_edges_target ON kg_edges(target_node_id);
CREATE INDEX idx_kg_edges_type ON kg_edges(edge_type);

-- Recall File to Node mapping
CREATE TABLE recall_file_nodes (
    recall_file_id UUID NOT NULL REFERENCES recall_files(id) ON DELETE CASCADE,
    node_id UUID NOT NULL REFERENCES kg_nodes(id) ON DELETE CASCADE,
    relevance_score FLOAT DEFAULT 1.0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    
    PRIMARY KEY (recall_file_id, node_id)
);

CREATE INDEX idx_recall_file_nodes_node ON recall_file_nodes(node_id);

-- Defining Memories
CREATE TABLE defining_memories (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    memory_type VARCHAR(50) NOT NULL,  -- 'decision', 'milestone', 'event', 'turning_point'
    summary TEXT NOT NULL,
    context TEXT,
    source_recall_file_id UUID REFERENCES recall_files(id) ON DELETE SET NULL,
    confidence FLOAT DEFAULT 1.0,
    detected_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    occurred_at TIMESTAMP WITH TIME ZONE,  -- When the event actually happened
    tags TEXT[] DEFAULT '{}',
    metadata JSONB DEFAULT '{}'::jsonb
);

CREATE INDEX idx_defining_memories_user_id ON defining_memories(user_id);
CREATE INDEX idx_defining_memories_type ON defining_memories(memory_type);
CREATE INDEX idx_defining_memories_detected_at ON defining_memories(detected_at);
CREATE INDEX idx_defining_memories_tags ON defining_memories USING gin(tags);

-- Summary Embeddings (Vector Store)
CREATE TABLE summary_embeddings (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    recall_file_id UUID NOT NULL REFERENCES recall_files(id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    embedding vector(1536),  -- OpenAI ada-002 dimension
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    
    CONSTRAINT unique_embedding_per_recall_file UNIQUE (recall_file_id)
);

-- Create vector index for similarity search
CREATE INDEX idx_summary_embeddings_vector ON summary_embeddings 
USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

CREATE INDEX idx_summary_embeddings_user_id ON summary_embeddings(user_id);

-- Keywords index (for fast exact-match search)
CREATE TABLE recall_file_keywords (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    recall_file_id UUID NOT NULL REFERENCES recall_files(id) ON DELETE CASCADE,
    keyword VARCHAR(255) NOT NULL,
    frequency INTEGER DEFAULT 1,
    
    CONSTRAINT unique_keyword_per_file UNIQUE (recall_file_id, keyword)
);

CREATE INDEX idx_keywords_recall_file ON recall_file_keywords(recall_file_id);
CREATE INDEX idx_keywords_keyword ON recall_file_keywords(keyword);
CREATE INDEX idx_keywords_keyword_trgm ON recall_file_keywords USING gin(keyword gin_trgm_ops);

-- User Sessions (for active conversation tracking)
CREATE TABLE user_sessions (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    active_recall_file_id UUID REFERENCES recall_files(id),
    current_token_count INTEGER DEFAULT 0,
    warm_node_ids UUID[] DEFAULT '{}',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    last_activity_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    expires_at TIMESTAMP WITH TIME ZONE,
    metadata JSONB DEFAULT '{}'::jsonb
);

CREATE INDEX idx_user_sessions_user_id ON user_sessions(user_id);
CREATE INDEX idx_user_sessions_active ON user_sessions(last_activity_at);

-- Audit Log
CREATE TABLE audit_log (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID REFERENCES users(id),
    action VARCHAR(100) NOT NULL,
    resource_type VARCHAR(100),
    resource_id UUID,
    details JSONB,
    ip_address INET,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_audit_log_user_id ON audit_log(user_id);
CREATE INDEX idx_audit_log_action ON audit_log(action);
CREATE INDEX idx_audit_log_created_at ON audit_log(created_at);

/storage/{user_id}/recall-files/{folder_name}/
├── summary.md          # AI-generated summary
├── keywords.txt        # Extracted keywords, one per line
├── transcript.md       # Complete conversation log
└── artifacts/          # Directory for files (or artifacts.zip when cold)
    ├── code_snippet_001.py
    ├── document_draft.md
    └── image_generated.png

# Summary: {topic}

**Date Range:** {start_date} - {end_date}
**Token Count:** {token_count}

## Overview

{AI-generated 2-3 paragraph summary}

## Key Points

- {bullet point 1}
- {bullet point 2}
- {bullet point 3}

## Topics Discussed

- {topic 1}
- {topic 2}

## Artifacts Created

- {artifact 1 with description}
- {artifact 2 with description}

hyperthyme
memory
architecture
recall file
knowledge graph
vector search
defining memory

# Conversation Transcript

**Recall File:** {folder_name}
**Started:** {start_timestamp}
**Finalized:** {end_timestamp}

---

## 2026-01-11T08:30:00Z | User

{user message content}

---

## 2026-01-11T08:30:45Z | Assistant

{assistant response content}

---

## 2026-01-11T08:32:00Z | User

{next user message}

[... continues ...]

from dataclasses import dataclass
from datetime import datetime
from enum import Enum
from typing import Optional
from uuid import UUID


class RecallFileStatus(Enum):
    ACTIVE = "active"
    FINALIZED = "finalized"
    ARCHIVED = "archived"


class StorageState(Enum):
    HOT = "hot"
    WARM = "warm"
    COLD = "cold"


class NodeType(Enum):
    PROJECT = "project"
    TOPIC = "topic"
    CONCEPT = "concept"
    ENTITY = "entity"
    RECALL_FILE = "recall_file"


class EdgeType(Enum):
    CONTAINS = "contains"
    RELATES_TO = "relates_to"
    DISCUSSED_IN = "discussed_in"
    MENTIONS = "mentions"
    SUPERSEDES = "supersedes"


class DefiningMemoryType(Enum):
    DECISION = "decision"
    MILESTONE = "milestone"
    EVENT = "event"
    TURNING_POINT = "turning_point"


@dataclass
class User:
    id: UUID
    external_id: str
    email: Optional[str]
    created_at: datetime
    settings: dict


@dataclass
class RecallFile:
    id: UUID
    user_id: UUID
    folder_name: str
    topic: Optional[str]
    status: RecallFileStatus
    storage_state: StorageState
    token_count: int
    summary_path: Optional[str]
    keywords_path: Optional[str]
    transcript_path: Optional[str]
    artifacts_path: Optional[str]
    created_at: datetime
    updated_at: datetime
    finalized_at: Optional[datetime]
    last_accessed_at: datetime
    metadata: dict


@dataclass
class KGNode:
    id: UUID
    user_id: UUID
    name: str
    node_type: NodeType
    description: Optional[str]
    created_at: datetime
    last_accessed_at: datetime
    metadata: dict


@dataclass
class KGEdge:
    id: UUID
    source_node_id: UUID
    target_node_id: UUID
    edge_type: EdgeType
    weight: float
    created_at: datetime
    metadata: dict


@dataclass
class DefiningMemory:
    id: UUID
    user_id: UUID
    memory_type: DefiningMemoryType
    summary: str
    context: Optional[str]
    source_recall_file_id: Optional[UUID]
    confidence: float
    detected_at: datetime
    occurred_at: Optional[datetime]
    tags: list[str]
    metadata: dict


@dataclass
class SummaryEmbedding:
    id: UUID
    recall_file_id: UUID
    user_id: UUID
    embedding: list[float]  # 1536 dimensions
    created_at: datetime


@dataclass
class UserSession:
    id: UUID
    user_id: UUID
    active_recall_file_id: Optional[UUID]
    current_token_count: int
    warm_node_ids: list[UUID]
    created_at: datetime
    last_activity_at: datetime
    expires_at: Optional[datetime]
    metadata: dict

{
  "message": "Continue working on the payment integration",
  "model": "claude-sonnet-4-20250514",
  "include_memories": true,
  "memory_options": {
    "max_memories": 5,
    "token_budget": 4000,
    "include_defining": true,
    "time_range": {
      "start": "2025-01-01T00:00:00Z",
      "end": null
    }
  },
  "system_prompt": "You are a helpful coding assistant.",
  "stream": false
}

{
  "id": "msg_abc123",
  "response": "I found our previous work on the payment integration...",
  "model": "claude-sonnet-4-20250514",
  "memories_used": [
    {
      "recall_file_id": "rf_xyz789",
      "topic": "Payment Integration - Stripe",
      "date": "2025-01-03",
      "relevance_score": 0.92
    }
  ],
  "usage": {
    "prompt_tokens": 1500,
    "completion_tokens": 350,
    "memory_tokens": 800
  },
  "logged_to": "rf_current123"
}

{
  "query": "payment webhook implementation",
  "max_results": 10,
  "include_transcripts": false,
  "filters": {
    "date_range": {
      "start": "2024-01-01",
      "end": null
    },
    "topics": ["payments", "integration"],
    "memory_types": ["defining", "regular"]
  }
}

{
  "results": [
    {
      "type": "recall_file",
      "id": "rf_xyz789",
      "topic": "Payment Integration - Stripe Webhooks",
      "date": "2025-01-03",
      "summary": "Implemented webhook handlers for payment events...",
      "relevance_score": 0.94,
      "keywords": ["stripe", "webhook", "payment", "handler"]
    },
    {
      "type": "defining_memory",
      "id": "dm_abc456",
      "memory_type": "decision",
      "summary": "Decided to use Stripe Connect for marketplace payments",
      "date": "2024-12-15",
      "relevance_score": 0.87
    }
  ],
  "total_count": 2,
  "search_stats": {
    "nodes_searched": 5,
    "recall_files_considered": 12,
    "search_time_ms": 45
  }
}

{
  "recall_files": [
    {
      "id": "rf_xyz789",
      "folder_name": "payment-integration-stripe-2025-01-03",
      "topic": "Payment Integration - Stripe",
      "status": "finalized",
      "storage_state": "warm",
      "token_count": 48500,
      "created_at": "2025-01-03T10:00:00Z",
      "finalized_at": "2025-01-03T14:30:00Z",
      "last_accessed_at": "2025-01-10T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

{
  "id": "rf_xyz789",
  "folder_name": "payment-integration-stripe-2025-01-03",
  "topic": "Payment Integration - Stripe",
  "status": "finalized",
  "storage_state": "warm",
  "token_count": 48500,
  "created_at": "2025-01-03T10:00:00Z",
  "finalized_at": "2025-01-03T14:30:00Z",
  "summary": "## Overview\n\nImplemented Stripe webhook handlers...",
  "keywords": ["stripe", "webhook", "payment", "handler", "checkout"],
  "transcript": "# Conversation Transcript\n\n...",
  "artifacts": [
    {
      "name": "webhook_handler.py",
      "type": "text/x-python",
      "size": 2500
    }
  ],
  "linked_nodes": [
    {"id": "node_123", "name": "Payments", "type": "topic"},
    {"id": "node_456", "name": "funnelChat", "type": "project"}
  ]
}

{
  "defining_memories": [
    {
      "id": "dm_abc456",
      "type": "decision",
      "summary": "Decided to build Hyperthyme as the memory layer for Neurigraph",
      "context": "After discovering Mem0 raised $24M...",
      "detected_at": "2025-01-11T08:00:00Z",
      "occurred_at": "2025-01-11T08:00:00Z",
      "source_recall_file_id": "rf_xyz789",
      "tags": ["product", "strategy", "commitment"],
      "confidence": 0.95
    }
  ],
  "pagination": {
    "total": 23,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

{
  "nodes": [
    {
      "id": "node_123",
      "name": "Payments",
      "type": "topic",
      "description": "Payment processing and integrations",
      "recall_file_count": 8,
      "related_nodes": [
        {"id": "node_456", "name": "Stripe", "relationship": "contains"},
        {"id": "node_789", "name": "funnelChat", "relationship": "belongs_to"}
      ]
    }
  ]
}

{
  "name": "New Project",
  "type": "project",
  "description": "Description of the project",
  "parent_id": null
}

@mcp_server.tool(
    name="search_memory",
    description="Search the user's conversation history for relevant memories"
)
async def search_memory(
    query: str,
    max_results: int = 5,
    include_defining: bool = True
) -> list[dict]:
    """
    Search for memories matching the query.
    
    Args:
        query: Natural language search query
        max_results: Maximum number of results to return
        include_defining: Whether to include defining memories
        
    Returns:
        List of matching memories with summaries and metadata
    """
    pass


@mcp_server.tool(
    name="get_defining_memories",
    description="Retrieve the user's major decisions, milestones, and significant events"
)
async def get_defining_memories(
    type_filter: str = None,
    since: str = None,
    limit: int = 10
) -> list[dict]:
    """
    Get defining memories.
    
    Args:
        type_filter: Filter by type (decision, milestone, event, turning_point)
        since: Only return memories after this date (ISO 8601)
        limit: Maximum results
        
    Returns:
        List of defining memories
    """
    pass


@mcp_server.tool(
    name="get_recall_file_content",
    description="Retrieve the full content of a specific conversation archive"
)
async def get_recall_file_content(
    recall_file_id: str,
    include: list[str] = ["summary", "transcript"]
) -> dict:
    """
    Get content from a specific Recall File.
    
    Args:
        recall_file_id: The ID of the Recall File
        include: Which components to include (summary, keywords, transcript, artifacts)
        
    Returns:
        Recall File content
    """
    pass


@mcp_server.tool(
    name="list_topics",
    description="List the user's projects and topics from their knowledge graph"
)
async def list_topics(
    type_filter: str = None,
    parent_id: str = None
) -> list[dict]:
    """
    List knowledge graph nodes.
    
    Args:
        type_filter: Filter by type (project, topic, concept)
        parent_id: Only show children of this node
        
    Returns:
        List of nodes with metadata
    """
    pass

# Python SDK Example

from hyperthyme import HyperthymeClient

# Initialize client
client = HyperthymeClient(
    api_key="sk_...",
    base_url="https://api.hyperthyme.ai"
)

# Chat with memory
response = client.chat(
    message="Continue working on the payment integration",
    model="claude-sonnet-4-20250514",
    memory_options={
        "max_memories": 5,
        "token_budget": 4000
    }
)

print(response.content)
print(f"Used {len(response.memories_used)} memories")

# Search memories
results = client.search(
    query="payment webhook implementation",
    max_results=10
)

for result in results:
    print(f"{result.topic}: {result.summary[:100]}...")

# Get defining memories
decisions = client.get_defining_memories(
    type_filter="decision",
    since="2025-01-01"
)

for decision in decisions:
    print(f"{decision.date}: {decision.summary}")

# Direct Recall File access
recall_file = client.get_recall_file(
    "rf_xyz789",
    include=["summary", "transcript"]
)

print(recall_file.transcript)

┌─────────────────────────────────────────────────────────────────────────┐
│                         RETRIEVAL PIPELINE                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Query: "What was the code for handling payment webhooks?"              │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ STAGE 1: Defining Memory Check                           ~5ms   │    │
│  │                                                                 │    │
│  │ Check if query relates to a decision/milestone/event           │    │
│  │ Result: No direct match (content query, not event query)       │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ STAGE 2: Knowledge Graph Navigation                     ~10ms   │    │
│  │                                                                 │    │
│  │ Extract entities: ["payment", "webhook", "code"]               │    │
│  │ Find matching nodes: [Payments, Webhooks, Stripe]              │    │
│  │ Expand neighborhood (depth=2)                                  │    │
│  │ Get linked Recall Files: 15 candidates                         │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ STAGE 3: Keyword Filtering                              ~15ms   │    │
│  │                                                                 │    │
│  │ Search keywords.txt in 15 candidates                           │    │
│  │ Terms: ["webhook", "payment", "stripe", "handler", "code"]     │    │
│  │ Score by keyword overlap                                       │    │
│  │ Result: 6 Recall Files with strong overlap                     │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ STAGE 4: Semantic Search (RAG)                          ~30ms   │    │
│  │                                                                 │    │
│  │ Embed query                                                    │    │
│  │ Vector search on 6 candidate summaries                         │    │
│  │ Rank by cosine similarity                                      │    │
│  │ Result: Top 3 with scores [0.94, 0.87, 0.82]                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ STAGE 5: Content Loading                                ~20ms   │    │
│  │                                                                 │    │
│  │ Load summaries for top 3                                       │    │
│  │ Load transcript for #1 (score > 0.9 threshold)                 │    │
│  │ Warm neighborhood nodes for future queries                     │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  Total Time: ~80ms                                                     │
│  Result: 3 memories, 1 with full transcript                            │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

async def check_defining_memories(
    user_id: str,
    query: str
) -> list[DefiningMemory]:
    """
    Quick check if query relates to defining memories.
    
    Uses keyword matching and optional semantic similarity
    against the defining memories index (always in memory).
    """
    # Keyword extraction
    query_keywords = extract_keywords(query)
    
    # Check for event-type query patterns
    event_patterns = [
        r"when did (I|we)",
        r"what (did I|did we) decide",
        r"(milestone|decision|event)",
        r"remember when"
    ]
    
    is_event_query = any(re.search(p, query.lower()) for p in event_patterns)
    
    if not is_event_query:
        return []
    
    # Search defining memories index
    matches = await db.query("""
        SELECT * FROM defining_memories
        WHERE user_id = $1
        AND (
            summary ILIKE ANY($2)
            OR tags && $3
        )
        ORDER BY detected_at DESC
        LIMIT 5
    """, user_id, [f"%{kw}%" for kw in query_keywords], query_keywords)
    
    return [DefiningMemory(**m) for m in matches]

async def navigate_knowledge_graph(
    user_id: str,
    query: str,
    max_depth: int = 2
) -> tuple[list[KGNode], list[RecallFile]]:
    """
    Find relevant nodes and their linked Recall Files.
    """
    # Extract potential topic/entity mentions
    mentions = await extract_mentions(query)  # NER + keyword extraction
    
    # Find matching nodes
    matching_nodes = []
    for mention in mentions:
        nodes = await db.query("""
            SELECT * FROM kg_nodes
            WHERE user_id = $1
            AND (
                name ILIKE $2
                OR description ILIKE $2
            )
        """, user_id, f"%{mention}%")
        matching_nodes.extend(nodes)
    
    # Expand to neighborhood (BFS)
    visited = set()
    frontier = [n.id for n in matching_nodes]
    depth = 0
    
    while frontier and depth < max_depth:
        edges = await db.query("""
            SELECT target_node_id FROM kg_edges
            WHERE source_node_id = ANY($1)
            UNION
            SELECT source_node_id FROM kg_edges
            WHERE target_node_id = ANY($1)
        """, frontier)
        
        new_frontier = []
        for edge in edges:
            node_id = edge['target_node_id'] or edge['source_node_id']
            if node_id not in visited:
                visited.add(node_id)
                new_frontier.append(node_id)
        
        frontier = new_frontier
        depth += 1
    
    # Get all recall files linked to visited nodes
    recall_files = await db.query("""
        SELECT DISTINCT rf.* FROM recall_files rf
        JOIN recall_file_nodes rfn ON rf.id = rfn.recall_file_id
        WHERE rfn.node_id = ANY($1)
        AND rf.status = 'finalized'
    """, list(visited))
    
    return matching_nodes, recall_files

async def filter_by_keywords(
    query: str,
    candidate_recall_files: list[RecallFile]
) -> list[tuple[RecallFile, float]]:
    """
    Score candidates by keyword overlap.
    """
    query_keywords = set(extract_keywords(query))
    
    scored_candidates = []
    
    for rf in candidate_recall_files:
        # Get keywords for this recall file
        rf_keywords = await db.query("""
            SELECT keyword FROM recall_file_keywords
            WHERE recall_file_id = $1
        """, rf.id)
        rf_keyword_set = set(k['keyword'] for k in rf_keywords)
        
        # Calculate overlap score
        if rf_keyword_set:
            overlap = len(query_keywords & rf_keyword_set)
            score = overlap / len(query_keywords) if query_keywords else 0
        else:
            score = 0
        
        if score > 0.1:  # Minimum threshold
            scored_candidates.append((rf, score))
    
    # Sort by score descending
    scored_candidates.sort(key=lambda x: x[1], reverse=True)
    
    return scored_candidates

async def semantic_search(
    query: str,
    candidate_ids: list[str],
    limit: int = 5
) -> list[tuple[str, float]]:
    """
    Vector similarity search on candidate summaries.
    """
    # Generate query embedding
    query_embedding = await embedding_model.embed(query)
    
    # Search with filtering
    results = await db.query("""
        SELECT 
            recall_file_id,
            1 - (embedding <=> $1) as similarity
        FROM summary_embeddings
        WHERE recall_file_id = ANY($2)
        ORDER BY embedding <=> $1
        LIMIT $3
    """, query_embedding, candidate_ids, limit)
    
    return [(r['recall_file_id'], r['similarity']) for r in results]

async def load_memory_content(
    recall_file_ids: list[str],
    scores: dict[str, float],
    transcript_threshold: float = 0.9
) -> list[MemoryResult]:
    """
    Load content from top-ranked Recall Files.
    """
    results = []
    
    for rf_id in recall_file_ids:
        rf = await get_recall_file(rf_id)
        score = scores[rf_id]
        
        # Always load summary
        summary = await load_file(rf.summary_path)
        
        # Load transcript only for high-confidence matches
        transcript = None
        if score >= transcript_threshold:
            transcript = await load_file(rf.transcript_path)
        
        results.append(MemoryResult(
            recall_file_id=rf_id,
            topic=rf.topic,
            date=rf.created_at,
            summary=summary,
            transcript=transcript,
            relevance_score=score
        ))
        
        # Update last accessed
        await db.execute("""
            UPDATE recall_files
            SET last_accessed_at = NOW()
            WHERE id = $1
        """, rf_id)
    
    return results

class RetrievalCache:
    """
    Multi-level cache for retrieval operations.
    """
    
    def __init__(self, redis_client):
        self.redis = redis_client
        self.local_cache = {}  # In-memory LRU
    
    async def get_embedding(self, text: str) -> list[float]:
        """Cache embeddings to avoid recomputation."""
        cache_key = f"emb:{hash(text)}"
        
        # Check local cache first
        if cache_key in self.local_cache:
            return self.local_cache[cache_key]
        
        # Check Redis
        cached = await self.redis.get(cache_key)
        if cached:
            embedding = json.loads(cached)
            self.local_cache[cache_key] = embedding
            return embedding
        
        # Compute and cache
        embedding = await embedding_model.embed(text)
        await self.redis.setex(cache_key, 86400, json.dumps(embedding))
        self.local_cache[cache_key] = embedding
        return embedding
    
    async def get_keywords(self, recall_file_id: str) -> list[str]:
        """Cache keywords for fast filtering."""
        cache_key = f"kw:{recall_file_id}"
        
        cached = await self.redis.get(cache_key)
        if cached:
            return json.loads(cached)
        
        keywords = await load_keywords_from_file(recall_file_id)
        await self.redis.setex(cache_key, 3600, json.dumps(keywords))
        return keywords

async def batch_get_recall_files(ids: list[str]) -> list[RecallFile]:
    """
    Fetch multiple Recall Files in a single query.
    """
    if not ids:
        return []
    
    results = await db.query("""
        SELECT * FROM recall_files
        WHERE id = ANY($1)
    """, ids)
    
    return [RecallFile(**r) for r in results]

┌─────────────────────────────────────────────────────────────────────────┐
│                         STORAGE TIERS                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ HOT                                                 0-1 hours   │    │
│  │                                                                 │    │
│  │ • Currently active Recall File                                 │    │
│  │ • All content in memory                                        │    │
│  │ • Instant access (<10ms)                                       │    │
│  │ • Location: Application memory + local SSD                     │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ WARM                                                1h - 7 days │    │
│  │                                                                 │    │
│  │ • Recently accessed Recall Files                               │    │
│  │ • Same KG neighborhood as current topic                        │    │
│  │ • Transcript cached, artifacts uncompressed                    │    │
│  │ • Fast access (<100ms)                                         │    │
│  │ • Location: Local SSD / Fast object storage                    │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ COLD                                                   7+ days  │    │
│  │                                                                 │    │
│  │ • Infrequently accessed Recall Files                           │    │
│  │ • Artifacts compressed (zip)                                   │    │
│  │ • Transcript on disk (not cached)                              │    │
│  │ • Keywords/summaries still indexed                             │    │
│  │ • Slower access (<1s)                                          │    │
│  │ • Location: Object storage (S3/GCS) with compression           │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

class StorageManager:
    """
    Manages storage tier transitions for Recall Files.
    """
    
    WARM_THRESHOLD_HOURS = 1
    COLD_THRESHOLD_DAYS = 7
    
    async def warm_recall_file(self, recall_file_id: str):
        """
        Transition a Recall File from cold to warm.
        """
        rf = await get_recall_file(recall_file_id)
        
        if rf.storage_state == StorageState.COLD:
            # Decompress artifacts
            if rf.artifacts_path and rf.artifacts_path.endswith('.zip'):
                await decompress_artifacts(rf.id)
            
            # Pre-cache transcript
            transcript = await load_file(rf.transcript_path)
            await cache.set(f"transcript:{rf.id}", transcript, ttl=3600)
            
            # Update state
            rf.storage_state = StorageState.WARM
            await save_recall_file(rf)
    
    async def cool_recall_file(self, recall_file_id: str):
        """
        Transition a Recall File from warm to cold.
        """
        rf = await get_recall_file(recall_file_id)
        
        if rf.storage_state == StorageState.WARM:
            # Compress artifacts
            if rf.artifacts_path and not rf.artifacts_path.endswith('.zip'):
                await compress_artifacts(rf.id)
            
            # Evict transcript cache
            await cache.delete(f"transcript:{rf.id}")
            
            # Update state
            rf.storage_state = StorageState.COLD
            await save_recall_file(rf)
    
    async def warm_neighborhood(self, node_ids: list[str]):
        """
        Warm all Recall Files in a KG neighborhood.
        """
        recall_files = await get_recall_files_for_nodes(node_ids)
        
        tasks = [
            self.warm_recall_file(rf.id)
            for rf in recall_files
            if rf.storage_state == StorageState.COLD
        ]
        
        await asyncio.gather(*tasks)


class StorageLifecycleJob:
    """
    Background job for storage lifecycle management.
    """
    
    async def run(self):
        """
        Run nightly to transition warm → cold.
        """
        cutoff = datetime.utcnow() - timedelta(days=7)
        
        warm_files = await db.query("""
            SELECT id FROM recall_files
            WHERE storage_state = 'warm'
            AND last_accessed_at < $1
        """, cutoff)
        
        storage_manager = StorageManager()
        
        for rf in warm_files:
            try:
                await storage_manager.cool_recall_file(rf['id'])
            except Exception as e:
                logger.error(f"Failed to cool {rf['id']}: {e}")

/storage/
├── {user_id}/
│   ├── recall-files/
│   │   ├── payment-integration-stripe-2025-01-03/
│   │   │   ├── summary.md
│   │   │   ├── keywords.txt
│   │   │   ├── transcript.md
│   │   │   └── artifacts/
│   │   │       ├── webhook_handler.py
│   │   │       └── test_coverage.png
│   │   │
│   │   ├── api-design-session-2025-01-05/
│   │   │   ├── summary.md
│   │   │   ├── keywords.txt
│   │   │   ├── transcript.md
│   │   │   └── artifacts.zip          # Compressed (cold)
│   │   │
│   │   └── current-session-2025-01-11/  # Active (hot)
│   │       └── transcript.md           # Being written to
│   │
│   └── config/
│       └── user_settings.json
│
└── system/
    ├── models/
    │   └── embedding_model/
    └── cache/

class AuthMiddleware:
    """
    Authentication and authorization middleware.
    """
    
    async def __call__(self, request: Request, call_next):
        # Extract auth header
        auth_header = request.headers.get("Authorization")
        
        if not auth_header:
            raise HTTPException(401, "Missing authorization")
        
        # Validate token
        if auth_header.startswith("Bearer "):
            token = auth_header[7:]
            user = await self.validate_jwt(token)
        elif auth_header.startswith("sk_"):
            user = await self.validate_api_key(auth_header)
        else:
            raise HTTPException(401, "Invalid authorization format")
        
        # Attach user to request
        request.state.user = user
        
        return await call_next(request)
    
    async def validate_jwt(self, token: str) -> User:
        try:
            payload = jwt.decode(token, JWT_SECRET, algorithms=["HS256"])
            user = await get_user(payload["sub"])
            return user
        except jwt.ExpiredSignatureError:
            raise HTTPException(401, "Token expired")
        except jwt.InvalidTokenError:
            raise HTTPException(401, "Invalid token")
    
    async def validate_api_key(self, api_key: str) -> User:
        # Hash and lookup
        key_hash = hashlib.sha256(api_key.encode()).hexdigest()
        user = await db.query("""
            SELECT u.* FROM users u
            JOIN api_keys ak ON u.id = ak.user_id
            WHERE ak.key_hash = $1
            AND ak.revoked_at IS NULL
        """, key_hash)
        
        if not user:
            raise HTTPException(401, "Invalid API key")
        
        return User(**user[0])

class EncryptionService:
    """
    Handles encryption/decryption of stored data.
    """
    
    def __init__(self, kms_client):
        self.kms = kms_client
    
    async def encrypt_file(self, user_id: str, content: bytes) -> bytes:
        # Get or create user data key
        data_key = await self.get_user_data_key(user_id)
        
        # Encrypt content
        nonce = os.urandom(12)
        cipher = Cipher(algorithms.AES(data_key), modes.GCM(nonce))
        encryptor = cipher.encryptor()
        ciphertext = encryptor.update(content) + encryptor.finalize()
        
        # Return nonce + tag + ciphertext
        return nonce + encryptor.tag + ciphertext
    
    async def decrypt_file(self, user_id: str, encrypted: bytes) -> bytes:
        # Extract components
        nonce = encrypted[:12]
        tag = encrypted[12:28]
        ciphertext = encrypted[28:]
        
        # Get user data key
        data_key = await self.get_user_data_key(user_id)
        
        # Decrypt
        cipher = Cipher(algorithms.AES(data_key), modes.GCM(nonce, tag))
        decryptor = cipher.decryptor()
        return decryptor.update(ciphertext) + decryptor.finalize()
    
    async def get_user_data_key(self, user_id: str) -> bytes:
        # Derive from master key using HKDF
        master_key = await self.kms.get_master_key()
        return HKDF(
            algorithm=hashes.SHA256(),
            length=32,
            salt=user_id.encode(),
            info=b"hyperthyme-data-key"
        ).derive(master_key)

def ensure_user_owns_resource(user_id: str, resource_user_id: str):
    """
    Verify user has access to a resource.
    """
    if user_id != resource_user_id:
        raise HTTPException(403, "Access denied")


# Applied to all resource access
@app.get("/recall-files/{recall_file_id}")
async def get_recall_file(recall_file_id: str, request: Request):
    rf = await db.get_recall_file(recall_file_id)
    ensure_user_owns_resource(request.state.user.id, rf.user_id)
    return rf

async def audit_log(
    user_id: str,
    action: str,
    resource_type: str,
    resource_id: str,
    details: dict = None,
    ip_address: str = None
):
    """
    Log security-relevant events.
    """
    await db.execute("""
        INSERT INTO audit_log (user_id, action, resource_type, resource_id, details, ip_address)
        VALUES ($1, $2, $3, $4, $5, $6)
    """, user_id, action, resource_type, resource_id, json.dumps(details), ip_address)


# Example usage
await audit_log(
    user_id=user.id,
    action="recall_file.read",
    resource_type="recall_file",
    resource_id=rf.id,
    details={"include_transcript": True},
    ip_address=request.client.host
)

async def delete_user_data(user_id: str, hard_delete: bool = False):
    """
    Delete all user data.
    
    Args:
        user_id: User to delete
        hard_delete: If True, permanently delete. If False, soft delete with 30-day recovery window.
    """
    if hard_delete:
        # Delete from all tables
        await db.execute("DELETE FROM audit_log WHERE user_id = $1", user_id)
        await db.execute("DELETE FROM defining_memories WHERE user_id = $1", user_id)
        await db.execute("DELETE FROM summary_embeddings WHERE user_id = $1", user_id)
        await db.execute("DELETE FROM recall_file_keywords WHERE recall_file_id IN (SELECT id FROM recall_files WHERE user_id = $1)", user_id)
        await db.execute("DELETE FROM recall_file_nodes WHERE recall_file_id IN (SELECT id FROM recall_files WHERE user_id = $1)", user_id)
        await db.execute("DELETE FROM recall_files WHERE user_id = $1", user_id)
        await db.execute("DELETE FROM kg_edges WHERE source_node_id IN (SELECT id FROM kg_nodes WHERE user_id = $1)", user_id)
        await db.execute("DELETE FROM kg_nodes WHERE user_id = $1", user_id)
        await db.execute("DELETE FROM user_sessions WHERE user_id = $1", user_id)
        await db.execute("DELETE FROM users WHERE id = $1", user_id)
        
        # Delete files
        await storage.delete_directory(f"/storage/{user_id}/")
    else:
        # Soft delete with recovery window
        await db.execute("""
            UPDATE users
            SET deleted_at = NOW(),
                deletion_scheduled_for = NOW() + INTERVAL '30 days'
            WHERE id = $1
        """, user_id)