# अंतर्निहित ज्ञान आर्किटेक्चर

Episteme ज्ञान की दो विशिष्ट परतों का प्रबंधन करता है: **कैननिकल** (अपरिवर्तनीय, क्यूरेट किया गया) और **अंतर्निहित** (परिवर्तनीय, उपयोगकर्ता-योगदान)। यह दस्तावेज़ दो-डेटाबेस आर्किटेक्चर, डेटा प्रवाह और अंतर्दृष्टि जीवनचक्र का वर्णन करता है।

## अवलोकन

| | कैननिकल ज्ञान | अंतर्निहित ज्ञान (अंतर्दृष्टि) |
|---|---|---|
| **भंडारण** | `~/.episteme/db/episteme.db` | `~/.episteme/user_knowledge.db` |
| **परिवर्तनीयता** | केवल-पढ़ने के लिए (`epis build` के माध्यम से पुनर्निर्मित) | पढ़ें-लिखें (MCP के माध्यम से वास्तविक समय) |
| **ID उपसर्ग** | `DP-NNN`, `RF-NNN`, `LAW-NNN`, `SMELL-NNN` | `TK-NNN` |
| **स्रोत** | `raw/` में क्यूरेट की गई Markdown फ़ाइलें | MCP `add_insight` टूल / CLI `epis insight` |
| **एंटिटीज़** | 22 पैटर्न, 66 रिफैक्टरिंग, 56 नियम, 23 स्मेल | असीमित उपयोगकर्ता अंतर्दृष्टि |

ये दो डेटाबेस भौतिक रूप से अलग हैं लेकिन रनटाइम पर एक एकल पारगमनीय ग्राफ में विलय होते हैं।

## दो-डेटाबेस डिज़ाइन

```
┌─────────────────────────────────┐     ┌──────────────────────────────┐
│  कैननिकल DB (episteme.db)       │     │  उपयोगकर्ता ज्ञान DB         │
│                                 │     │  (user_knowledge.db)         │
│  ┌───────────┐  ┌────────────┐  │     │  ┌────────────────────────┐  │
│  │  chunks   │  │ embeddings │  │     │  │  user_entities         │  │
│  │  (914)    │  │  (914)     │  │     │  │  (TK-xxx प्रविष्टियाँ)  │  │
│  └───────────┘  └────────────┘  │     │  ├────────────────────────┤  │
│                                 │     │  │  user_relations        │  │
│  बनाया गया: epis build          │     │  ├────────────────────────┤  │
│  से भरा गया: raw/*.md           │     │  │  user_embeddings       │  │
│                                 │     │  ├────────────────────────┤  │
│  रनटाइम पर अपरिवर्तनीय         │     │  │  user_entities_fts     │  │
│                                 │     │  │  (FTS5 खोज इंडेक्स)    │  │
└──────────────┬──────────────────┘     │  ├────────────────────────┤  │
               │                        │  │  insight_seq           │  │
               │                        │  │  (परमाणु ID काउंटर)     │  │
               │                        │  └────────────────────────┘  │
               │                        │                              │
               │                        │  लिखा गया: MCP add_insight   │
               │                        │  पढ़ा गया: search_insights   │
               │                        └──────────────┬───────────────┘
               │                                       │
               └───────────────┬───────────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │   CompositeGraph    │
                    │   (इन-मेमोरी विलय)  │
                    │                     │
                    │  - एकीकृत एंटिटी    │
                    │    लुकअप            │
                    │  - क्रॉस-लेयर BFS   │
                    │  - क्रॉस-लेयर       │
                    │    पड़ोसी क्वेरीज़   │
                    │                     │
                    │  सभी MCP            │
                    │  टूल अनुरोध सेवा   │
                    └─────────────────────┘
```

### डेटाबेस अलग क्यों?

1. **सुरक्षा** — उपयोगकर्ता इनपुट क्यूरेट किए गए कैननिकल ज्ञान को दूषित नहीं कर सकता।
2. **स्वतंत्र जीवनचक्र** — कैननिकल ज्ञान बिल्ड पाइपलाइन के माध्यम से अपडेट होता है; अंतर्निहित ज्ञान वास्तविक समय में अपडेट होता है।
3. **पोर्टेबिलिटी** — कैननिकल परत को छूए बिना `user_knowledge.db` को मशीनों या टीमों में साझा करें।

