Metadata-Version: 2.4
Name: karjimut
Version: 2.0.0
Summary: Karjimut — Arsitektur Memori Dua Lapis Berbasis Model Context Protocol (MCP) dengan Konsolidasi Fase Idle
Author: Naufal Arhab Fadhil Muhammad
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2.0.0,>=1.2.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pytest>=8.0.0
Requires-Dist: customtkinter>=5.2.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: fastembed>=0.9.0
Requires-Dist: numpy>=1.21.0
Dynamic: license-file

<p align="center">
  <img src="assets/karjimut_banner.png" alt="Karjimut Logo" width="640" style="border-radius: 16px;" />
</p>

<h1 align="center">Karjimut: Arsitektur Memori Dua Lapis Berbasis Model Context Protocol dengan Konsolidasi Fase Idle</h1>

<p align="center">
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-1.2.0+-green.svg" alt="MCP Spec"></a>
  <a href="https://sqlite.org/wal.html"><img src="https://img.shields.io/badge/SQLite-WAL%20Mode-orange.svg" alt="SQLite WAL"></a>
  <a href="../LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

<p align="center">
  Dikembangkan oleh <strong>Naufal Arhab Fadhil Muhammad</strong>
</p>

---

## 1. Ikhtisar Arsitektur

**Karjimut** memecahkan masalah pembengkakan *context window*, polusi log sampah, dan amnesia lintas sesi pada Autonomous AI Agent (Cursor, Antigravity, Claude Code, Cline) dengan memisahkan memori ke dalam dua lapisan:

| Lapisan Memori | Kapasitas Token | Karakteristik Isi | Primitif MCP |
| :--- | :--- | :--- | :--- |
| **Lapis 1: KTP Proyek** (*Elastic Core Project Identity*) | **Elastic Core** (Fleksibel mengikuti skala proyek via `KTP_MAX_TOKENS=0`; opsional batas keras $\le 150$ token) | Identitas dasar, *tech stack*, struktur direktori inti, dan aturan wajib proyek (dilengkapi tautan *1-Hop Causal Graph* `[Solusi #ID]`). | MCP Tool `baca_ktp_proyek(kode_proyek)` & Resource `karjimut://{kode_proyek}/ktp` |
| **Lapis 2: Laci Arsip Solusi** (*On-Demand Solution Vault*) | **0 Token di awal sesi** (Dipanggil saat dibutuhkan) | Intisari solusi konkret atas error teknis / bug dengan multi-tag gejala, *confidence score*, & *self-cleaning superseding* (`supersedes_id`). | MCP Tool `cari_laci_solusi(kode_proyek, kata_kunci)` (Hybrid BM25 + Vector RRF) |

Pencatatan aktivitas kerja selama sesi dilakukan secara asinkron dan instan via MCP Tool `titip_catatan_kerja(kode_proyek, ringkasan_aksi)` ke tabel `antrean_mentah`. Saat pengguna tidak aktif ($\ge 5$ menit), **Idle Watcher** secara otomatis memicu **7-Step Sleep Cycle** untuk merangkum log mentah, memperbarui KTP Proyek, mendeprekasi solusi usang (*Self-Cleaning*), mengekstrak solusi bug ke Laci Arsip, dan menyinkronkan memori tim ke `.karjimut/team_memory.jsonl`.

---

## 2. Struktur Direktori Proyek

