# मेमोरी मॉडल

Synapse का मेमोरी मॉडल LLM एजेंट्स के लिए डिज़ाइन किया गया है — विश्वसनीय रिकॉल के लिए पर्याप्त संरचित, किसी भी डोमेन के लिए पर्याप्त लचीला।

## मेमोरी शरीर रचना

```json
{
  "id": "mem_abc123",
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed on vps1. CI green.",
  "tags": ["synapse", "deployment", "v1.5.0"],
  "priority": "high",
  "source": "agent",
  "verified": false,
  "confidence": 0.85,
  "expires_at": null,
  "mind_id": "m_xyz789",
  "created_at": "2026-06-27T...",
  "updated_at": "2026-06-27T..."
}
```

## फ़ील्ड्स

| फ़ील्ड | प्रकार | आवश्यक | विवरण |
|-------|------|----------|-------------|
| `id` | string | auto | अद्वितीय ID (mem_xxx) |
| `category` | enum | ✅ | 8 श्रेणियों में से एक |
| `key` | string | ✅ | स्थिर पहचानकर्ता (अपडेट के लिए उपयोग) |
| `content` | string | ✅ | मेमोरी सामग्री (कोई भी टेक्स्ट) |
| `tags` | string[] | – | खोज और फ़िल्टरिंग के लिए |
| `priority` | enum | – | low, normal, high, critical (डिफ़ॉल्ट: normal) |
| `source` | enum | auto | user, agent (किसने स्टोर किया) |
| `verified` | bool | auto | क्या किसी मानव ने इसे सत्यापित किया? |
| `confidence` | float | – | 0.0 से 1.0 (डिफ़ॉल्ट: user के लिए 1.0, agent के लिए 0.7) |
| `expires_at` | timestamp | – | यह मेमोरी कब भूलनी है |
| `mind_id` | string | auto | कौन सा mind इसका मालिक है |
| `created_at` | timestamp | auto | पहले स्टोर किया गया |
| `updated_at` | timestamp | auto | अंतिम बार संशोधित |

## श्रेणियाँ

आठ श्रेणियाँ सामान्य LLM एजेंट उपयोग के मामलों को कवर करती हैं:

| श्रेणी | उद्देश्य | उदाहरण सामग्री |
|----------|---------|-----------------|
| `identity` | उपयोगकर्ता कौन है | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | उपयोगकर्ता प्राथमिकताएँ | "Prefers concise technical responses" |
| `fact` | सत्यापित योग्य तथ्य | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | परियोजना स्थिति | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | उपयोगकर्ता के कौशल | "Advanced Python, 10+ years" |
| `mistake` | पिछली त्रुटियाँ | "Forgot to bump npm version — CI failed" |
| `context` | सत्र संदर्भ | "Currently reviewing PR #42" |
| `note` | विविध नोट्स | "Try Redis for caching next sprint" |

## कुंजी: स्थिर पहचानकर्ता

`key` फ़ील्ड महत्वपूर्ण है — यह डुप्लिकेट बनाए बिना मेमोरीज़ अपडेट करने का तरीका है।

```python
# First store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Update with same key (overwrites, doesn't duplicate)
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**कुंजी नियम:**

- (category, mind) के भीतर अद्वितीय होनी चाहिए
- `snake_case` का उपयोग करें
- स्पष्टता के लिए श्रेणी के साथ उपसर्ग: `preference_communication`, `mistake_npm_version`
- स्थिर रखें — निर्माण के बाद कुंजी न बदलें

## टैग्स: खोज के लिए

टैग्स तेज़ फ़िल्टरिंग और खोज सक्षम बनाते हैं:

```bash
# Find all memories with tag "docker"
GET /memory/by-tag?tag=docker

