# सिमेंटिक खोज (Embeddings)

Synapse वेक्टर embeddings का उपयोग करके सिमेंटिक खोज का समर्थन करता है। FTS5 (कीवर्ड मिलान) के विपरीत, सिमेंटिक खोज **अर्थ** द्वारा मेमोरीज़ खोजती है — भले ही कोई कीवर्ड मेल न खाए।

## यह कैसे काम करता है

```
1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned
```

### Embeddings क्या हैं?

Embeddings टेक्स्ट के संख्यात्मक वेक्टर प्रतिनिधित्व हैं। समान अर्थ वाले टेक्स्ट के समान वेक्टर होते हैं। Synapse प्रत्येक मेमोरी की सामग्री के लिए एक वेक्टर (जैसे 1536 आयाम) जनरेट करता है।

### कोसाइन समानता

सिमेंटिक रूप से समान मेमोरीज़ खोजने के लिए, Synapse क्वेरी वेक्टर और प्रत्येक मेमोरी वेक्टर के बीच कोसाइन समानता की गणना करता है। उच्च समानता = अधिक प्रासंगिक।

## सिमेंटिक खोज कब उपयोग करें

### सिमेंटिक खोज का उपयोग करें जब:

- आप "X के बारे में मेमोरीज़" चाहते हैं जहाँ X स्टोर किए गए से अलग ढंग से वर्णित है
- FTS5 कोई परिणाम नहीं लौटाता (कोई कीवर्ड मिलान नहीं)
- आप वैचारिक समूहीकरण चाहते हैं (जैसे सभी "deployment" मेमोरीज़, भले ही कुछ "release" कहें)
- क्वेरी एक प्रश्न है: "how do we handle authentication?"

### FTS5 का उपयोग करें जब:

- आप सटीक कीवर्ड्स जानते हैं
- आपको बूलियन लॉजिक (AND, OR, NOT) चाहिए
- आपको सब-मिलीसेकंड प्रतिक्रिया चाहिए
- आप वाक्यांश मिलान चाहते हैं

## एंडपॉइंट

### GET /memory/semantic-search

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

प्रतिक्रिया:

```json
{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}
```

## उदाहरण

### परिनियोजन मेमोरीज़ खोजें

```bash
# FTS5 might miss some — semantic catches all
curl .../memory/semantic-search?q=deployment+process
```

"deployment", "release", "publishing", "rolling out", आदि के बारे में मेमोरीज़ लौटाता है।

### प्रमाणीकरण पैटर्न खोजें

```bash
curl .../memory/semantic-search?q=how+do+users+log+in
```

login, auth, JWT, session management, OAuth, आदि के बारे में मेमोरीज़ लौटाता है।

### समान मेमोरीज़ खोजें

```bash
# Find memories similar to a specific one
curl .../memory/related/mem_001
```

सिमेंटिक समानता का उपयोग करता है (साझा टैग्स और embedding वेक्टर्स के माध्यम से)।

## Embedding जनरेशन

### Embeddings कब जनरेट होते हैं?

- **मेमोरी स्टोर पर** — यदि embeddings सेवा कॉन्फ़िगर की गई है, तो embedding तुल्यकालिक रूप से जनरेट होता है
- **बैच जनरेशन** — `POST /memory/embed-batch` उन मेमोरीज़ के लिए embeddings जनरेट करता है जिनके पास नहीं हैं
- **अतुल्यकालिक अपडेट** — जब सामग्री अपडेट होती है, embedding पुनः जनरेट होता है

### Embedding प्रदाता

Synapse कॉन्फ़िगर करने योग्य embedding प्रदाताओं का समर्थन करता है:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **लोकल मॉडल** (Ollama या समान के माध्यम से)
- **कस्टम** (embeddings इंटरफ़ेस लागू करें)

पर्यावरण वेरिएबल्स के माध्यम से कॉन्फ़िगर करें:

```bash
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small
```

### बैच जनरेशन

कई मेमोरीज़ वाले minds के लिए जिनमें embeddings गायब हैं:

```bash
# Generate embeddings for up to 100 memories
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Check progress
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## प्रदर्शन

| ऑपरेशन | विलंबता |
|-----------|---------|
| Embedding जनरेट करें (OpenAI) | 100-200ms |
| सिमेंटिक खोज (1k मेमोरीज़) | 50-100ms |
| सिमेंटिक खोज (10k मेमोरीज़) | 200-500ms |
| बैच जनरेशन (100 मेमोरीज़) | 10-20s |

> [!NOTE]
> वेक्टर गणना के कारण सिमेंटिक खोज FTS5 से धीमी है। ज्ञात कीवर्ड्स के लिए FTS5, वैचारिक क्वेरीज़ के लिए सिमेंटिक का उपयोग करें।

## सीमाएँ

### Embeddings लागत

यदि OpenAI का उपयोग कर रहे हैं, तो embeddings जनरेट करने का खर्च आता है (text-embedding-3-small के लिए ~$0.02 प्रति 1M टोकन)। 10,000 मेमोरीज़ औसतन 100 टोकन प्रत्येक के लिए, यह ~$0.02 है — नगण्य।

### कोल्ड स्टार्ट

Embeddings कॉन्फ़िगर किए जाने से पहले स्टोर की गई मेमोरीज़ में embeddings नहीं होंगे। बैकफ़िल के लिए `POST /memory/embed-batch` चलाएँ।

### प्रदाता निर्भरता

यदि embeddings प्रदाता डाउन है, तो सिमेंटिक खोज विनम्रतापूर्वक विफल होती है (खाली परिणाम या त्रुटि लौटाती है)। FTS5 अभी भी काम करता है।

## जब Embeddings उपलब्ध नहीं हैं

यदि embeddings सेवा कॉन्फ़िगर नहीं है:

- `GET /memory/semantic-search` 503 Service Unavailable लौटाता है
- `POST /memory` अभी भी काम करता है (बस कोई embedding जनरेट नहीं होता)
- FTS5 खोज अभी भी काम करती है

## सर्वोत्तम प्रथाएँ

> [!TIP]
> - **वैचारिक क्वेरीज़ के लिए सिमेंटिक का उपयोग करें** — "how do we handle X?"
> - **विशिष्ट शब्दों के लिए FTS5 का उपयोग करें** — "docker swarm"
> - **नियमित रूप से embeddings बैकफ़िल करें** — `POST /memory/embed-batch`
> - **प्रदाता स्वास्थ्य की निगरानी करें** — सिमेंटिक खोज इस पर निर्भर करती है
> - **टैग्स के साथ संयोजित करें** — सिमेंटिक + टैग फ़िल्टर परिणाम संकरा करता है

## अगले कदम

- [FTS5 Search](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [आर्किटेक्चर](/docs/concepts/architecture)