## CompositeGraph

`CompositeGraph` स्ट्रक्ट (`src/domain/composite_graph.rs` में) स्टार्टअप पर दोनों परतों को एकल `GraphRepository` इंटरफ़ेस में विलय करता है:

- `relations.json` से कैननिकल `KnowledgeGraph` लोड करता है
- `UserGraphStore` के माध्यम से `user_knowledge.db` खोलता है
- दोनों परतों में एकीकृत `get_entity()`, `get_neighbors()`, `find_path()` प्रदान करता है
- उपयोगकर्ता संचालन कभी भी कैननिकल ग्राफ को संशोधित नहीं करते

### ग्रेसफुल फ़ॉलबैक

यदि `user_knowledge.db` खोला नहीं जा सकता (फ़ाइल अनुपस्थित, अनुमति त्रुटि), तो सिस्टम केवल-कैननिकल मोड में फ़ॉलबैक करता है। सभी 6 कैननिकल MCP टूल काम करते रहते हैं; 3 अंतर्निहित ज्ञान टूल त्रुटि लौटाते हैं।

## उपयोगकर्ता ज्ञान स्कीमा

```sql
-- कोर एंटिटी तालिका
CREATE TABLE user_entities (
    id TEXT PRIMARY KEY,                    -- उदा. "TK-001"
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    author TEXT NOT NULL DEFAULT 'user',
    confidence REAL NOT NULL DEFAULT 0.5,   -- 0.0 से 1.0
    evidence_count INTEGER NOT NULL DEFAULT 0,
    last_validated TEXT NOT NULL DEFAULT '',
    tags TEXT NOT NULL DEFAULT '[]',        -- JSON ऐरे
    relations TEXT NOT NULL DEFAULT '{}',   -- JSON: प्रकार -> [लक्ष्य ID]
    created_at TEXT NOT NULL DEFAULT '',
    updated_at TEXT NOT NULL DEFAULT '',
    link_provenance TEXT NOT NULL DEFAULT '{}'  -- JSON: एंटिटी ID -> मेटाडेटा
);

-- स्पष्ट संबंध किनारे
CREATE TABLE user_relations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    from_id TEXT NOT NULL,
    relation_type TEXT NOT NULL,
    to_id TEXT NOT NULL,
    UNIQUE(from_id, relation_type, to_id)
);

-- एम्बेडिंग वेक्टर (f32, लिटिल-एंडियन)
CREATE TABLE user_embeddings (
    entity_id TEXT PRIMARY KEY,
    embedding BLOB NOT NULL
);

-- फ़ुल-टेक्स्ट खोज इंडेक्स
CREATE VIRTUAL TABLE user_entities_fts USING fts5(
    title, content, tags,
    content=user_entities, content_rowid=rowid
);

-- परमाणु ID अनुक्रम
CREATE TABLE insight_seq (key TEXT PRIMARY KEY, val INTEGER NOT NULL);
```

## MCP टूल्स

### add_insight

मुक्त पाठ से `TK-NNN` एंटिटी बनाता है। सिस्टम स्वचालित रूप से:

1. **कैननिकल एंटिटी लिंक का पता लगाता है** — दो-चरण कीवर्ड मिलान (स्टॉप-वर्ड फ़िल्टरिंग + कंपोजिट स्कोरिंग) प्रासंगिक पैटर्न, नियम और स्मेल खोजता है।
2. **डुप्लिकेट की जाँच करता है** — मौजूदा अंतर्दृष्टियों से तुलना करता है।
3. **`derives_from` संबंध बनाता है** — उच्च-विश्वास लिंक (स्कोर >= 0.5) के लिए, स्वचालित रूप से कैननिकल एंटिटीज़ से लिंक करता है।
4. **सहसंबंधों की गणना करता है** — Jaccard समानता का उपयोग करके संबंधित अंतर्दृष्टियाँ खोजता है।

पैरामीटर:
- `text` (आवश्यक) — मुक्त-पाठ अंतर्दृष्टि सामग्री
- `project` (वैकल्पिक) — प्रोजेक्ट नाम टैग
- `tags` (वैकल्पिक) — श्रेणी टैग
- `linked_entities` (वैकल्पिक) — लिंक करने के लिए स्पष्ट एंटिटी ID (उदा. `["DP-005", "SMELL-01"]`)

