# Memory API

Memory API Synapse का हृदय है। यह संरचित मेमोरीज़ को स्टोर करने, पुनः प्राप्त करने, खोजने और प्रबंधित करने के लिए 22 एंडपॉइंट्स प्रदान करता है। सभी एंडपॉइंट्स को प्रमाणीकरण के लिए Mind Key की आवश्यकता है।

> [!CRITICAL]
> **हर सत्र की शुरुआत में हमेशा `GET /memory/recall` कॉल करें।** यह पिछले सत्रों से संदर्भ को पुनर्निर्माण करने का एकमात्र तरीका है।

## श्रेणियाँ

मेमोरीज़ को 8 श्रेणियों में व्यवस्थित किया गया है:

| श्रेणी | उपयोग का मामला |
|----------|----------|
| `identity` | उपयोगकर्ता नाम, भूमिका, संपर्क जानकारी, स्वयं के बारे में प्राथमिकताएँ |
| `preference` | पसंद, नापसंद, कार्य शैली, संचार प्राथमिकताएँ |
| `fact` | सत्यापित योग्य तथ्य (परियोजना विवरण, तिथियाँ, URL) |
| `project` | परियोजना स्थिति, मील के पत्थर, आर्किटेक्चर |
| `skill` | चीज़ें जिनमें उपयोगकर्ता अच्छा है |
| `mistake` | पिछली त्रुटियाँ — दोहराने से बचें |
| `context` | सत्र-प्रासंगिक संदर्भ |
| `note` | विविध नोट्स |

## प्राथमिकताएँ

- `low` — जानना अच्छा है
- `normal` — डिफ़ॉल्ट
- `high` — महत्वपूर्ण
- `critical` — कभी न भूलें (उपयोगकर्ता पहचान, कानूनी जानकारी)

## मुख्य एंडपॉइंट्स

### GET /memory/recall

सभी मेमोरीज़ को LLM-अनुकूलित सादे टेक्स्ट के रूप में लौटाता है। इसे हर सत्र की शुरुआत में कॉल करें।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

प्रतिक्रिया (text/plain):

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

नई मेमोरी स्टोर करें या मौजूदा को अपडेट करें (समान श्रेणी + कुंजी = अपडेट)।

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

प्रतिक्रिया: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

वैकल्पिक फ़िल्टर के साथ मेमोरीज़ की सूची बनाएँ।

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

ID द्वारा एक विशिष्ट मेमोरी अपडेट करें।

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

एकल मेमोरी हटाएँ।

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## खोज एंडपॉइंट्स

### GET /memory/search

FTS5 का उपयोग करके फुल-टेक्स्ट खोज।

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

FTS5 सिंटैक्स:

- कई शब्द = AND: `docker swarm`
- वाक्यांश: `"docker swarm"`
- उपसर्ग: `docker*`
- बूलियन: `docker OR kubernetes`
- बहिष्कार: `docker -swarm`

### GET /memory/semantic-search

एम्बेडिंग का उपयोग करके वैचारिक खोज (FTS5 से धीमा लेकिन अर्थ समझता है)।

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

वे मेमोरीज़ लौटाता है जो क्वेरी के साथ सिमेंटिक रूप से समान हैं, भले ही कोई कीवर्ड मेल न खाए। "X के बारे में मेमोरीज़ खोजें" के लिए उपयोगी जहाँ X को अलग ढंग से वर्णित किया गया है।

### GET /memory/by-tag

टैग द्वारा मेमोरीज़ की सूची बनाएँ।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

किसी विशिष्ट मेमोरी से संबंधित मेमोरीज़ खोजें (साझा टैग के माध्यम से)।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## सिंक और Diff

### GET /memory/diff

इंक्रीमेंटल सिंक — किसी टाइमस्टैम्प के बाद से बदली गई मेमोरीज़ लौटाता है।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

प्रतिक्रिया: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

किसी अन्य इंस्टेंस से diff लागू करें (सेल्फ-होस्टेड सिंक के लिए)।

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## बल्क ऑपरेशन्स

### POST /memory/bulk-delete

ID द्वारा कई मेमोरीज़ हटाएँ।

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

उन मेमोरीज़ के लिए एम्बेडिंग जनरेट करें जिनके पास अभी तक नहीं हैं (सिमेंटिक खोज के लिए)।

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

### GET /memory/embed-batch-status

एम्बेडिंग जनरेशन प्रगति जाँचें।

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

## सत्यापन

मेमोरीज़ के पास `verified` फ़्लैग होता है। एजेंट-स्टोर की गई मेमोरीज़ डिफ़ॉल्ट रूप से असत्यापित होती हैं (`source=agent`); मानव-स्टोर की गई मेमोरीज़ सत्यापित होती हैं (`source=user`)।

### POST /memory/verify

मेमोरी को सत्यापित के रूप में चिह्नित करें (Mind Key नहीं, JWT आवश्यक)।

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

मेमोरी को असत्यापित के रूप में चिह्नित करें (JWT आवश्यक)।

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

मानव सत्यापन की प्रतीक्षा कर रही मेमोरीज़ की सूची बनाएँ।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## सांख्यिकी और ऑडिट

### GET /memory/stats

वर्तमान mind के लिए समग्र सांख्यिकी।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

लौटाता है: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

सभी स्थिति-परिवर्तनकारी ऑपरेशन्स का ऑडिट लॉग।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

स्टोर की गई मेमोरीज़ में संभावित विरोधाभासों का पता लगाएँ।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

समाप्ति तिथि निकट आ रही मेमोरीज़ की सूची बनाएँ।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## स्वास्थ्य और निर्यात

### GET /memory/health

मेमोरी सिस्टम के लिए त्वरित स्वास्थ्य जाँच।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

सभी मेमोरीज़ का पूर्ण JSON निर्यात (बैकअप के लिए)।

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

समान मेमोरीज़ संक्षिप्त करें (ऑटो-सारांशीकरण)।

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## अगले कदम

- [LLMs के लिए Quick Start](/docs/getting-started/quick-start-llm)
- [मेमोरी सर्वोत्तम प्रथाएँ](/docs/guides/memory-best-practices)
- [FTS5 Search](/docs/concepts/fts5-search)
- [सिमेंटिक खोज](/docs/concepts/semantic-search)