# Thermocline — Complete LLM Context

> Thermocline is an open-source, AI-native document database with automatic tiered storage, built-in vector search, time travel, Raft replication, and full MongoDB wire protocol compatibility.

Organization: StronglyAI, Inc.
License: SSPL v1
Website: https://thermocline.org
GitHub: https://github.com/strongly-ai/thermocline
Cloud: https://thermoclinecloud.com

## What Is Thermocline?

Thermocline is a complete database built from the ground up — not a wrapper around MongoDB or any other database. It implements the MongoDB wire protocol so existing applications work with just a connection string change. It is named after the oceanographic phenomenon where warm surface water meets cold deep water, reflecting its automatic hot/cold tiered storage architecture.

## Key Differentiators

1. **Native Storage Engine**: LSM-tree with WAL, not a proxy. Sub-millisecond point reads, 50K+ writes/sec.
2. **Automatic Tiered Storage**: Data flows from hot (NVMe/SST) to cold (Parquet on S3) transparently. Queries federate across both tiers.
3. **Built-in Vector Search**: HNSW (in-memory) and DiskANN (disk-based) indexes. $vectorSearch aggregation stage. Hybrid search with pre/post filtering.
4. **Time Travel**: MVCC versioning. Read data at any historical timestamp. Database branching via MVCC snapshots.
5. **Raft Consensus**: Built-in replication with automatic leader election, <5s failover, strong consistency.
6. **60-80% Cost Reduction**: Hot tier for active data, cold tier on cheap object storage. Automatic archival policies.
7. **Platform Features**: REST API, realtime WebSockets, auth, file storage, queues, triggers, MCP server, edge functions — all built in.

## Architecture

```
Client App → Gateway (Rust) → Coordinator (Go) → Storage Engine (Rust) [hot]
                                               → Query Engine (Rust) → S3 [cold]

Storage Engine: WAL → Memtable → SST files (hot) → Parquet (cold)
Replication: Raft consensus across Storage Engine nodes
Controller (Go) handles archival, backup, lifecycle
```

### Components

| Component | Language | Purpose |
|-----------|----------|---------|
| Gateway | Rust | MongoDB wire protocol, 50K+ connections, TLS, auth |
| Coordinator | Go | Query routing, hot+cold merge, cursor management |
| Storage Engine | Rust | LSM-tree, WAL, MVCC, Raft, HNSW/DiskANN, indexes |
| Query Engine | Rust | Parquet/Arrow cold storage queries via DataFusion |
| Controller | Go | Archival (hot→cold), backup/restore, lifecycle |

## Storage Tiers

- **Hot Tier**: NVMe SST files with in-memory indexes. Sub-millisecond reads.
- **Cold Tier**: Parquet files on S3/GCS/Azure Blob. Cost-optimized, columnar.
- **Archive Tier**: Glacier/deep archive for compliance and long-term retention.
- **Federation**: Coordinator transparently merges results from hot and cold tiers.

## Vector Search

Thermocline has native vector search — no external vector database needed.

- **HNSW**: In-memory approximate nearest neighbor. >95% recall@10, <10ms p50 latency.
- **DiskANN**: Disk-based ANN for billion-scale vectors. <100ms p50 latency.
- **$vectorSearch**: MongoDB aggregation stage for semantic search.
- **Hybrid Search**: Combine vector similarity with MQL filters (pre-filter, post-filter, auto).
- **Quantization**: SQ8 scalar quantization for 4x memory reduction with re-ranking.

Example:
```javascript
db.products.aggregate([
  { $vectorSearch: {
      index: "product_embeddings",
      path: "embedding",
      queryVector: [0.1, 0.2, ...],
      numCandidates: 100,
      limit: 10
  }},
  { $project: { name: 1, score: { $meta: "vectorSearchScore" } } }
])
```

## MongoDB Compatibility

Thermocline supports the MongoDB wire protocol (OP_MSG). Existing MongoDB drivers work without modification.

Supported: find, insert, update, delete, aggregate, createIndex, getMore, killCursors, count, distinct, findAndModify, listCollections, listDatabases, createCollection, drop, explain, $vectorSearch, change streams, transactions, and more.

## Deployment Options

- **Standalone**: Single binary, all components in one process. For development.
- **Distributed**: Separate pods for each component with Raft HA. For production.
- **Kubernetes**: Helm chart and Kubernetes operator with CRD.
- **Thermocline Cloud**: Managed SaaS at thermoclinecloud.com.

## Cloud Pricing (Thermocline Cloud)

| Plan | Platform Fee | Cluster Compute | Features |
|------|-------------|-----------------|----------|
| Free | $0 | tc.starter (free, auto-pauses) | All features, 1 cluster, 10GB hot |
| Developer | $29/mo | tc.developer ($49/mo) | 3 clusters, daily backups |
| Team | $99/mo | tc.production ($429/mo, 3-node HA) | 10 clusters, hourly backups, PITR |
| Business | $299/mo | tc.business ($899/mo, 3-node HA) | 25 clusters, VPC, LDAP/SSO, plugins |
| Enterprise | Custom | Custom | Unlimited, dedicated support |

## Plugins

- **GPU Acceleration**: CUDA-powered HNSW distance computation, KNN, graph construction, SQ8 quantized distance, re-ranking.
- **ML Engine**: In-database machine learning. 13 algorithms: linear/logistic/elastic-net regression, k-means, DBSCAN, naive Bayes, decision trees, PCA, SVD.
- **Intelligent Cache**: 3-tier adaptive caching (L1 memory, L2 SSD, L3 distributed) with ML-inspired eviction scoring and predictive pre-warming.

## Quick Start

```bash
# Docker
docker run -p 27017:27017 ghcr.io/strongly-ai/thermocline:latest

# Connect with mongosh
mongosh mongodb://localhost:27017

# Insert data
db.users.insertOne({ name: "Alice", embedding: [0.1, 0.2, 0.3] })

# Query
db.users.find({ name: "Alice" })
```

## Performance Targets

| Component | Metric | Target |
|-----------|--------|--------|
| Gateway | Connections | 50,000+ |
| Storage Engine | Point read (hot) | <1ms p50 |
| Storage Engine | Write throughput | 50,000+ ops/sec |
| Query Engine | Cold query | <500ms p50 |
| Vector Search | HNSW recall@10 | >95% |
| Vector Search | HNSW latency | <10ms p50 |
| Raft | Failover | <5s |