# vault-engine 🧠

> **Knowledge Graph & Vault Integrity Inspector for Obsidian Vaults & Second Brain via MCP**  
> *Pemindai graf pengetahuan, detektor tautan putus (broken wikilinks), penavigasi backlink, dan linter kepatuhan doktrin Markdown berstandar tinggi.*

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)](https://python.org)
[![MCP Protocol](https://img.shields.io/badge/MCP-Standard%20v1.0-orange.svg)](https://modelcontextprotocol.io)
[![Obsidian Ready](https://img.shields.io/badge/Obsidian-Wikilinks%20&%20Graph-purple.svg)](https://obsidian.md)

---

## 🏛️ Mengapa `vault-engine` Dibangun?

Seiring bertambahnya ratusan atau ribuan catatan di dalam Obsidian Vault (*Second Brain*), berbagai degradasi pengetahuan sering terjadi tanpa disadari:
- **Broken Wikilinks:** Tautan `[[...]]` yang merujuk ke catatan yang belum pernah dibuat atau salah ketik.
- **Orphan Notes:** Catatan penting yang terisolasi dan terlupakan (tidak memiliki tautan masuk maupun keluar).
- **Inkonsistensi Metadata:** Kunci frontmatter YAML yang hilang atau format penamaan berkas yang acak-acakan.
- **Hilangnya Doktrin Penutup:** Catatan teknis yang tidak mendokumentasikan apa yang sengaja ditunda (*Skipped*) dan kondisi kapan harus dikembangkan (*Add when*).

**`vault-engine` menyediakan mesin komputasi graf dan linter otomatis** yang dapat dipanggil langsung oleh AI Agent (Hermes, Claude, Cursor) maupun pengembang melalui CLI mandiri.

---

## ⚙️ Fitur Utama

1. **Knowledge Graph Inspector:**
   - Memetakan seluruh jaringan keterhubungan catatan berbasis wikilink `[[...]]`.
   - Menghitung metrik total nodes, total edges, densitas graf, dan mengidentifikasi *Central Hubs* (catatan paling berpengaruh).
   - Menemukan *Orphan Notes* (catatan terisolasi tanpa relasi).
2. **Backlink & Forward Link Navigator:**
   - Melacak catatan mana saja yang merujuk *ke* suatu catatan (*inbound backlinks*) dan catatan mana saja yang dirujuk *oleh* catatan tersebut (*outbound links*).
3. **Broken Link Detector:**
   - Memindai seluruh vault dalam hitungan milidetik untuk mendaftar seluruh tautan putus yang perlu diperbaiki atau dibuatkan catatannya.
4. **Doktrin Vault Linter:**
   - Memeriksa 6 kunci frontmatter wajib: `judul`, `kategori`, `tag`, `tanggal_dibuat`, `terakhir_diperbarui`, `tautan_terkait`.
   - Menegakkan konvensi penamaan berkas *Kebab-Case* (`Catatan-Arsitektur.md`).
   - Memverifikasi keberadaan baris penutup doktrin: `*Skipped:*` dan `*Add when:*`.
5. **Compliant Note Scaffolder:**
   - Otomatis menghasilkan templat catatan Markdown baru yang 100% mematuhi standar vault, lengkap dengan nama berkas kebab-case dan blok uji invarian berbasis `assert`.

---

## 🚀 Cara Pemasangan & Penggunaan

### 1. Menjalankan sebagai MCP Server (Hermes / Claude / AI Agent)
```bash
hermes mcp add vault-engine --command python3 --args -m vault_engine.server
```

Atau daftarkan ke konfigurasi MCP:
```json
{
  "mcpServers": {
    "vault-engine": {
      "command": "python3",
      "args": ["-m", "vault_engine.server"]
    }
  }
}
```

### 2. Menggunakan CLI Mandiri
```bash
# 1. Pindai metrik graf pengetahuan vault
python3 -m vault_engine.cli inspect --vault /path/to/vault

# 2. Audit kepatuhan standar catatan .md
python3 -m vault_engine.cli lint /path/to/vault/Catatan.md

# 3. Telusuri backlink catatan
python3 -m vault_engine.cli backlinks Nama-Catatan --vault /path/to/vault

# 4. Cari catatan terindeks
python3 -m vault_engine.cli search "arsitektur" --tag erp --vault /path/to/vault

# 5. Hasilkan templat catatan doktrin baru
python3 -m vault_engine.cli scaffold "Arsitektur Event Driven" --category backend -o /path/to/vault/Arsitektur-Event-Driven.md
```

---

## 🛠️ Daftar 6 Perkakas MCP (Tool Catalog)

| Nama Tool | Parameter | Fungsi Utama |
|:---|:---|:---|
| **`vault_inspect_graph`** | `vault_path`, `refresh` | Memindai jaringan graf pengetahuan: total catatan, total koneksi, central hubs, orphan notes, dan densitas graf. |
| **`vault_lint_note`** | `file_path_or_content`, `file_name` | Mengaudit kepatuhan frontmatter YAML, penamaan kebab-case, dan baris penutup doktrin (*Skipped & Add when*). |
| **`vault_get_backlinks`** | `note_stem`, `vault_path` | Menavigasi relasi backlink masuk (inbound) dan keluar (outbound) serta mendeteksi broken links pada catatan tertentu. |
| **`vault_find_broken_links`** | `vault_path` | Mendeteksi seluruh tautan wikilink putus yang merujuk ke berkas yang belum ada di vault. |
| **`vault_search`** | `query`, `tag`, `category` | Pencarian cepat terindeks berdasarkan kata kunci, saringan tag, atau kategori direktori. |
| **`vault_scaffold_note`** | `judul`, `kategori`, `tags_json` | Menghasilkan draf catatan Markdown baru yang 100% sah dan mematuhi seluruh standar integritas vault. |

---

## 🧪 Pengujian Unit (Test Suite)

```bash
python3 tests/test_all.py
```

Output:
```text
....
----------------------------------------------------------------------
Ran 4 tests in 0.004s

OK
```

---

## 📄 Hak Cipta & Lisensi

Diciptakan oleh **Bagas Saputra (Bagas Cihuy)** bersama **Hermes Architecture**.  
Dilisensikan di bawah [MIT License](LICENSE).