# FTS5 search within tagged subset
GET /memory/search?q=swarm&tag=docker
```

**टैग सर्वोत्तम प्रथाएँ:**

- प्रति मेमोरी 2-5 टैग्स (अधिक टैग न करें)
- निरंतरता के लिए लोअरकेस
- परियोजना नाम, विषय, तकनीकों का उपयोग करें
- टैग्स केस-असंवेदनशील हैं

## प्राथमिकता स्तर

| प्राथमिकता | कब उपयोग करें | रिकॉल व्यवहार |
|----------|-------------|-----------------|
| `critical` | पहचान, कानूनी, अपरिवर्तनीय | हमेशा रिकॉल के शीर्ष पर |
| `high` | सक्रिय परियोजनाएँ, मुख्य प्राथमिकताएँ | रिकॉल में प्रमुख |
| `normal` | अधिकांश मेमोरीज़ (डिफ़ॉल्ट) | मानक रिकॉल क्रम |
| `low` | क्षणिक, जानना-अच्छा | सारांशित हो सकता है |

`/memory/recall` प्राथमिकता द्वारा (critical पहले), फिर नवीनता द्वारा क्रमबद्ध करता है।

## स्रोत: User बनाम Agent

मेमोरीज़ को `source` के साथ टैग किया जाता है:

- `user` — किसी मानव द्वारा स्टोर किया गया (JWT या human UI के माध्यम से)
- `agent` — किसी LLM एजेंट द्वारा स्टोर किया गया (Mind Key के माध्यम से)

यह प्रभावित करता है:

- **सत्यापन**: `user` मेमोरीज़ ऑटो-सत्यापित हैं, `agent` मेमोरीज़ नहीं
- **विश्वास्यता**: `user` का डिफ़ॉल्ट 1.0, `agent` का 0.7
- **रिकॉल**: `/memory/recall` असत्यापित मेमोरीज़ को "(unverified)" से चिह्नित करता है

> [!NOTE]
> `agent`-स्रोत मेमोरीज़ के प्रति उचित संदेह रखें। ये सीधे उपयोगकर्ता द्वारा बताई गई नहीं, बल्कि अनुमानित या मानी गई हो सकती हैं।

## सत्यापन

`verified` फ़्लैग दर्शाता है कि किसी मानव ने मेमोरी की पुष्टि की है:

- `user` मेमोरीज़: ऑटो-सत्यापित (`true`)
- `agent` मेमोरीज़: डिफ़ॉल्ट असत्यापित (`false`)

मेमोरीज़ इसके माध्यम से सत्यापित करें:

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

> [!NOTE]
> सत्यापन के लिए Mind Key (एजेंट प्रमाणीकरण) नहीं, JWT (मानव प्रमाणीकरण) आवश्यक है। यह सुनिश्चित करता है कि केवल मानव ही मेमोरीज़ को सत्यापित के रूप में चिह्नित कर सकें।

## विश्वास्यता

`confidence` फ़ील्ड (0.0 से 1.0) दर्शाता है कि मेमोरी कितनी विश्वसनीय है:

- 1.0 — उपयोगकर्ता द्वारा सीधे बताई गई
- 0.7 — एजेंट द्वारा अनुमानित
- 0.5 — अनिश्चित, सत्यापन चाहिए
- 0.0 — स्पष्ट रूप से संदिग्ध

स्टोर करते समय विश्वास्यता सेट करें:

```json
{
  "category": "preference",
  "key": "prefers_dark_mode",
  "content": "User seems to prefer dark mode (based on their IDE screenshots)",
  "confidence": 0.5,
  "source": "agent"
}
```

## समाप्ति

समय-संवेदनशील मेमोरीज़ के लिए `expires_at` सेट करें:

```json
{
  "category": "context",
  "key": "current_meeting_topic",
  "content": "Discussing Q3 roadmap",
  "expires_at": "2026-06-28T00:00:00Z"
}
```

समाप्त मेमोरीज़ `/memory/recall` द्वारा लौटाई नहीं जातीं (लेकिन DB में अभी भी मौजूद हैं)।
जल्द ही समाप्त होने वाली मेमोरीज़ देखने के लिए `/memory/expiring?within=7d` का उपयोग करें।

## मेमोरी जीवनचक्र

```
                  ┌─────────────────┐
                  │     Create      │
                  │  POST /memory   │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     Active      │ ◀──── PUT /memory/:id (update)
                  │  (in recall)    │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Expired  │ │ Verified │ │ Deleted  │
        │ (in DB)  │ │ (flag)   │ │ (gone)   │
        └──────────┘ └──────────┘ └──────────┘
```

## रिकॉल व्यवहार

`GET /memory/recall` LLM संदर्भ के लिए अनुकूलित सादे-टेक्स्ट सारांश लौटाता है:

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

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

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
```

- प्राथमिकता द्वारा क्रमबद्ध (critical → low), फिर नवीनता द्वारा
- असत्यापित मेमोरीज़ `[unverified]` से चिह्नित
- संदर्भ के लिए टैग्स शामिल
- सादा टेक्स्ट (कोई JSON पार्सिंग आवश्यक नहीं)

## अगले कदम

- [Memory API](/docs/api/memory)
- [मेमोरी सर्वोत्तम प्रथाएँ](/docs/guides/memory-best-practices)
- [FTS5 Search](/docs/concepts/fts5-search)