Unified RAG++ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                          UNIFIED RAG++ ARCHITECTURE                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │   Claude     │  │   Cursor     │  │   ChatGPT    │  │    Speak     │    │
│  │    Code      │  │    Agent     │  │    Export    │  │    Voice     │    │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │
│         │                 │                 │                 │             │
│         └────────────┬────┴────────────┬────┴────────────┬────┘             │
│                      │                 │                 │                  │
│                      ▼                 ▼                 ▼                  │
│  ┌───────────────────────────────────────────────────────────────────┐     │
│  │                       PROMPT LOGGER                                │     │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │     │
│  │  │ main.py     │  │response_hook│  │ orbit_sync  │               │     │
│  │  │ (capture)   │  │ (response)  │  │ (unified)   │               │     │
│  │  └─────────────┘  └─────────────┘  └──────┬──────┘               │     │
│  └───────────────────────────────────────────┼───────────────────────┘     │
│                                              │                              │
│                                              ▼                              │
│  ┌───────────────────────────────────────────────────────────────────┐     │
│  │                         ORBIT SERVER                              │     │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │     │
│  │  │ /api/rag/   │  │ Project     │  │ Session     │               │     │
│  │  │ ingest      │  │ Manager     │  │ Handler     │               │     │
│  │  └──────┬──────┘  └─────────────┘  └─────────────┘               │     │
│  └─────────┼─────────────────────────────────────────────────────────┘     │
│            │                                                                │
│            ▼                                                                │
│  ┌───────────────────────────────────────────────────────────────────┐     │
│  │                       PROMPT INGESTER                             │     │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │     │
│  │  │ Embedding   │  │ Trajectory  │  │ Supabase    │               │     │
│  │  │ (Gemini)    │  │ Compute     │  │ Insert      │               │     │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘               │     │
│  └─────────┼────────────────┼────────────────┼───────────────────────┘     │
│            │                │                │                              │
│            │                ▼                │                              │
│  ┌─────────┼────────────────────────────────┼───────────────────────┐     │
│  │         │          RUST CORE             │                        │     │
│  │  ┌──────┴──────┐  ┌─────────────┐  ┌─────┴─────┐                 │     │
│  │  │ HNSWIndex   │  │    IRCP     │  │ Trajectory │                 │     │
│  │  │ (neighbors) │  │ Propagator  │  │ Coord 5D   │                 │     │
│  │  └─────────────┘  └─────────────┘  └───────────┘                 │     │
│  └───────────────────────────────────────────────────────────────────┘     │
│            │                │                │                              │
│            └────────────────┴────────────────┘                              │
│                             │                                               │
│                             ▼                                               │
│  ┌───────────────────────────────────────────────────────────────────┐     │
│  │                         SUPABASE                                  │     │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │     │
│  │  │ memory_     │  │ memory_     │  │ claude_     │               │     │
│  │  │ turns       │  │ convos      │  │ prompts     │               │     │
│  │  └─────────────┘  └─────────────┘  └─────────────┘               │     │
│  └───────────────────────────────────────────────────────────────────┘     │
│                             │                                               │
│                             ▼                                               │
│  ┌───────────────────────────────────────────────────────────────────┐     │
│  │                    COGNITIVETWIN                                  │     │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │     │
│  │  │   Hybrid    │  │   Global    │  │   Pattern   │               │     │
│  │  │   Trainer   │  │  Signature  │  │   Memory    │               │     │
│  │  └─────────────┘  └─────────────┘  └─────────────┘               │     │
│  └───────────────────────────────────────────────────────────────────┘     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

L5: Integration ─────┐
        │            │
        ▼            │
L4: Orchestration ───┤
        │            │
        ▼            │
L3: ML ──────────────┤
        │            │
        ▼            │
L2: Ingestion ───────┤
        │            │
        ▼            │
L1: Data ────────────┤
        │            │
        ▼            │
L0: Foundation ◀─────┘

from _rag_plusplus_rs import HNSWIndex

index = HNSWIndex()

# Add vectors
index.add("turn-uuid-123", embedding_768d)

