zesdex/docs/CODEMAPS/data.md

Data & Persistence

State Runtime (TUI)

State TUI yang berjalan di memori adalah AppStateRest (apps/interfaces/tui/src/state.rs).

TranscriptCache

pub struct TranscriptCache {
    pub messages: VecDeque<ChatMessageDisplay>,  // O(1) eviction
    pub max_lines: usize,                        // default: 200
    pub dirty: bool,                             // perlu rebuild cache?
}

Saat dirty=true, pre_render_chat() rebuild display_lines_cache (render markdown semua pesan) sebelum frame berikutnya.

SessionRuntime

pub struct SessionRuntime {
    pub messages: Vec<ChatMessage>,   // history untuk LLM context
    pub usage: UsageStats,            // token counting akumulasi
    pub session_start: i64,           // unix ms saat sesi dimulai
    pub hive_mind_converged: bool,    // flag selesai hive mind
}

Context Window

resolve_context_window() di state.rs:

1. Ambil settings.max_tokens jika ada dan > 0
2. Fallback ke 256.000 token (default)

Token dihitung lazily via count_tokens() (tiktoken cl100k_base, fallback len/4), di-cache di AppStateRest::cached_token_count, hanya dihitung ulang saat token_count_dirty=true.

Persistence di Disk

Semua data disimpan di platform data directory:

• Linux: ~/.local/share/zesdex/
• macOS: ~/Library/Application Support/zesdex/

~/.local/share/zesdex/
├── settings.json              # User settings (provider, model, max_tokens, dll)
├── sessions/
│   └── <uuid>/
│       ├── session.json       # Metadata sesi
│       ├── messages.jsonl     # Message log (append-only)
│       └── .lock              # Lock file (cegah concurrent access)
├── memories/
│   └── *.md                   # Memory files dengan frontmatter
├── lessons/
│   └── *.md                   # Lesson files (output dari learning system)
└── worktrees/                 # Git worktree per sesi (isolasi perubahan)

settings.json

{
  "provider": "openai",
  "model": "gpt-4o",
  "max_tokens": 256000,
  "temperature": 0.7,
  "concise_output": false
}

Diload via JsonSettingsRepository::load(), disimpan kembali saat TUI keluar (state.save_settings()).

Memory Files

Format markdown dengan YAML frontmatter:

---
name: prefer-early-return
type: feedback
description: Selalu gunakan early return untuk mengurangi nesting
---

Ketika menulis fungsi, gunakan early return/guard clauses daripada deep nesting.

Types: user, feedback, project, reference

Lesson Files

Hasil dari learning system, disimpan di lessons/:

• Satu file per lesson
• Plain markdown, dibaca oleh overlay Learning
• Bisa di-accept/reject dari TUI

SQLite (Message Log)

rusqlite dengan fitur bundled (tidak perlu install SQLite terpisah):

• Per-session database di sessions/<uuid>/messages.db
• Table messages: id, session_id, role, content, timestamp, tokens
• Table sessions: id, metadata, created_at

IPC Protocol (Daemon Mode)

Daemon dan client berkomunikasi via Unix domain socket:

~/.local/share/zesdex/daemon.sock

Frame format:

[4 bytes BE: payload length][JSON payload]

Message types:

• Action — client kirim aksi ke daemon
• StateSnapshot — daemon kirim snapshot state ke client
• Ping/Pong — keepalive

Edit History

Agent mencatat setiap mutasi file ke event log internal:

• Tool write/edit/delete merekam path, bytes delta, timestamp
• Digunakan oleh subagent review untuk audit trail

TurnEvent Queue

Agent berjalan di background thread dan mengirim events ke TUI via Arc<Mutex<VecDeque<TurnEvent>>>:

Event	Payload	Efek di TUI
AssistantMessage(msg)	ChatMessage	Push ke transcript
ToolResult { output, .. }	String	Push sebagai tool message
Usage { tokens_in, tokens_out }	u64, u64	Update usage stats
Error(msg)	String	Toast error
Compacted(msgs)	Vec<ChatMessage>	Update session_runtime.messages
SystemNote { kind, message }	String	Push ke transcript
Done	—	Set turn_in_flight_flag = false