```text
sleep-mcp/
|-- assets/
|   |-- karjimut_banner.png   # Banner utama Karjimut
|   |-- karjimut_logo.png     # Logo maskot Karjimut (Sidebar GUI & Onboarding)
|   |-- karjimut.ico          # Ikon jendela aplikasi Windows (.ico)
|-- .env.example              # Template konfigurasi environment
|-- requirements.txt          # Dependensi proyek
|-- README.md                 # Dokumentasi operasional & arsitektur
|-- MULAI_DISINI.bat          # Peluncur 1-Klik Desktop GUI (Windows)
|-- run.py                    # Entrypoint utama (GUI, MCP Server, CLI, Test, Benchmark)
|-- rules_template/
|   |-- .cursorrules          # Template instruksi Tiga Mandat Wajib (Cursor)
|   |-- antigravity_rules.md  # Template instruksi Tiga Mandat Wajib (Antigravity IDE)
|-- src/
|   |-- __init__.py
|   |-- config.py             # Pengaturan konfigurasi, batas token, credentials
|   |-- db.py                 # SQLite WAL mode, 6 tabel relasional + FTS5 + sqlite-vec
|   |-- tokenizer_utils.py    # Tiktoken cl100k_base, Elastic Core Mode, & Hard-Limit Guard
|   |-- fts_search.py         # Hybrid Search: FTS5 Okapi BM25 + FastEmbed Vector RRF
|   |-- embedding.py          # Mesin vektor lokal ONNX CPU (384 dimensi)
|   |-- consolidator.py       # Orkestrator 7-Step Sleep Cycle & Atomic Batch Locking
|   |-- log_parser.py         # Pemfilteran noise, ekstraksi tag/teknologi, & quality gate
|   |-- ktp_manager.py        # Penguraian, perenderan KTP, distiller lokal, & 1-Step Rollback
|   |-- llm_distiller.py      # Klien LLM multi-provider (JSON mode) & validasi skema
|   |-- archive_manager.py    # Deduplikasi laci_arsip, auto-supersede, decay, & Git Team Sync
|   |-- idle_watcher.py       # Daemon pemantau waktu idle (>= 5 menit) & status siklus
|   |-- mcp_server.py         # FastMCP Server: 4 Tools utama + Resource karjimut://
|   |-- services.py           # Lapisan layanan data GUI (Metrik A/B/C, CRUD Solusi, Manajemen Proyek)
|   |-- gui/
|       |-- __init__.py
|       |-- app_gui.py        # Controller utama Aplikasi Desktop Native (CustomTkinter)
|       |-- shell_layout.py   # Kerangka Sidebar, Top Header, 4 Kartu KPI, & Status Footer
|       |-- theme.py          # Palet warna TeamHub Soft Mint-Teal & Sage Green
|       |-- project_dialogs.py# Dialog tambah, ganti nama/gabung, & hapus proyek
|       |-- tab_ktp.py        # Halaman 1: Editor KTP Proyek, Live Token Counter, & Rollback
|       |-- tab_solusi.py     # Halaman 2: Bank Solusi BM25/RRF, CRUD, & Feedback Loop
|       |-- tab_antrean.py    # Halaman 3: Metrik Keberlanjutan A/B/C, Antrean Log, & Audit
|       |-- tab_settings.py   # Halaman 4: Auto-Detect API Key 1 Kolom & Generator Config MCP
|       |-- onboarding_dialog.py # Pop-up First-Run Onboarding Wizard (Auto-Detect API Key)
|       |-- key_detector.py   # Detektor otomatis prefix API Key & Self-Healing Model Selector
|       |-- i18n.py           # Kamus lokalisasi dwibahasa (Indonesia & Inggris)
|-- tests/
    |-- __init__.py
    |-- test_unit_core.py     # 21 Unit test inti (UT-01 s.d. UT-21)
    |-- test_v2_features.py   # 5 Unit test fitur Karjimut v2.0 (UT-22 s.d. UT-26)
    |-- benchmark_skripsi.py  # Simulasi 3 Skenario Rencana Pengujian (Bab 3)
    |-- output_benchmark/     # Hasil ekspor simulasi skenario (Markdown, CSV, dan JSON)
```

---

## 3. Cara Tercepat Menjalankan Sistem (1-Click / 1-Command)

Tidak perlu setup manual yang rumit. `run.py` akan **otomatis** menyiapkan `.env`, menginstal dependensi yang belum ada, menyiapkan database SQLite WAL, menyalakan *Idle Watcher* di background, dan membuka **Aplikasi Desktop Native (CustomTkinter)**.

### Opsi A: Klik 2x (Khusus Windows — Tanpa Jendela Terminal Hitam)
Klik dua kali file **`MULAI_DISINI.bat`** untuk langsung meluncurkan aplikasi desktop mandiri via `pythonw`. Saat pertama kali dibuka, pop-up **Setup Awal Karjimut** akan otomatis mendeteksi API Key Anda (`AIzaSy...` Gemini, `gsk_...` Groq, `sk-or-...` OpenRouter, `sk-ant-...` Claude, atau `sk-...` OpenAI) hanya dari satu kolom input.

### Opsi B: Satu Perintah di Terminal
```bash
cd sleep-mcp

# 1. Langsung buka Aplikasi Desktop Native Karjimut (CustomTkinter + Idle Watcher):
python run.py

# 2. Buka Menu Interaktif Terminal (Pilih 1-5):
python run.py menu

# 3. Jalankan 26 Unit & Integration Test:
python run.py test

# 4. Jalankan Simulasi 3 Skenario Rencana Pengujian (Bab 3) & sinkronkan DB:
python run.py benchmark
```