# Search neighbors
results = index.search(query_embedding, k=10)
# Returns: List[SearchResult] with id, score

from _rag_plusplus_rs import IRCPPropagator, IRCPConfig

config = IRCPConfig(
    forward_weight=0.4,
    inverse_weight=0.3,
    cross_weight=0.3,
)
propagator = IRCPPropagator(config)

# Compute attention weights
weights = propagator.compute_attention(
    query_coord,      # PyTrajectoryCoordinate5D
    context_coords,   # List[PyTrajectoryCoordinate5D]
    query_embedding,  # numpy array
    context_embeddings,  # List[numpy array]
)

from _rag_plusplus_rs import compute_trajectory_coordinates
import numpy as np

coord = compute_trajectory_coordinates(
    embedding=np.array([...], dtype=np.float32),  # 768-dim
    neighbor_similarities=[0.85, 0.72, 0.68],     # from HNSW search
    session_depth=5,                               # depth in session
    turn_index=12,                                 # position in conversation
    sibling_count=1,                               # branches at this depth
    sibling_order=0,                               # position among siblings
    project_phase="implementation",                # phase string
)
# Returns: PyTrajectoryCoordinate5D

pub enum TrajectoryPhase {
    Exploration,   // Initial topic discovery
    Refinement,    // Narrowing focus, planning
    Application,   // Implementation, execution
    Resolution,    // Debugging, review, completion
}

crates/
├── core/
│   └── src/
│       ├── lib.rs              # Core exports
│       ├── index/
│       │   ├── hnsw.rs         # HNSW implementation
│       │   └── flat.rs         # Flat index fallback
│       └── trajectory/
│           ├── mod.rs          # Trajectory exports
│           ├── coordinate.rs   # 5D coordinate types
│           ├── ircp.rs         # IRCP propagator
│           └── phase.rs        # Phase inference
└── python/
    └── src/
        └── lib.rs              # PyO3 bindings

CREATE TABLE memory_conversations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title TEXT,
    source TEXT NOT NULL,  -- 'chatgpt', 'claude', 'orbit'
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    metadata JSONB DEFAULT '{}'::jsonb
);

CREATE TABLE memory_turns (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversation_id UUID REFERENCES memory_conversations(id),
    content TEXT NOT NULL,
    role TEXT NOT NULL,  -- 'user', 'assistant', 'system'
    turn_index INTEGER NOT NULL,

    -- 768-dim embedding (Gemini)
    embedding vector(768),

    -- 5D Trajectory Coordinates
    trajectory_depth FLOAT,           -- x: depth (0-1)
    trajectory_sibling_order FLOAT,   -- y: sibling position (0-1)
    trajectory_homogeneity FLOAT,     -- z: semantic focus (0-1)
    trajectory_temporal FLOAT,        -- t: time position (0-1)
    trajectory_complexity FLOAT,      -- n: complexity (0-1)
    trajectory_phase TEXT,            -- phase enum string

    -- Salience and importance
    salience_score FLOAT DEFAULT 0.5,

    -- Metadata
    metadata JSONB DEFAULT '{}'::jsonb,
    created_at TIMESTAMPTZ DEFAULT NOW(),

    -- Indexes
    CONSTRAINT fk_conversation FOREIGN KEY (conversation_id)
        REFERENCES memory_conversations(id) ON DELETE CASCADE
);

-- Vector similarity index
CREATE INDEX idx_turns_embedding ON memory_turns
    USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

-- Trajectory coordinate indexes
CREATE INDEX idx_turns_trajectory ON memory_turns (
    trajectory_depth, trajectory_temporal, trajectory_phase
);

CREATE TABLE claude_prompts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    prompt_id TEXT UNIQUE NOT NULL,
    session_id TEXT NOT NULL,
    prompt_text TEXT NOT NULL,
    prompt_text_length INTEGER,
    source TEXT DEFAULT 'claude',

    -- Timing
    prompt_received_at TIMESTAMPTZ,
    response_complete_at TIMESTAMPTZ,
    total_duration_ms FLOAT,

    -- Git context
    git_repo TEXT,
    git_branch TEXT,
    git_commit_before TEXT,

    -- Link to unified memory_turns (if ingested)
    memory_turn_id UUID REFERENCES memory_turns(id),

    metadata JSONB DEFAULT '{}'::jsonb,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Full-text search on content