### search_insights

उपयोगकर्ता-योगदान की अंतर्दृष्टियों में FTS5 कीवर्ड खोज। मिलान करने वाली `TK-*` एंटिटीज़ उनकी सामग्री और संबंधों के साथ लौटाता है।

पैरामीटर:
- `query` (आवश्यक) — प्राकृतिक-भाषा खोज क्वेरी
- `limit` (वैकल्पिक) — अधिकतम परिणाम (डिफ़ॉल्ट 10, अधिकतम 20)

### confirm_links

एक अंतर्दृष्टि और कैननिकल एंटिटीज़ के बीच स्वतः-पहचाने गए लिंक को मान्य या अस्वीकार करता है। प्रत्येक पुष्टि:

- अंतर्दृष्टि का विश्वास स्कोर बढ़ाती है (प्रत्येक पुष्ट लिंक +0.05, अधिकतम 1.0)
- लिंक प्रोवेनेंस रिकॉर्ड करती है (स्रोत, स्कोर, टाइमस्टैंप)
- अंतर्दृष्टियों के बीच मर्ज/सुपरसीड संबंधों का समर्थन करती है

पैरामीटर:
- `insight_id` (आवश्यक) — `TK-NNN` ID
- `accepted` (आवश्यक) — मान्य लिंक के रूप में पुष्ट करने के लिए एंटिटी ID
- `rejected` (वैकल्पिक) — अस्वीकार करने के लिए एंटिटी ID
- `merged_with` (वैकल्पिक) — मर्ज/सुपरसीड के लिए लक्ष्य अंतर्दृष्टि ID

## अंतर्दृष्टि जीवनचक्र

```
1. add_insight("마이크로서비스 분리 시 도메인 경계를 먼저 식별하기로 결정")
       │
       ▼
2. स्वतः-लिंक पहचान: CONWAY-001 (Conway's Law), DP-026 (Strangler Fig)
       │
       ▼
3. TK-001 बनाएँ जिसमें derives_from → LAW-017, DP-026
       │
       ▼
4. confirm_links(insight_id="TK-001", accepted=["LAW-017"])
       │
       ▼
5. विश्वास बढ़ाया गया: 0.5 → 0.55
       │
       ▼
6. बाद में: search_insights("마이크로서비스 분리") → TK-001 लौटाता है
       │
       ▼
7. find_path("TK-001", "SMELL-03") → क्रॉस-लेयर ग्राफ ट्रैवर्स करता है
```

## संबंध प्रकार

| संबंध | दिशा | विवरण |
|--------|--------|-------------|
| `derives_from` | TK → कैननिकल | अंतर्दृष्टि एक कैननिकल एंटिटी पर आधारित है |
| `applies_to` | TK → कैननिकल | अंतर्दृष्टि एक पैटर्न/नियम को विशिष्ट संदर्भ में लागू करती है |
| `supersedes` | TK → TK | नई अंतर्दृष्टि पुरानी को प्रतिस्थापित करती है |
| `related_to` | TK → TK/कैननिकल | सामान्य सिमेंटिक कनेक्शन |

## CLI उपयोग

```bash
# अंतर्दृष्टि जोड़ें
epis insight add "팀에서 God Class 리팩토링 시 Extract Class보다 Facade Pattern이 효과적이었음"

# अंतर्दृष्टि खोजें
epis insight search "인증 미들웨어"

# सभी अंतर्दृष्टियाँ सूचीबद्ध करें
epis insight list
```

## प्रमुख स्रोत फ़ाइलें

| फ़ाइल | भूमिका |
|--------|------|
| `src/domain/composite_graph.rs` | कैननिकल + उपयोगकर्ता परतों का रनटाइम विलय |
| `src/adapters/user_graph_store.rs` | SQLite-आधारित `MutableGraphRepository` |
| `src/server/mcp_insight.rs` | 3 अंतर्निहित ज्ञान टूल्स के लिए MCP हैंडलर |
| `src/adapters/insight_utils.rs` | ID जनरेशन, टाइमस्टैंप, टेक्स्ट उपयोगिताएँ |
| `src/domain/types.rs` | `UserEntity`, `LinkProvenance`, `EntityType::Insight` |
| `src/ports/graph.rs` | `MutableGraphRepository` trait (14 विधियाँ) |
