MemoDokümantasyon
TR

Sistem Mimarisi

Memo, iki süreçli bir mimari izler: başsız bir Go arka ucu ve bir Flutter masaüstü/mobil ön ucu. localhost:8090 üzerinde REST + SSE ile iletişim kurarlar.

Üst Düzey Mimari

┌──────────────────────────────────────────────────┐
│                  Flutter Ön Uç                     │
│  ┌─────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │  Sohbet │  │  Model   │  │ Ayarlar (8 sekme)│ │
│  │  Ekranı │  │ Mağazası │  │ Sağlayıcı, Hafıza│ │
│  │         │  │          │  │ Ajan, Orkestra   │ │
│  └────┬────┘  └────┬─────┘  └────────┬─────────┘ │
│       │            │                 │            │
│  ┌────┴────────────┴─────────────────┴──────────┐ │
│  │              Riverpod Durum Katmanı           │ │
│  │   chatProvider, memoryProvider, agentProvider  │ │
│  └───────────────────────┬──────────────────────┘ │
│                          │                        │
│  ┌───────────────────────┴──────────────────────┐ │
│  │           Dio HTTP / SSE İstemcisi           │ │
│  │       MemoApiClient (singleton)               │ │
│  └───────────────────────┬──────────────────────┘ │
└──────────────────────────┼────────────────────────┘
                            │ HTTP + SSE
                            │ localhost:8090
┌──────────────────────────┼────────────────────────┐
│                          ▼                         │
│                Go Arka Ucu (app.go)                │
│  ┌──────────────────────────────────────────────┐ │
│  │           http.ServeMux Yönlendirici          │ │
│  │        ~90 REST + SSE uç noktası             │ │
│  └──────────────────────┬───────────────────────┘ │
│                         │                          │
│  ┌──────────────────────┴───────────────────────┐ │
│  │              AppBridge / FullBridge           │ │
│  │         İşleyicileri App'ten ayırır          │ │
│  └──────────────────────┬───────────────────────┘ │
│                         │                          │
│  ┌──────────────────────┴───────────────────────┐ │
│  │              Merkezi App Yapısı               │ │
│  │  Tüm alt sistemleri orkestre eder             │ │
│  └───┬───────┬───────┬──────┬──────┬────────────┘ │
│      │       │       │      │      │               │
│  ┌───┴─┐ ┌───┴─┐ ┌───┴─┐ ┌──┴──┐ ┌──┴──────────┐ │
│  │Hafıza│ │Ajan │ │Sağl.│ │Senkr│ │Takvim...     │ │
│  │Depo  │ │Yürüt│ │Yönld│ │Drive│ │29 paket      │ │
│  └─────┘ └─────┘ └─────┘ └─────┘ └──────────────┘ │
│                         │                          │
│  ┌──────────────────────┴───────────────────────┐ │
│  │             Veri Katmanı (SQLite/DS)          │ │
│  │  data/memory/ sessions/ models/ providers.json│ │
│  └──────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────┘

Süreç Tasarımı

Go Arka Ucu (main.go → internal/app/app.go)

Arka uç, başlatan tek bir Go ikili dosyasıdır:

  1. Yapılandırma — config/config.yaml dosyasını yükler
  2. Veritabanı başlatma — SQLite veritabanlarını açar, geçişleri çalıştırır, şemaları doğrular
  3. Sağlayıcı sistemi — Sağlayıcı yapılandırmalarını yükler, sağlık kontrolü goroutine'lerini başlatır
  4. llama.cpp yöneticisi — İsteğe bağlı olarak dahili llama-server sürecini başlatır
  5. Hafıza deposu — RAG deposunu başlatır, gömme modelini hazırlar
  6. Web sunucusu — http.ServeMux üzerinde ~90 yol kaydeder, :8090'da dinlemeye başlar
  7. Arka plan hizmetleri — WhatsApp, bulut senk., proaktif öğrenme, takvim hatırlatıcıları, hafıza düşüşü/birleştirme, ruh hali motoru

