Karjimut: Arsitektur Memori Dua Lapis Berbasis Model Context Protocol dengan Konsolidasi Fase Idle

Dikembangkan oleh Naufal Arhab Fadhil Muhammad

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:

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

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

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:

{
  "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)

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)

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.