TrajectoryOS

TrajectoryOS

The Long-Horizon Operating System

Version: 1.2.0
Last Updated: 2026-01-03
Status: Production
Parent: [00-OVERVIEW.md](00-OVERVIEW.md)
Complement: [03-ECHELON.md](03-ECHELON.md) (real-time engine)

---

Overview

TrajectoryOS is the operating system layer that provides long-horizon context, memory, and identity persistence across sessions. While Echelon handles real-time motion physics, TrajectoryOS answers a fundamentally different question:

> What does this moment mean in the context of everything else, and where does it sit in the long arc?

TrajectoryOS operates in a meta-manifold of trajectories: sessions, projects, creative arcs, life phases, memory geometry, and symbolic traces.

Key Characteristics

---

Architecture

flowchart TB
    subgraph Input [Input Sources]
        Claude[Claude Prompts]
        Cursor[Cursor/Codex]
        Echelon[Echelon Segments]
    end

    subgraph Ingestion [Ingestion Layer]
        Hooks[Response Hooks]
        Sync[orbit_sync.py]
    end

    subgraph Storage [Storage Layer]
        Supabase[(Supabase)]
        MemTurns[memory_turns]
        Convos[conversations]
    end

    subgraph Core [RAG++ Core - Rust]
        HNSW[HNSW Index]
        IRCP[I-RCP Propagator]
        Traj5D[5D Trajectory]
    end

    subgraph ML [ML Layer - Python]
        Twin[CognitiveTwin]
        Trainer[Hybrid Trainer]
        Signature[Style Signature]
    end

    subgraph Output [Output]
        MCP[MCP Server]
        API[REST API]
        Viz[3D Topology]
    end

    Claude --> Hooks --> Sync --> Supabase
    Cursor --> Hooks
    Echelon --> Sync

    Supabase --> HNSW
    Supabase --> MemTurns
    MemTurns --> IRCP --> Traj5D

    HNSW --> Twin --> Signature
    Trainer --> Twin

    HNSW --> MCP
    Traj5D --> API
    Traj5D --> Viz

---

Core Components

RAG++ (Retrieval-Augmented Generation++)

RAG++ is not traditional RAG. It extends the paradigm with:

1. 5D Trajectory Coordinates: Every memory turn has position in a 5-dimensional conversation topology
2. I-RCP Propagation: Inverse Ring Contextual Propagation for computing attention weights
3. Salience Scoring: Dynamic importance based on recency, depth, impact, and role

Location: `core/cc-rag-plus-plus/`

5D Trajectory Coordinates

Each memory turn exists at a coordinate:

pub struct TrajectoryCoordinate5D {
    pub temporal: f64,      // Time since epoch (normalized)
    pub semantic: f64,      // Semantic similarity to query
    pub depth: f64,         // Conversation depth (child of child of...)
    pub homogeneity: f64,   // Similarity to siblings
    pub salience: f64,      // Dynamic importance score
}

HNSW Index (Rust Core)

The Hierarchical Navigable Small World graph provides O(log n) approximate nearest neighbor search for memory retrieval.

Location: `core/cc-rag-plus-plus/crates/core/src/hnsw.rs`

pub struct HNSWIndex {
    pub layers: Vec<HNSWLayer>,
    pub entry_point: Option<usize>,
    pub max_level: usize,
    pub m: usize,          // Max connections per node
    pub ef_construction: usize,
    pub ef_search: usize,
}

I-RCP Propagator (Rust Core)

Computes attention weights using inverse ring propagation. Closer nodes in the trajectory receive higher attention.

Location: `core/cc-rag-plus-plus/crates/core/src/ircp.rs`

CognitiveTwin (Python ML)

The CognitiveTwin learns user reasoning patterns from accumulated memory turns. It produces:

1. Style Signature: A global embedding representing user communication style
2. Context Predictions: Anticipating what context the user might need
3. Reasoning Patterns: Modeling decision-making tendencies

Location: `core/cc-rag-plus-plus/rag_plusplus/ml/cognitive/`

---

Data Model

memory_turns Table

The unified knowledge fabric stores all interactions:

CREATE TABLE memory_turns (
    id UUID PRIMARY KEY,
    conversation_id UUID REFERENCES conversations(id),
    role TEXT NOT NULL,           -- 'user', 'assistant', 'system'
    content TEXT NOT NULL,
    content_embedding vector(1536),
    trajectory_coord JSONB,       -- 5D coordinates
    phase TEXT,                   -- 'exploration', 'implementation', etc.
    salience FLOAT,
    parent_turn_id UUID,
    metadata JSONB,
    created_at TIMESTAMPTZ
);

conversations Table

Groups related turns:

CREATE TABLE conversations (
    id UUID PRIMARY KEY,
    session_id TEXT,
    project_id UUID REFERENCES orbit_projects(id),
    title TEXT,
    summary TEXT,
    start_time TIMESTAMPTZ,
    end_time TIMESTAMPTZ,
    turn_count INTEGER,
    metadata JSONB
);

---

Integration with Echelon

TrajectoryOS and Echelon are complementary:

Bidirectional Flow

sequenceDiagram
    participant E as Echelon
    participant T as TrajectoryOS

    E->>T: Trajectory Segment (30s of motion)
    Note right of T: Stores as memory turn
    T->>E: Context Window (relevant history)
    Note left of E: Uses for anticipation priors
    E->>T: Gesture Detection Event
    Note right of T: Indexes with trajectory coords

---

Orbit Orchestration

Orbit is the project orchestrator that sits above TrajectoryOS:

flowchart LR
    subgraph Orbit [Orbit Server]
        Projects[Project Registry]
        Sessions[Session Manager]
        Proxy[RAG++ Proxy]
    end

    subgraph Storage [Storage]
        Files[(Project Files)]
        DB[(Supabase)]
    end

    subgraph Clients [Clients]
        Claude[Claude]
        Cursor[Cursor]
        Studio[CC Studio]
    end

    Claude --> Proxy
    Cursor --> Proxy
    Studio --> Proxy

    Proxy --> Projects
    Proxy --> Sessions
    Projects --> Files
    Sessions --> DB

Location: `apps/trajectory/trajectory-orbit/`

---

API Routes

RAG++ Service (FastAPI)

Orbit Server (Axum)

---

MCP Tools

The Model Context Protocol server exposes TrajectoryOS to AI assistants:

# Tools available via MCP
@server.tool("rag_search")
async def rag_search(query: str, limit: int = 10) -> list:
    """Search the unified memory fabric."""

@server.tool("rag_context")
async def rag_context(project_id: str, limit: int = 20) -> list:
    """Get contextual memory for a project."""

@server.tool("rag_style_signature")
async def rag_style_signature() -> dict:
    """Get current global style signature."""

Location: `[home-path]`

---

Training Pipeline

The CognitiveTwin is trained in batch and incremental modes:

Batch Training

trainer = HybridCognitiveTwinTrainer(supabase_url, supabase_key)

# Train on all historical data
trainer.train_batch(
    mode="batch_turns",
    project_id=None,  # All projects
    limit=10000
)

Incremental Training

# Trigger on session end
trainer.train_incremental(session_id="...")

---

Deployment

Cloud Run Services

Environment Variables

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
OPENAI_API_KEY=sk-...
ORBIT_SERVER_URL=https://orbit-server-*.run.app
RAG_SERVICE_URL=https://rag-plusplus-*.run.app

---

Further Reading

### Component Documentation
- [08-RAG_PLUS_PLUS.md](08-RAG_PLUS_PLUS.md) - Technical RAG++ details
- [09-ORBIT.md](09-ORBIT.md) - Orbit orchestration
- [03-ECHELON.md](03-ECHELON.md) - Real-time engine (complement)

Advanced Deep-Dive Documentation ✨

• [18-COGNITIVETWIN_BRIDGE.md](18-COGNITIVETWIN_BRIDGE.md) - TrajectoryOS ↔ Echelon integration
• FFI boundary between Python (RAG++) and Rust (Echelon)
• 5D coordinate transformation (Echelon segments → RAG++ trajectories)
• Temporal downsampling strategy (60Hz → 0.2Hz)
• Bidirectional style signature propagation

• [19-DELL_THEORY.md](19-DELL_THEORY.md) - DELL neural architecture
• CognitiveTwin training pipeline (PyTorch → Rust export)
• Dual-equilibrium dynamics (fast: real-time, slow: contextual)
• Style signature computation and embedding aggregation

• [20-SECURITY_ARCHITECTURE.md](20-SECURITY_ARCHITECTURE.md) - Security model
• JWT authentication with Supabase
• Row-Level Security (RLS) policies
• Secrets management (GCP Secret Manager)

• [21-OBSERVABILITY.md](21-OBSERVABILITY.md) - Monitoring and debugging
• Prometheus metrics for RAG++ (search latency, HNSW performance)
• Distributed tracing (OpenTelemetry/Jaeger)
• SLIs and SLOs for memory services

### Visual Documentation
- [diagrams/cognitivetwin-bridge-sequence.md](diagrams/cognitivetwin-bridge-sequence.md) - FFI sequence flow
- [diagrams/security-architecture.md](diagrams/security-architecture.md) - Trust boundaries and authentication
- [diagrams/system-dataflow.md](diagrams/system-dataflow.md) - Complete system data flow