Tüm alt sistemler internal/app/app.go içindeki merkezi App yapısı aracılığıyla başlatılır.

Flutter Ön Ucu (frontend/lib/main.dart)

Flutter uygulaması masaüstü arayüzünü oluşturur ve arka uçla iletişim kurar:

  • Riverpod sağlayıcıları durumu yönetir ve MemoApiClient yöntemlerini çağırır
  • Dio HTTP isteklerini ve SSE akış ayrıştırmasını yönetir
  • 8 Ayarlar sekmesi her arka uç alt sistemini görsel olarak yapılandırır
  • Motor çubuğu aktif modellerin ve sağlayıcıların canlı durumunu gösterir

Modül Haritası — 38 Go Paketi

Paket Sorumluluk
internal/app/ Merkezi orkestratör — sohbet, hafıza, LLM, ajan akışları
internal/webserver/ HTTP işleyicileri, köprü deseni, SSE akışı
internal/memory/ RAG vektör deposu — gömme, arama, içe/dışa aktarma
internal/provider/ LLM sağlayıcı yönlendirme, API istemcileri (9 sağlayıcı), yedekleme
internal/orchestra/ Çoklu-model iş akışı — şef, 8 uzman rol
internal/agent/ Araç çağırma korumalı alanı — yürütücü, işlem hattı, izinler
internal/cloudsync/ Google Drive uçtan uca senk. — şifreleme, OAuth, aktarım
internal/whatsapp/ WhatsApp köprüsü — istemci, depo, mesaj işleme
internal/calendar/ Etkinlik deposu, hatırlatıcılar, niyet-etkinlik köprüsü
internal/sessions/ Sohbet oturumu kalıcılığı
internal/identity/ Sistem prompt'u, kişilik stilleri
internal/config/ YAML yapılandırma yükleme ve doğrulama
internal/skill/ opencode-uyumlu beceri sistemi
internal/mood/ Stokastik duygu motoru
internal/database/ SQLite yazma kuyruğu, bağlantı havuzu
internal/encryption/ AES-256-GCM, PBKDF2, anahtar yönetimi
internal/proactive/ Niyet çıkarımı, alışkanlık takibi, öğrenme döngüsü
internal/routine/ Rutinler — doğal dilden zamanlanmış otomasyonlar, cihaz saat dilimi senkronu
internal/swarm/ Memo Swarm (beta) — host/join, birden fazla PC arasında rpc-server ile model paylaşımı
internal/anthropicapi/ Geliştirici API Ağ Geçidi — yerel Anthropic-uyumlu uç nokta (/v1/messages)
internal/stats/ Kalıcı LLM kullanım olayı deposu — Ayarlar → İstatistikler sekmesi için
internal/taskloop/ CEO/Worker görev döngüsü — otonom görev listesi yürütme

Özelliğe Göre Veri Akışı

Sohbet Akışı