CREATE INDEX idx_turns_content_fts ON memory_turns
    USING gin(to_tsvector('english', content));

-- Metadata JSONB indexing
CREATE INDEX idx_turns_metadata ON memory_turns USING gin(metadata);

-- Source filtering
CREATE INDEX idx_turns_source ON memory_turns ((metadata->>'source'));

-- Orbit project filtering
CREATE INDEX idx_turns_orbit_project ON memory_turns
    ((metadata->>'orbit_project_id'));

// memory_turns.metadata for prompts ingested via Orbit
{
    "source": "claude_prompt",
    "prompt_id": "session123-20241229123456-abc12345",
    "orbit_project_id": "uuid-of-project",
    "orbit_session_id": "uuid-of-session",
    "project_name": "cc-rag-plus-plus",
    "working_directory": "/Users/user/project",
    "turn_index": 5
}

class PromptIngester:
    """Ingests Claude prompts into unified memory_turns table."""

    def __init__(
        self,
        supabase_url: Optional[str] = None,
        supabase_key: Optional[str] = None,
        embedding_fn: Optional[Callable[[str], List[float]]] = None,
        hybrid_trainer: Optional[HybridCognitiveTwinTrainer] = None,
        enable_incremental_learning: bool = True,
    ) -> None:
        ...

async def ingest_prompt(
    self,
    prompt_id: str,
    prompt_text: str,
    response_text: str,
    orbit_context: OrbitContext,
) -> IngestedTurn:
    """
    Complete ingestion flow:

    1. Combine prompt + response → content
    2. Compute embedding via Gemini (768-dim)
    3. Find neighbors via Rust HNSWIndex
    4. Compute trajectory via Rust IRCPPropagator
    5. Insert as memory_turn
    6. Trigger incremental learning (optional)
    """

@dataclass
class OrbitContext:
    """Context from Orbit orchestrator."""
    project_id: str          # Orbit project UUID
    session_id: str          # Orbit session UUID
    project_status: str      # "active", "paused", etc.
    project_name: str        # Human-readable name
    session_depth: int       # Depth within session
    turn_index: int          # Turn index
    working_directory: str   # CWD
    metadata: Dict[str, Any] # Additional context

@dataclass
class TrajectoryCoords:
    """5D trajectory coordinates."""
    x: float = 0.0   # Depth
    y: float = 0.0   # Sibling order
    z: float = 0.5   # Homogeneity
    t: float = 0.0   # Temporal
    n: float = 0.5   # Complexity
    phase: str = "exploration"

    def to_dict(self) -> Dict[str, Any]:
        return {
            "trajectory_depth": self.x,
            "trajectory_sibling_order": self.y,
            "trajectory_homogeneity": self.z,
            "trajectory_temporal": self.t,
            "trajectory_complexity": self.n,
            "trajectory_phase": self.phase,
        }

@dataclass
class IngestedTurn:
    """Result of ingesting a prompt."""
    turn_id: str
    prompt_id: str
    content: str
    role: str
    embedding: List[float]
    trajectory_coords: TrajectoryCoords
    orbit_project_id: str
    orbit_session_id: str
    created_at: datetime
    metadata: Dict[str, Any]

    def to_supabase_row(self, conversation_id: str) -> Dict[str, Any]:
        """Convert to Supabase memory_turns row."""
        ...

┌───────────────────────────────────────────────────────────────────────┐
│                        COGNITIVETWIN                                   │
│  ┌─────────────────┐  ┌──────────────────┐  ┌─────────────────────┐  │
│  │ ReasoningPattern│  │   Style          │  │   Pattern           │  │
│  │ Encoder         │──│   Projector      │──│   Memory            │  │
│  │ (768 → 1024)    │  │   (1024 → 256)   │  │   (10K patterns)    │  │
│  └────────┬────────┘  └────────┬─────────┘  └──────────┬──────────┘  │
│           │                    │                       │              │
│           └────────────────────┴───────────────────────┘              │
│                                │                                       │
│                                ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                    PromptGenerator                               │  │
│  │  Generates prompts/continuations in user's style                 │  │
│  └─────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────┘