### Opsi C: Integrasi ke AI Agent (Antigravity / Cursor / Claude Desktop)
Jalankan `python run.py setup-ide` untuk menghasilkan file `mcp_config_siap_pakai.json` dengan path absolut perangkat Anda secara otomatis:
```json
{
  "mcpServers": {
    "karjimut": {
      "command": "python",
      "args": ["path/ke/sleep-mcp/run.py", "mcp"],
      "cwd": "path/ke/sleep-mcp"
    }
  }
}
```
> **Catatan:** *Idle Watcher* sudah otomatis berjalan di dalam proses MCP Server dan Aplikasi Desktop Native (*Embedded Mode*), sehingga Anda **tidak perlu** membuka terminal terpisah untuk menjalankan `idle_watcher.py`.

---

## 4. Tiga Mandat Wajib Workspace Bootstrap Rule

Agar agen AI bekerja secara deterministik dalam **Mode Vibecoder 100% Otomatis (Zero-Prompt)**, letakkan file `rules_template/.cursorrules` atau `rules_template/antigravity_rules.md` (`GEMINI.md` / `.agents/rules/sleep-mcp-auto.md`) pada root workspace proyek Anda:

1. **Mandat Inisialisasi (Awal Sesi):** AI Agent wajib memanggil `baca_ktp_proyek(kode_proyek, path_workspace)` pada giliran pertama sesi baru sebelum menulis kode.
2. **Mandat Pencatatan Milestone (Selama Sesi):** AI Agent wajib memanggil `titip_catatan_kerja(kode_proyek, ringkasan_aksi, path_workspace=...)` setiap menyelesaikan satu milestone kerja.
3. **Mandat Konsultasi Arsip (Saat Error):** AI Agent wajib memanggil `cari_laci_solusi(kode_proyek, kata_kunci, path_workspace=...)` saat menemui error terminal sebelum melakukan trial-and-error.

---

## 5. Rencana & Simulasi Skenario Pengujian (Bab 3)

### Menjalankan Seluruh 26 Unit Test (Pytest)
```bash
python -m pytest tests/test_unit_core.py tests/test_v2_features.py -v
```
Memverifikasi 26 kasus pengujian otomatis (`UT-01` s.d. `UT-26`):
- `UT-01` s.d. `UT-09`: Inisialisasi SQLite WAL Mode, Trigger FTS5 otomatis, pencarian BM25 dengan simbol `#`/`-`, *Stale Lock Sweeper* ($>3$ menit), *Hard-Limit Enforcement*, *1-Step Rollback* KTP, Deduplikasi Jaccard ($\ge 0,5$), *Offline Rule-Based Distiller*, dan konkurensi *multi-thread* bebas `SQLITE_BUSY`.
- `UT-10` s.d. `UT-21`: Layanan Desktop GUI (`src/services.py`), resolusi `path_workspace` (`peta_workspace`), *rename/merge* proyek (`alias_proyek`), proteksi anti-IDOR lintas proyek, ekstraksi hashtag otomatis, *Cross-Process File Lock*, *Auto-Detect API Key* 6 provider, *Self-Healing Model Selector*, lokalisasi ID/EN (`src/gui/i18n.py`), dan *Hybrid Search* (BM25 + ONNX Vector RRF).
- `UT-22`: **Elastic Core Mode** (`KTP_MAX_TOKENS=0`) menjaga keutuhan aturan proyek berskala besar tanpa pemotongan paksa.
- `UT-23`: **1-Hop Causal Graph Links** menautkan referensi `[Solusi #ID]` pada KTP Proyek ke Laci Arsip.
- `UT-24`: **Self-Cleaning Memory** (`supersedes_id`) otomatis mendeprekasi solusi lama yang usang.
- `UT-25`: **Multi-Team Git Sync** mengekspor dan mengimpor `.karjimut/team_memory.jsonl` lintas anggota tim secara idempoten.
- `UT-26`: **Confidence Score Weighting** memprioritaskan solusi dengan histori keberhasilan tertinggi.

### Menjalankan Simulasi 3 Skenario Rencana Pengujian (Bab 3)
```bash
python tests/benchmark_skripsi.py
```
Menghasilkan data simulasi skenario di `tests/output_benchmark/`:
- `skenario_1_efisiensi_token.csv` & `.json` (Efisiensi Token 40 Langkah / 5 Sesi)
- `skenario_2_konsistensi_aturan.csv` & `.json` (Retensi Aturan Arsitektur & Hard-Limit)
- `skenario_3_kecepatan_solusi.csv` & `.json` (Kecepatan One-Shot Resolution FTS5 BM25)
- `simulasi_skenario_pengujian.md` (Ringkasan tabel simulasi skenario pengujian)

---

## 6. Lisensi
Hak Cipta (c) 2026 Naufal Arhab Fadhil Muhammad. Dilisensikan di bawah lisensi MIT.