Kullanıcı mesaj yazar
  → Flutter ChatScreen
  → chatProvider.sendMessage(text)
  → MemoApiClient.postChatStream(body)   [POST /api/chat]
  → Go işleyici → App.Chat()
  → Sistem prompt'u oluştur (kimlik + ruh hali + beceriler)
  → Anıları getir (RAG hibrit arama)
  → Tam prompt'u oluştur (sistem + anılar + geçmiş + mesaj)
  → Sağlayıcıya yönlendir (yerel llama.cpp veya bulut API'si)
  → Token'ları SSE ile akış
  → Flutter SSE ayrıştırıcısı chatProvider'ı gerçek zamanlı günceller
  → Yanıttan sonra: oturumu kaydet, hafıza gömme vektörünü sakla

Hafıza Akışı

Yeni alışveriş tamamlandı
  → App.rememberExchange(userMsg, assistantReply)
  → Mesaj çiftini parçala (300 kelime, 50 kelime örtüşme)
  → Gömme vektörünü hesapla (llama.cpp ile nomic-embed-text-v1.5)
  → memory.db'ye yaz (memories + memory_vec + memory_fts tabloları)
  → Üç yazma arasında atomik işlem

Erişim (her yanıttan önce)
  → Kullanıcı sorgusu için gömme vektörü hesapla
  → Vektör arama (vec0, kosinüs benzerliği)
  → FTS5 arama (anahtar kelime eşleşmesi)
  → RRF birleştir (k=60)
  → Önem eşiğine göre filtrele
  → [İlgili Anılar] olarak sistem prompt'una ekle

Ajan Akışı

Kullanıcı ajan isteği gönderir
  → App.Chat() ajan modunu tespit eder
  → agent.Executor işlem hattını çalıştırır
  → Her araç çağrısı için:
      → İzinleri kontrol et (6 politika: izin ver, reddet, sor, oturum-izin, oturum-red, zaman aşımı)
      → Gerekirse izin iletişim kutusu göster
      → Aracı 60sn zaman aşımıyla çalıştır
      → Yolları doğrula (sembolik bağ koruması)
      → Sonucu tool_executing → tool_result olaylarıyla akış
  → İşlem hattı tamamlandıktan sonra (veya 20 yineleme):
      → Son LLM çağrısı tüm araç çıktılarını sentezler
      → Sentezlenmiş yanıtı döndür

Orkestra Akışı

Kullanıcı karmaşık görev gönderir
  → orchestra.Conductor alt görevleri planlar
  → 8 uzman rol paralel olarak yürütülür:
      planner, frontend, backend, bug_fixer,
      reviewer, security_auditor, devops, generalist
  → Her rol atanmış sağlayıcı + modeli kullanır
  → Her uzman tamamlandıkça ilerleme olayları akış
  → Şef tüm çıktıları nihai yanıta sentezler

Proaktif Öğrenme Akışı

Kullanıcı mesaj gönderir
  → Anahtar kelime ön filtresi (hızlı, LLM çağrısı yok)
  → Niyet benzeri anahtar kelimeler tespit edilirse:
      → LLM sınıflandırır: plan / alışkanlık / hiçbiri
      → Çıkarır: zaman, konu, tekrarlama
      → Takvim niyet köprüsü etkinlik oluşturur
      → Alışkanlıklar gelecek referans için saklanır
  → Günlük proaktif döngü:
      → Yaklaşan etkinlikler için takvimi kontrol eder
      → Zamanlanmış takipler için alışkanlıkları kontrol eder
      → LLM aracılığıyla öneriler üretir
      → Bildirim / sohbet üzerinden kullanıcıya gönderir

Bulut Senkronizasyonu Akışı

Otomatik senkronizasyon tetikleyicisi (N mesaj veya manuel)
  → cloudsync.Drive.Sync()
  → Yerel veri dosyalarını oku (önce WAL checkpoint)
  → AES-256-GCM ile şifrele (kullanıcı parolası veya makine anahtarı)
  → Google Drive'a yükle (OAuth2 token)
  → Senkronizasyon üst verisini sakla

Geri yükleme / çekme:
  → Drive'dan şifreli blokları indir
  → Parola ile şifreyi çöz
  → Yerel veri dizinine yaz (atomik geçici + yeniden adlandırma)

Eşzamanlılık Modeli

Go arka ucu açık eşzamanlılık desenleri kullanır:

  • Paylaşılan durum için sync.RWMutex (hafıza deposu, sağlayıcı yapılandırmaları, WhatsApp istemcisi)
  • Arka plan hizmetleri için Goroutine'ler (sağlık kontrolleri, proaktif döngü, ruh hali motoru, düşüş döngüsü)
  • Fonksiyon parametresi olarak iletilen context.Context — asla yapı alanlarında saklanmaz
  • database.DB.Write() kuyruğu, database is locked hatasını önlemek için tüm SQLite yazmalarını serileştirir
  • Kapatmada önce web sunucusu durur, alt sistemler bağlantısı kesilmeden önce uçuş halindeki istekleri boşaltır


context.Context'i asla yapı alanlarında saklamayın (yaşam döngüsü goroutine'leri hariç). Her zaman ihtiyaç duyan fonksiyonlara ilk parametre olarak iletin.