class TrainingMode(str, Enum):
    BATCH_PROMPTS = "batch_prompts"      # Train on prompt/response pairs
    BATCH_TURNS = "batch_turns"          # Train on memory_turns
    REALTIME_STYLE = "realtime_style"    # Inference-only extraction
    INCREMENTAL = "incremental"          # Update per interaction

class TriggerType(str, Enum):
    SESSION_END = "session_end"    # Orbit session boundary
    SCHEDULED = "scheduled"        # Cron schedule (e.g., 3 AM daily)
    THRESHOLD = "threshold"        # After N incremental updates
    MANUAL = "manual"              # API/UI trigger

class HybridCognitiveTwinTrainer:
    async def batch_train_prompts(
        self, prompts: List[PromptResponsePair], epochs: int = 3
    ) -> TrainingMetrics:
        """Train on prompt/response pairs from claude_prompts."""

    async def batch_train_turns(
        self, turns: List[MemoryTurn], epochs: int = 3
    ) -> TrainingMetrics:
        """Train on unified memory_turns with trajectory context."""

    def realtime_style_extract(
        self, text: str, embedding: Optional[Tensor] = None
    ) -> StyleSignatureVector:
        """Extract style without training (inference only)."""

    async def incremental_learn(self, turn: MemoryTurn) -> None:
        """Update global signature after single interaction."""

    # Trigger handlers
    async def on_session_end(self, session_id: str) -> TrainingMetrics:
    async def on_schedule(self) -> TrainingMetrics:
    async def on_manual_trigger(self, mode: TrainingMode, filter: Dict)

class GlobalStyleSignature:
    """
    Evolving global style signature using Exponential Moving Average.

    signature = momentum * old + (1 - momentum) * weight * new
    """

    def __init__(
        self,
        dim: int = 256,
        momentum: float = 0.9,        # 90% old, 10% new
        snapshot_interval: int = 10,   # Snapshot every 10 updates
        max_history: int = 100,        # Keep last 100 snapshots
    ):
        self.signature = torch.zeros(dim)
        self.confidence = 0.0
        self.update_count = 0

    def blend(
        self,
        new_signature: Tensor,
        weight: float = 0.1,
        source: Optional[str] = None,
    ) -> None:
        """Blend new observation into global signature."""
        new_norm = F.normalize(new_signature.detach(), dim=0)
        self.signature = (
            self.momentum * self.signature +
            (1 - self.momentum) * weight * new_norm
        )
        self.signature = F.normalize(self.signature, dim=0)
        self.update_count += 1
        # Confidence: asymptotic to 1.0
        self.confidence = min(1.0, self.update_count / (self.update_count + 100))

def save(self, path: Path) -> None:
    torch.save(self.state_dict(), path)

@classmethod
def load(cls, path: Path) -> "GlobalStyleSignature":
    state = torch.load(path, weights_only=True)
    instance = cls(dim=state["dim"], momentum=state["momentum"])
    instance.load_state_dict(state)
    return instance

@dataclass
class StyleSignatureVector:
    """Current style signature with metadata."""
    vector: Tensor           # 256-dim style embedding
    confidence: float        # 0-1, how confident in signature
    update_count: int        # Number of blending updates
    last_updated: datetime   # When last updated

#[derive(Debug, Deserialize)]
struct RagIngestRequest {
    prompt_id: String,
    prompt_text: String,
    response_text: String,
    session_id: String,
    project_id: String,
    project_name: Option<String>,
    working_directory: Option<String>,
    turn_index: Option<i32>,
}

#[derive(Debug, Deserialize)]
struct RagTrainRequest {
    mode: Option<String>,     // "batch_prompts" | "batch_turns" | "incremental"
    filter: Option<Value>,    // {"project_id": "..."} optional filter
}

Project (Orbit)
    └── Session (Claude Code session)
            └── Turn (memory_turn)
                    ├── content
                    ├── embedding[768]
                    └── trajectory_coords[5]

