📚 Understanding Embeddings and Vector Databases with Qdrant

🧠 What Are Embeddings?

• Explain how text, images, audio, etc. are converted into vectors (mathematical representations)
• Introduce the concept of semantic similarity using vector distance
• Show why this matters (recall memory, search, retrieval, etc.)

---

📐 Understanding Vector Sizes

• Different embedding models produce different vector dimensions
  • mxbai-embed-large → 1024
  • text-embedding-3-small → 1536
  • all-MiniLM-L6-v2 → 384
• Qdrant needs you to declare this size when you create a collection
• Mismatch = 🔥 “Bad request, dimension error”

---

🧪 What Embedding Model Should You Use?

Model	Dimensions	Best for	Notes
mxbai-embed-large	1024	General memory	Great with LLMs
text-embedding-3-small	1536	Short-form text	OpenAI fallback
all-MiniLM-L6-v2	384	Lightweight use	Fast, decent

---

🔧 How to Create an Embedding + Insert Into Qdrant

import { createClient } from '@qdrant/js-client-rest';
import { getEmbedding } from './embedding';

const client = new QdrantClient({ url: 'http://localhost:6333' });

await client.upsert('guardian_memories', {
  points: [
    {
      id: 'memory_001',
      vector: await getEmbedding('This is an example memory.'),
      payload: {
        source: 'BlogPost',
        tags: ['guardian', 'blog'],
        timestamp: new Date().toISOString(),
      },
    },
  ],
});

• Your getEmbedding() function can call Ollama or an API
• Your collection must match the vector size

---

🧷 Qdrant + Guardian

• Qdrant is the long-term memory store
• Guardian uses it for:
  • Similarity search
  • Memory retrieval per task
  • Contextual enrichment for LLM calls
• Supabase handles metadata, Qdrant handles semantic recall

---

🛠 Common Problems

Issue	Cause	Fix
Dimension mismatch	Vector size doesn’t match Qdrant collection	Double-check the model you’re using
Service not found	Qdrant not running / wrong port	Restart Docker, check localhost:6333
Bad vector values	NaNs or zero-vectors	Normalize inputs before embedding

---

🧭 Next Steps

• Add a tag, source, or taskId to every memory
• Use filter + vector search together
• Log LLM decisions with addMemory() and classify them with runLLM()

---