roedyrustam/vibes-plug/session-memory-manager

Session Memory Manager

English | Bahasa Indonesia

<a name="english"></a>

English

Orchestration & Integration

• Upstream Orchestrators: Works under brainstorming and zero-to-prod-orchestrator (Phases 1-8 Master Lifecycle) as the persistent session memory and context controller.
• Downstream Cooperating Skills:
• prd-architect — Read and maintain PRD, ERD, and continuous blueprint files.
• living-codebase-ast-graph — Synchronize AST symbol graphs with CONTEXT_MAP.md.
• agentic-memory-architect — Integrate episodic memory persistence with long-term agent stores.
• multi-agent-orchestration — Pass concise subagent context slices during Swarm Fan-Out.
• anti-slop — Enforce ultra-compact YAML checkpoints (<300 tokens) and zero conversational fluff.

Description

This skill acts as the agent's memory controller. It handles loading project context at session startup, dynamically updating the context map and learning graph during the session, and seamlessly generating ultra-compact handoff checkpoints at session end.

1. Session Start (Ingestion)

Activate this phase IMMEDIATELY on a new session, or when the user says "start session" or "load context". Do not answer primary requests until complete.

Workflow:

1. Discover Files: Search the root or .docs/ using list_dir, grep_search, or view_file for: CONTEXT_MAP.md, LEARNING_GRAPH.md, PRD.md, BLUEPRINT.md (or ARCHITECTURE.md), and CHECKPOINT.md. Also read tech stack identifiers (TECH_STACK.md, package.json, go.mod, etc.).
2. Internalize: Read the contents. Grasp the architectural constraints, user stylistic preferences, hard-learned lessons, and the current goal/milestone.
3. Acknowledge: Briefly confirm to the user what context was loaded, stating the Tech Stack and immediate goal. Proceed to address the actual request.

2. Active Session (Run)

Maintain project memory actively to prevent context exhaustion and hallucination.

Maintain Context Map (`CONTEXT_MAP.md`)

• A highly compressed index (bullet points) of architecture, dependency graphs, and state locations.
• Rules: Do not store full code; use only file paths and 1-sentence responsibilities. Use BM25/grep_search before modifying. Append new major components/routes immediately upon creation.

Maintain Learning Graph (`LEARNING_GRAPH.md`)

• Triggers: When the user corrects code style, states a strong preference, or after resolving a complex bug.
• Rules: Physically write lessons to the memory file under categories: User Stylistic Preferences, Hard-Learned Lessons, Architectural Decisions. Do not just promise to remember.
• Global Memory: For issues spanning multiple projects, document the root cause/solution into a global context directory (e.g., <appDataDir>/knowledge). Inject this historical context proactively in future tasks.

3. Session End (Handoff)

Triggers: Session is very long (>30 messages or >70% context used), major milestone reached, or user says "save checkpoint" / "handoff".

Action: Generate an ultra-compact YAML checkpoint block (<200 tokens).

Checkpoint Format:

# CHECKPOINT — [Project Name] — [Date]
project: "[Name]"
goal: "[One-line goal]"
status: "[e.g., 60% — backend API done]"
stack: "[Tech Stack]"
last_completed:
  - "[Most recent task]"
next_tasks:
  - "[Immediate next task]"
blockers: "[Blockers or 'none']"
key_files:
  - "[path/to/critical.ts]"
env_needed: "[List of vars]"
notes: "[Critical context]"

Cross-Model Handoff Prompt: Use this universal template when moving across models (Gemini, Claude, GPT):

## RESUME CONTEXT — [Project Name]
**Goal**: [One-sentence goal]
**Current Status**: [Status]
**Tech Stack**: [Stack]
**Completed**: [Done items]
**Next Tasks**: 1. [Task 1] 2. [Task 2]
**Critical Files to Read First**: [File paths & reasons]
**Known Constraints**: [Constraints]
**Do NOT**: [Anti-patterns to avoid]
Start by reading the critical files, then confirm understanding before proceeding.

Checkpoint Storage Hierarchy:

1. CHECKPOINT.md in project root (Primary).
2. .agents/CHECKPOINT.md (Alternative).
3. Clipboard or Supabase notes table (Cross-device).

4. Production Session Memory Blueprints (TypeScript)

1. Ultra-Compact Checkpoint Serializer & Token Budget Enforcer (<200 Tokens)

export interface SessionCheckpointState {
  readonly project: string;
  readonly goal: string;
  readonly status: string;
  readonly stack: readonly string[];
  readonly lastCompleted: readonly string[];
  readonly nextTasks: readonly string[];
  readonly keyFiles: readonly string[];
}
export function serializeCompactCheckpoint(
  state: SessionCheckpointState,
  maxTokenBudget: number = 200
): { yaml: string; estimatedTokens: number; withinBudget: boolean } {
  const lines = [
    `project: "${state.project}"`,
    `goal: "${state.goal.slice(0, 120)}"`,
    `status: "${state.status}"`,
    `stack: [${state.stack.slice(0, 6).map((s) => `"${s}"`).join(', ')}]`,
    `last_completed:`,
    ...state.lastCompleted.slice(0, 3).map((item) => `  - "${item.slice(0, 90)}"`),
    `next_tasks:`,
    ...state.nextTasks.slice(0, 3).map((item) => `  - "${item.slice(0, 90)}"`),
    `key_files:`,
    ...state.keyFiles.slice(0, 5).map((file) => `  - "${file}"`)
  ];
  const yaml = lines.join('\n');
  const estimatedTokens = Math.ceil(Buffer.byteLength(yaml, 'utf8') / 3.8);
  return {
    yaml,
    estimatedTokens,
    withinBudget: estimatedTokens <= maxTokenBudget
  };
}