UserPromptSubmit
        │
        ▼
    main.py
        │  ├── capture prompt
        │  ├── register pending
        │  └── sync_with_orbit()
        │
        ▼
    Stop (response complete)
        │
        ▼
    response_hook.py
        │  ├── capture response
        │  ├── extract tool calls
        │  ├── capture file diffs
        │  └── sync_full_prompt()
        │
        ▼
    orbit_sync.py
        │  ├── find_project_by_path()
        │  ├── update_project_activity()
        │  └── ingest_to_rag()

def sync_with_orbit(
    cwd: str,
    prompt_id: str,
    prompt_text: str,
    session_id: str,
    response_text: str = "",
) -> Optional[str]:
    """Basic sync - find project, update activity, optionally ingest."""

def sync_full_prompt(
    cwd: str,
    prompt_id: str,
    prompt_text: str,
    response_text: str,
    session_id: str,
    turn_index: int = 0,
) -> Tuple[Optional[str], Optional[str]]:
    """Full sync with RAG++ ingestion. Returns (project_name, memory_turn_id)."""

def ingest_to_rag(
    prompt_id: str,
    prompt_text: str,
    response_text: str,
    session_id: str,
    project_id: str,
    project_name: str,
    cwd: str,
    turn_index: int = 0,
) -> Optional[str]:
    """POST to /api/rag/ingest. Returns memory_turn_id."""

def notify_session_end(session_id: str, project_id: str) -> bool:
    """Notify Orbit of session end to trigger training."""

# Search unified memory_turns
{
    "name": "rag_search",
    "description": "Search the unified memory_turns knowledge fabric via RAG++.",
    "inputSchema": {
        "properties": {
            "query": {"type": "string"},
            "limit": {"type": "integer", "default": 10},
            "project_id": {"type": "string"}  # optional filter
        },
        "required": ["query"]
    }
}

# Get project context
{
    "name": "rag_context",
    "description": "Get contextual memory turns for a project/session.",
    "inputSchema": {
        "properties": {
            "project_id": {"type": "string"},
            "session_id": {"type": "string"},
            "limit": {"type": "integer", "default": 20}
        },
        "required": ["project_id"]
    }
}

# Get style signature
{
    "name": "rag_style_signature",
    "description": "Get the current global CognitiveTwin style signature."
}

# Trigger training
{
    "name": "rag_trigger_training",
    "description": "Trigger CognitiveTwin training via Orbit.",
    "inputSchema": {
        "properties": {
            "mode": {"enum": ["batch_prompts", "batch_turns", "incremental"]},
            "project_id": {"type": "string"}
        }
    }
}

# Health check
{
    "name": "rag_health",
    "description": "Check RAG++ and Orbit integration health."
}

┌─────────────┐
│ User types  │
│ prompt in   │
│ Claude Code │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ main.py hook    │
│ captures prompt │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Claude Code processes                        │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ response_hook.py captures:                                       │
│   - Full text response                                           │
│   - Tool calls (Read, Edit, Write, Bash)                        │
│   - File diffs                                                   │
│   - Timing metrics                                               │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ orbit_sync.sync_full_prompt()                                    │
│   ├── find_project_by_path(cwd)                                 │
│   ├── update_project_activity(project_id)                       │
│   └── ingest_to_rag(...)                                        │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ Orbit Server: POST /api/rag/ingest                              │
│   └── Forwards to PromptIngester                                │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ PromptIngester.ingest_prompt()                                   │
│   ├── content = f"User: {prompt}\n\nAssistant: {response}"      │
│   ├── embedding = GeminiEmbedder.embed(content)  [768-dim]      │
│   ├── neighbors = HNSWIndex.search(embedding, k=10)             │
│   ├── coords = compute_trajectory_coordinates(...)               │
│   ├── Supabase.insert(memory_turns, {...})                      │
│   └── HybridTrainer.incremental_learn(turn)                     │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ memory_turns table:                                              │
│   id: uuid                                                       │
│   content: "User: ...\n\nAssistant: ..."                        │
│   embedding: [768 floats]                                        │
│   trajectory_depth: 0.25                                         │
│   trajectory_sibling_order: 0.0                                  │
│   trajectory_homogeneity: 0.72                                   │
│   trajectory_temporal: 0.12                                      │
│   trajectory_complexity: 0.45                                    │
│   trajectory_phase: "implementation"                             │
│   metadata: {"source": "claude_prompt", "orbit_project_id": ...} │
└─────────────────────────────────────────────────────────────────┘

