# DriftOS

DriftOS is a conversational routing and memory system for AI agents. It transforms flat conversation logs into navigable semantic graphs, enabling focused context windows instead of dumping entire chat history into every LLM call.

Website: https://driftos.dev
License: MIT (Patent Pending)

## The Problem

AI applications dump entire conversation history into every LLM call:
- Unfocused context leads to worse responses
- Token waste increases costs (1000 messages = ~$5 per call)
- No structure means you can't query "what did we decide about X?"
- Linear context replay causes silent context corruption in multi-topic conversations
- Long context windows increase capacity but do not provide control or auditability

## The Solution

DriftOS detects topic shifts and routes messages into semantic branches:
- **STAY** - Same topic, continue in current branch
- **BRANCH** - Topic drift detected, create new branch  
- **ROUTE** - Return to a previous topic

Result: 20 relevant messages instead of 1000. Up to 50x cost reduction.

## Core Concepts

- **Conversational branches** - Messages grouped by semantic topic
- **Semantic routing** - Automatic detection of topic shifts
- **Context isolation** - Each branch maintains focused context
- **Decision provenance** - Every routing decision logged with reasoning
- **Fact extraction** - Structured facts extracted from branch conversations
- **Graph-native context** - Walk the graph to assemble optimal context

## How It Works

1. **Detect** - Analyze message for topic drift (semantic + functional)
2. **Route** - Decide: BRANCH / STAY / ROUTE
3. **Assemble** - Build optimal context from graph (current branch + related clusters)
4. **Explain** - Full audit trail with similarity scores and confidence values

## Two Routing Engines

### driftos-embed (Embedding-based)
- **Latency:** <200ms
- **Cost:** $0 for routing decisions
- **Accuracy:** Good
- **Model:** paraphrase-MiniLM-L6-v2
- **Best for:** Real-time applications, clear topic shifts

### driftos-core (LLM-based)
- **Latency:** 500-1000ms
- **Cost:** ~$0.001 per routing decision
- **Accuracy:** High
- **Model:** Llama 3.1 via Groq
- **Best for:** Nuanced understanding, subtle topic shifts

## Key Features

### Dual-Axis Drift Detection
- Semantic drift via embedding similarity
- Functional drift via conversational mode analysis
- Configurable thresholds with hysteresis
- Refractory periods prevent oscillation

### Intelligent NLP Pipeline
- Implicit anaphora detection (6 categories)
- OOV compound reference detection
- Entity overlap analysis
- Pure linguistic structure analysis (no regex)
- Local processing: spaCy + transformers.js

### Explainable Routing
- Every decision has an audit trail
- Similarity scores and confidence values
- Boost multipliers with reasons
- Built for compliance requirements

## Architecture

```
Message → NLP Pipeline → Drift Detection → Router → Storage → Context for LLM
```

Components:
- **NLP Pipeline:** spaCy + transformers.js
- **Embeddings:** paraphrase-MiniLM-L6-v2 (local)
- **NLP Analysis:** en_core_web_md
- **Storage:** PostgreSQL + Prisma
- **Framework:** Fastify + TypeScript
- **Zero external calls:** All routing decisions made locally

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/drift/route` | Route a message to a branch |
| GET | `/api/v1/drift/branches/:conversationId` | List all branches |
| GET | `/api/v1/context/:branchId` | Get optimized LLM context |
| POST | `/api/v1/facts/:branchId/extract` | Extract facts from branch |
| GET | `/api/v1/facts/:branchId` | Get existing facts |

## SDK

```bash
npm install @driftos/client
```

```typescript
import { createDriftClient } from '@driftos/client';

const drift = createDriftClient('http://localhost:3000');

// Route a message
const result = await drift.route('conv-123', 'I want to plan a trip to Paris');

// Get context for LLM
const { system, messages } = await drift.buildPrompt(result.branchId);

// Use with any LLM
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: system },
    ...messages,
    { role: 'user', content: 'What hotels do you recommend?' }
  ]
});
```

## MCP Integration

DriftOS provides an MCP server for Claude Desktop integration:
- GitHub: https://github.com/DriftOS/driftos-mcp-server

## Related Projects

- **driftos-core** - LLM-based routing (higher accuracy)
- **driftos-embed** - Embedding-based routing (faster, zero cost)
- **drift-sdk** - TypeScript/JavaScript SDK
- **driftos-mcp-server** - MCP server for Claude Desktop

## Key Claims

- Linear context replay causes silent context corruption in multi-topic conversations
- Long context windows increase capacity but do not provide control or auditability
- DriftOS routes messages into semantic branches and assembles scoped context
- Graph-native context management enables 50x cost reduction
- Sub-100ms NLP analysis with zero external API calls for routing