2. Surgical Subagent Fan-Out Context Slice Pruner

export interface ContextMapEntry {
  readonly filePath: string;
  readonly domain: 'frontend' | 'backend' | 'database' | 'security' | 'ai';
  readonly responsibility: string;
  readonly exportedSymbols: readonly string[];
}
export function buildSubagentContextSlice(
  entries: readonly ContextMapEntry[],
  targetDomain: ContextMapEntry['domain'],
  subtaskGoal: string
): string {
  const filtered = entries.filter((e) => e.domain === targetDomain).slice(0, 8);
  const rows = filtered.map(
    (e) => `- \`${e.filePath}\` [${e.exportedSymbols.join(', ')}]: ${e.responsibility}`
  );
  return [
    `### Subagent Slice (${targetDomain.toUpperCase()})`,
    `**Goal**: ${subtaskGoal}`,
    `**Relevant Files**:`,
    ...rows
  ].join('\n');
}

Sovereign Execution, Token Efficiency & Invariants

<a name="bahasa-indonesia"></a>

Bahasa Indonesia

Integrasi Orkestrasi

• Orkestrator Hulu: Beroperasi di bawah arahan brainstorming dan zero-to-prod-orchestrator (Master Lifecycle Fase 1-8) sebagai pengontrol memori sesi persisten dan konteks proyek.
• Skill Hilir & Kerja Sama:
• prd-architect — Membaca dan memelihara PRD, ERD, dan file cetak biru berkelanjutan.
• living-codebase-ast-graph — Sinkronisasi graf simbol AST dengan CONTEXT_MAP.md.
• agentic-memory-architect — Mengintegrasikan persistensi memori episodik dengan memory store jangka panjang.
• multi-agent-orchestration — Mengirimkan irisan konteks subagen yang ringkas saat Swarm Fan-Out.
• anti-slop — Menegakkan checkpoint YAML ultra-ringkas (<300 token) tanpa pemborosan kata.

Deskripsi

Skill ini mengatur memori agen: memuat konteks di awal sesi, memperbarui peta proyek dan grafik pembelajaran selama sesi berjalan, dan membuat checkpoint ringkas untuk perpindahan sesi (handoff).

1. Awal Sesi (Ingestion)

Aktifkan SEGERA pada sesi baru, atau saat diminta "mulai sesi" / "muat konteks".

Alur Kerja:

1. Temukan File: Cari di root atau .docs/: CONTEXT_MAP.md, LEARNING_GRAPH.md, PRD.md, BLUEPRINT.md, CHECKPOINT.md, dan file identifikasi tech stack (package.json, dsb).
2. Pahami: Baca isinya. Pahami batasan arsitektur, preferensi pengguna, pelajaran penting, dan tujuan/milestone saat ini.
3. Konfirmasi: Beritahu pengguna secara singkat bahwa konteks dimuat, sebutkan Tech Stack dan tujuan langsung, lalu proses permintaan utama.

2. Sesi Berjalan (Run)

Pertahankan memori proyek agar tidak terjadi halusinasi dan hemat token.

Pelihara Peta Konteks (`CONTEXT_MAP.md`)

• Indeks super padat berisi arsitektur, lokasi file penting, dan graf dependensi.
• Aturan: Jangan simpan kode lengkap, hanya path dan tanggung jawab singkat. Gunakan BM25/grep_search sebelum mengedit. Tambahkan entri baru saat membuat komponen/rute besar.

Pelihara Grafik Pembelajaran (`LEARNING_GRAPH.md`)

• Pemicu: Pengguna mengoreksi gaya koding, menyatakan preferensi, atau setelah mengatasi bug rumit.
• Aturan: Catat langsung ke file dalam kategori: Preferensi Gaya, Pelajaran Berharga, Keputusan Arsitektur.
• Memori Global: Ekstrak solusi masalah lintas-proyek ke direktori pengetahuan global (<appDataDir>/knowledge). Gunakan pengetahuan masa lalu secara proaktif dengan menyebutkannya.

3. Akhir Sesi (Handoff)

Pemicu: Pesan > 30, jendela konteks > 70% terpakai, milestone tercapai, atau pengguna berkata "simpan checkpoint".

Tindakan: Hasilkan blok YAML super ringkas (<200 token) berisi: project, goal, status, stack, last_completed, next_tasks, blockers, key_files, env_needed, dan notes.

Prompt Handoff Lintas-Model: Gunakan template universal saat berpindah model: Berikan konteks proyek (Tujuan, Status, Stack, Tugas Selesai, Tugas Berikutnya), daftar file kritis untuk dibaca pertama kali, batasan, dan apa yang JANGAN dilakukan. Minta konfirmasi sebelum lanjut.

Hierarki Penyimpanan Checkpoint:

1. CHECKPOINT.md di root proyek (Utama).
2. .agents/CHECKPOINT.md (Alternatif).
3. Clipboard / Catatan Supabase (Lintas perangkat).

Matriks Eksekusi Berdaulat, Efisiensi Token & Invarian