┌───────────────────┐     ┌───────────────────┐     ┌───────────────────┐
│   Session End     │     │    Scheduled      │     │    Threshold      │
│   (Orbit event)   │     │    (3 AM daily)   │     │    (50 updates)   │
└─────────┬─────────┘     └─────────┬─────────┘     └─────────┬─────────┘
          │                         │                         │
          ▼                         ▼                         ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                     HybridCognitiveTwinTrainer                          │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ on_session_end(session_id)                                      │    │
│  │   └── turns = fetch_session_turns(session_id)                   │    │
│  │       └── batch_train_turns(turns)                              │    │
│  │                                                                  │    │
│  │ on_schedule()                                                    │    │
│  │   └── turns = fetch_recent_turns(since=last_scheduled)          │    │
│  │       └── batch_train_turns(turns)                              │    │
│  │                                                                  │    │
│  │ _trigger_threshold_training()                                    │    │
│  │   └── batch_train_turns(pending_batch)                          │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                                 │                                       │
│                                 ▼                                       │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ batch_train_turns(turns):                                       │    │
│  │   1. Stack embeddings → [batch, 768]                            │    │
│  │   2. Stack trajectory_coords → [batch, 5]                       │    │
│  │   3. CognitiveTwin.learn_from_conversation(...)                 │    │
│  │   4. Update GlobalStyleSignature with batch                     │    │
│  │   5. Persist checkpoint                                         │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                                 │                                       │
│                                 ▼                                       │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ GlobalStyleSignature.blend_batch(style_embeddings)              │    │
│  │   └── signature = EMA(old_signature, weighted_avg(new))         │    │
│  │   └── confidence = min(1.0, updates / (updates + 100))          │    │
│  └────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────┐
│ MCP Tool Call:  │
│ rag_search      │
│ query="..."     │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────┐
│ MCP Server → Orbit Server: GET /api/rag/search?query=...       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ RAG++ Search Pipeline                                            │
│   1. query_embedding = GeminiEmbedder.embed(query, RETRIEVAL_QUERY)  │
│   2. candidates = Supabase.rpc('match_turns', {                  │
│        query_embedding: [...],                                   │
│        match_count: 20,                                          │
│        similarity_threshold: 0.7                                 │
│      })                                                          │
│   3. reranked = TrajectoryReranker.rerank(candidates, context)   │
│   4. return top_k                                                │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ Response:                                                        │
│ {                                                                │
│   "query": "...",                                                │
│   "results": [                                                   │
│     {                                                            │
│       "turn_id": "...",                                          │
│       "content": "...",                                          │
│       "similarity": 0.85,                                        │
│       "trajectory": {                                            │
│         "depth": 0.3,                                            │
│         "phase": "implementation"                                │
│       }                                                          │
│     },                                                           │
│     ...                                                          │
│   ]                                                              │
│ }                                                                │
└─────────────────────────────────────────────────────────────────┘

# Supabase
SUPABASE_URL=https://project.supabase.co
SUPABASE_ANON_KEY=eyJ...

# Orbit
ORBIT_SERVER_URL=http://localhost:3847
ORBIT_DATABASE_URL=[home-path]
ORBIT_STORAGE_BACKEND=sqlite  # sqlite | supabase | hybrid

# RAG++ Integration
RAG_INGEST_ENABLED=true

# Gemini (for embeddings)
GOOGLE_API_KEY=...

# Training
COGNITIVE_TWIN_CHECKPOINT_DIR=checkpoints/cognitive_twin
GLOBAL_SIGNATURE_PATH=checkpoints/cognitive_twin/global_signature.pt

