TurboMemory ⚡

TurboMemory is a lightweight semantic storage engine for compressed embedding archives.

It combines:

• SQLite metadata indexing
• append-only transcript logging
• quantized embedding storage (4-bit / 6-bit / 8-bit packed format)
• topic-based partitioning + centroid prefiltering
• background consolidation (merge / prune / deduplicate)
• optional confidence decay + contradiction detection

TurboMemory is designed for local-first semantic search, offline RAG, and edge deployments.

Goal: deliver "SQLite simplicity" for semantic memory + compressed vector storage.

Why TurboMemory?

Embedding storage is expensive:

• float32 vectors consume large disk space
• most vector DBs are heavy to deploy
• local-first apps need portable storage formats

TurboMemory solves this by using TurboQuant-style packing to store embeddings efficiently while still enabling fast retrieval.

Features

Storage

• Append-only transcript/event log (durable ingestion)
• Topic-based storage files (load-on-demand)
• SQLite index for metadata + fast filtering
• Packed embedding formats: 4-bit / 6-bit / 8-bit

Retrieval

• centroid/topic prefilter to reduce search space
• configurable scoring pipeline
• optional verification filtering

Maintenance / Self-Healing

• background consolidation daemon
• deduplication and merging of similar chunks
• TTL expiration + confidence decay
• experimental contradiction detection

Installation

From PyPI (recommended)

pip install turbomemory

From source

git clone https://github.com/Kubenew/TurboMemory.git
cd TurboMemory
pip install -e .

With all features

pip install turbomemory[all]

Requirements

• Python 3.9+
• numpy >= 1.24.0
• sentence-transformers >= 2.2.0

Quickstart

CLI Usage

# Add memory
python -m turbomemory add_memory --topic notes --text "TurboMemory stores semantic chunks efficiently."

# Query
python -m turbomemory query --query "semantic storage" --k 5

# Get stats
python -m turbomemory stats

Python Usage

from turbomemory import TurboMemory

tm = TurboMemory(root="./tm_data")

# Add memory
tm.add_memory(
    topic="notes",
    text="TurboMemory stores semantic chunks efficiently.",
    ttl_days=365
)

# Query
results = tm.query("semantic storage", k=5)

for score, topic, chunk in results:
    print(f"[{score:.3f}] {chunk['text']}")

Example output:

[0.892] TurboMemory stores semantic chunks efficiently.
[0.756] Semantic search with compression
[0.723] Vector storage made simple

CLI Command Reference

See python -m turbomemory --help for full options.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        TurboMemory                              │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  CLI / API    │  │ Python SDK    │  │ Integrations │       │
│  └──────┬─────────┘  └──────┬─────────┘  └──────┬─────────┘       │
│         │                   │                   │                  │
│  ┌──────▼───────────────────▼───────────────────▼─────────┐    │
│  │                    Core Engine                         │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │    │
│  │  │ Quantization│  │   Search    │  │ Consolidation│    │    │
│  │  │  (4/6/8bit)│  │  (BM25+Vec) │  │   Daemon    │    │    │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │    │
│  └─────────┼────────────────┼────────────────┼────────────┘    │
│            │                │                │                 │
│  ┌─────────▼────────────────▼────────────────▼────────────┐  │
│  │                    Storage Layer                       │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │  │
│  │  │SQLite   │  │  TMF    │  │  .tmlog │  │  Sync   │   │  │
│  │  │Index    │  │ Vectors │  │   Log   │  │ Protocol│   │  │
│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

Benchmarks

Compression Ratios

Query Latency

Recall Quality

Run benchmarks yourself:

python -m turbomemory.benchmark

Comparison

Integrations

LangChain

from turbomemory.integrations import TurboMemoryVectorStore

vectorstore = TurboMemoryVectorStore(root="./data", topic="docs")
vectorstore.add_texts(["doc1", "doc2"])
docs = vectorstore.similarity_search("query")

LlamaIndex

from turbomemory.integrations import getTurboMemoryIndex

index = getTurboMemoryIndex(root="./data")
query_engine = index.as_query_engine()
response = query_engine.query("your question")

Limitations

• No distributed clustering - Designed for single-node deployment
• No real-time multi-writer - Single-writer with eventual consistency via sync
• HNSW/IVF not default - Uses centroid prefilter; optional HNSW available
• Model pinned at ingest - All vectors must use same embedding model

Glossary

• Centroid prefilter: Pre-selects relevant topics using centroid similarity before full search
• Confidence decay: Reduces confidence of older memories over time
• Contradiction detection: Detects conflicting information and adjusts confidence
• Consolidation: Background process to merge/prune/optimize storage
• TurboQuant: 4/6/8-bit packed quantization for embeddings
• TMF: TurboMemory Format - portable storage format specification

Roadmap

See ROADMAP.md

Docker

# Build
docker build -t turbomemory .

# Run
docker run -p 8000:8000 turbomemory

# Or use docker-compose
docker compose up

Contributing

Contributions are welcome!

1. Fork the repo
2. Create a feature branch
3. Run tests: pytest tests/
4. Run linters: ruff check . && black .
5. Submit a PR

See CONTRIBUTING.md for details.

License

MIT License - see LICENSE

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Star History