@dataclass
class HybridConfig:
    enable_incremental: bool = True        # Run incremental learning
    incremental_weight: float = 0.1        # Weight for incremental blend
    threshold_count: int = 50              # Trigger batch after N updates
    signature_checkpoint_path: Path = ...  # Path to save signature
    style_dim: int = 256                   # Style embedding dimension
    batch_epochs: int = 3                  # Epochs for batch training
    min_batch_size: int = 10               # Minimum samples for batch
    auto_save_signature: bool = True       # Auto-persist after training

@dataclass
class ScheduleConfig:
    daily_hour: int = 3              # Hour for daily training
    daily_minute: int = 0            # Minute for daily training
    enable_daily: bool = True        # Enable daily training
    interval_hours: int = 24         # Interval between trainings
    timezone: str = "UTC"            # Timezone for scheduling
    celery_broker: str = "redis://localhost:6379/0"  # For distributed

# Fast (inference-optimized)
CognitiveTwinConfig.fast()
# - 2 attention heads
# - 128-dim style
# - Approximate retrieval

# Accurate (quality-optimized)
CognitiveTwinConfig.accurate()
# - 8 attention heads
# - 512-dim style
# - Exact retrieval

# Balanced (default)
CognitiveTwinConfig.balanced()
# - 4 attention heads
# - 256-dim style
# - Hybrid retrieval

class PromptIngester:
    async def ingest_prompt(
        self,
        prompt_id: str,
        prompt_text: str,
        response_text: str,
        orbit_context: OrbitContext,
    ) -> IngestedTurn:
        """Ingest single prompt."""

    async def ingest_batch(
        self,
        prompts: List[Dict[str, Any]],
        orbit_context: OrbitContext,
    ) -> List[IngestedTurn]:
        """Ingest batch of prompts."""

    def add_to_index(self, turn_id: str, embedding: List[float]) -> None:
        """Add turn to HNSW index."""

    def build_index_from_supabase(self, limit: int = 100000) -> int:
        """Build index from existing turns."""

class HybridCognitiveTwinTrainer:
    # Training modes
    async def batch_train_prompts(self, prompts, epochs) -> TrainingMetrics
    async def batch_train_turns(self, turns, epochs) -> TrainingMetrics
    def realtime_style_extract(self, text, embedding) -> StyleSignatureVector
    async def incremental_learn(self, turn) -> None

    # Triggers
    async def on_session_end(self, session_id) -> TrainingMetrics
    async def on_schedule(self) -> TrainingMetrics
    async def on_manual_trigger(self, mode, filter) -> TrainingMetrics

    # Signature management
    def get_global_signature(self) -> StyleSignatureVector
    def persist_global_signature(self) -> None
    def reset_global_signature(self) -> None

    # History
    def get_training_history(self) -> List[Dict[str, Any]]

class GlobalStyleSignature:
    def blend(self, new_signature, weight, source) -> None
        """Blend single signature."""

    def blend_batch(self, signatures, weights) -> None
        """Blend batch of signatures."""

    def current(self) -> StyleSignatureVector
        """Get current signature state."""

    def similarity(self, other) -> float
        """Cosine similarity with another signature."""

    def state_dict(self) -> Dict[str, Any]
        """For checkpointing."""

    def load_state_dict(self, state) -> None
        """Load from checkpoint."""

    def save(self, path) -> None
    def load(cls, path) -> GlobalStyleSignature
    def reset(self) -> None

class TrainingScheduler:
    def start(self) -> None
        """Start scheduler."""

    def stop(self) -> None
        """Stop scheduler."""

    async def trigger_now(self) -> Dict[str, Any]
        """Manual immediate trigger."""

    def add_callback(self, callback) -> None
        """Add completion callback."""

    def get_status(self) -> Dict[str, Any]
        """Get scheduler status."""

class OrbitSessionHandler:
    async def on_session_end(self, session_id, project_id) -> Dict[str, Any]
        """Handle session end event."""

    def on_session_start(self, session_id, project_id) -> None
        """Track session start."""

    def get_active_sessions(self) -> Dict[str, str]
        """Get currently active sessions."""

scripts/e2e_ingest_test.sh