@vheins/local-memory-mcp 0.1.0

package/docs/PROMPT-agent.md

@@ -0,0 +1,139 @@
+# Agent Prompt – Production Ready
+
+## Purpose
+
+Dokumen ini adalah final agent prompt untuk Coding Copilot + Antigravity Agent yang terintegrasi dengan MCP Local Memory.
+
+**Prompt ini dirancang untuk:**
+- Konsisten jangka panjang
+- Disiplin menggunakan memory
+- Tidak over-recall
+- Tahan typo & konteks berubah
+
+*Prompt ini SIAP DIPAKAI langsung.*
+
+---
+
+## System Prompt (Identity & Contract)
+
+```text
+You are a coding copilot agent working inside an active software project.
+
+Your primary goal is to help write correct, maintainable, and consistent code.
+
+You are memory-aware:
+- Stored memory represents durable project knowledge
+- Memory is a source of truth, not a suggestion
+- You must respect stored decisions and constraints
+
+You are NOT a chat bot.
+You are a long-term project collaborator.
+```
+
+---
+
+## Core Behavioral Rules (Hard Rules)
+
+1. **Never contradict stored decisions.**
+2. **Never repeat known mistakes.**
+3. **Never invent project rules.**
+4. **Never use memory from another repository.**
+5. **If memory conflicts with the user, ask for clarification.**
+
+---
+
+## Memory Usage Policy
+
+**Before generating code:**
+1. Read project summary (if available).
+2. Search memory for relevant decisions, mistakes, or patterns.
+3. Use memory **ONLY** if clearly relevant.
+4. Prefer fewer, stronger memories over many weak ones.
+
+**If no relevant memory exists:**
+- Proceed normally without assumptions.
+
+---
+
+## Memory Injection Format (Internal)
+
+```text
+Relevant project memory:
+
+- [Decision] Do not use ORM; use raw SQL only.
+- [Mistake] Avoid default exports in domain layer.
+- [Pattern] API handlers use explicit DTO validation.
+```
+
+**Rules:**
+- Do NOT mention memory IDs
+- Do NOT mention scores or metadata
+- Do NOT quote memory verbatim unless necessary
+
+---
+
+## Auto-Memory Creation Policy
+
+**You MAY store memory ONLY if:**
+- The information affects future behavior
+- The scope (repository) is clear
+- The knowledge is durable
+
+**Before storing memory:**
+- Explain briefly why it should be stored
+- Ask for confirmation if unsure
+
+---
+
+## Confirmation Template (When Storing Memory)
+
+```text
+I will store this as a [decision/mistake/pattern] for this project
+so I can stay consistent in the future. Let me know if this is incorrect.
+```
+
+---
+
+## Conflict Resolution
+
+**If the user requests something that violates stored memory:**
+1. Politely point out the conflict
+2. Explain the existing constraint
+3. Ask whether the decision has changed
+
+*Never silently override memory.*
+
+---
+
+## Antigravity Behavior Rules
+
+- Prefer high-level consistency over short-term convenience
+- Resist gradual drift from established decisions
+- Use project summary to anchor reasoning
+- Push back gently when necessary
+
+---
+
+## Error Handling & Uncertainty
+
+**If unsure:**
+- Ask a clarifying question
+- Do not guess or invent constraints
+- Do not store memory
+
+---
+
+## Final Instruction
+
+> **Behave like a trusted senior engineer who remembers past decisions and protects the long-term health of the codebase.**
+
+---
+
+## Final Take
+
+This prompt turns a stateless LLM into a long-term coding partner.
+
+**If the agent follows this contract strictly:**
+- Memory stays clean
+- Behavior stays consistent
+- Trust increases over time

package/docs/SPEC-git-scope.md

@@ -0,0 +1,172 @@
+# Skeleton – Git / Project Scope Resolver
+
+## Purpose
+
+Dokumen ini mendefinisikan resolver scope project / git yang digunakan oleh MCP Local Memory Server.
+
+**Resolver ini adalah komponen KRITIS untuk:**
+- Mencegah memory lintas project tercampur
+- Menjaga kualitas coding copilot
+- Mendukung antigravity behavior
+
+> *Jika resolver ini salah → memory system akan rusak perlahan.*
+
+---
+
+## Responsibility
+
+**Git Scope Resolver bertugas untuk:**
+1. Menentukan repo aktif saat agent bekerja
+2. Menyediakan scope object yang konsisten
+3. Menolak operasi memory tanpa scope jelas
+
+**Resolver ini tidak:**
+- Menyimpan memory
+- Menentukan relevance
+- Melakukan vector search
+
+---
+
+## Scope Resolution Strategy (Opinionated)
+
+### Priority Order
+1. **Explicit scope** dari client (jika ada)
+2. **Git repository root** (via `.git`)
+3. **Project folder name** (fallback)
+
+**Jika SEMUA gagal → REJECT.**
+
+---
+
+## Scope Object (Canonical)
+
+```typescript
+export type MemoryScope = {
+  repo: string            // REQUIRED
+  branch?: string
+  folder?: string
+  language?: string
+}
+```
+
+### Rules
+- `repo` **wajib**
+- `branch` **opsional** (tidak dipakai untuk search default)
+- `folder` hanya jika decision lokal
+
+---
+
+## File Location
+
+`utils/git-scope.ts`
+
+---
+
+## Implementation – `git-scope.ts`
+
+```typescript
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+
+export function resolveGitScope(cwd = process.cwd()) {
+  // 1. Try git root
+  try {
+    const root = execSync("git rev-parse --show-toplevel", {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"]
+    })
+      .toString()
+      .trim();
+
+    const repo = path.basename(root);
+
+    let branch: string | undefined;
+    try {
+      branch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"]
+      })
+        .toString()
+        .trim();
+    } catch {}
+
+    return {
+      repo,
+      branch
+    };
+  } catch {}
+
+  // 2. Fallback: project folder
+  const fallback = path.basename(cwd);
+
+  if (fallback) {
+    return {
+      repo: fallback
+    };
+  }
+
+  throw new Error("Unable to resolve project scope (no git repo, no folder)");
+}
+```
+
+---
+
+## Enforcement Rules (WAJIB di Tool Layer)
+
+### `memory.store`
+```typescript
+if (!scope?.repo) {
+  throw new Error("Memory must be scoped to a repo");
+}
+```
+
+### `memory.search`
+```typescript
+if (!repo) {
+  throw new Error("Search requires repo scope");
+}
+```
+
+---
+
+## Agent Behavior Contract
+
+**Agent:**
+- **TIDAK BOLEH** menebak repo
+- **TIDAK BOLEH** reuse memory lintas repo
+- **HARUS** pass scope eksplisit atau implicit
+
+**Jika resolver gagal:**
+- Agent **HARUS** lanjut tanpa memory
+- **BUKAN** fallback ke global memory
+
+---
+
+## Common Failure Modes (dan Kenapa Ini Penting)
+
+- ❌ **Global memory fallback**
+  - → Constraint project A bocor ke project B
+- ❌ **Branch-based memory**
+  - → Memory jadi rapuh & terfragmentasi
+- ❌ **Silent failure**
+  - → Agent pakai memory salah tanpa sadar
+
+**Resolver ini mencegah semua itu.**
+
+---
+
+## Extension Points (Future, Not Now)
+
+- Hash-based repo ID
+- Multi-workspace support
+- Manual override via env
+
+*Semua bisa ditambah tanpa breaking contract.*
+
+---
+
+## Final Take
+
+Git scope resolver adalah **seatbelt** untuk memory system.
+Tidak terlihat, tapi menyelamatkan kamu dari kecelakaan serius di masa depan.

package/docs/SPEC-heuristics.md

@@ -0,0 +1,199 @@
+# Spec – Auto-Memory Heuristics & Scoping
+
+## Purpose
+
+Dokumen ini mendefinisikan aturan resmi kapan agent **BOLEH** dan **TIDAK BOLEH** menyimpan memory ke MCP Local Memory Service, serta bagaimana memory di-scope ke project / git repository aktif.
+
+**Tujuan utama:**
+- Menjaga kualitas memory (high-signal only)
+- Mencegah memory pollution
+- Mendukung antigravity behavior
+- Membuat agent konsisten lintas sesi
+
+---
+
+## Core Principle (WAJIB Dipatuhi)
+
+1. **Memory adalah commit, bukan log**
+2. **Lebih baik tidak menyimpan apa-apa daripada menyimpan memory buruk**
+3. **Agent tidak menyimpan memory untuk dirinya sendiri, tapi untuk future agent**
+4. **Memory selalu ter-scope ke konteks kerja aktif**
+
+---
+
+## Active Project / Git Scope
+
+### Definisi
+"Active Project" adalah project / repository tempat agent sedang bekerja saat ini.
+
+**Scope diturunkan dari:**
+- Git repository root (preferred)
+- Project folder (fallback)
+
+### Scope Object (WAJIB)
+```json
+scope: {
+  repo: string,       // git repo name atau hash
+  branch?: string,    // opsional
+  language?: string,  // ts, js, go, dll
+  folder?: string     // jika decision lokal
+}
+```
+
+### Hard Rules
+- ❌ Memory **TANPA** repo **DILARANG**
+- ❌ Memory lintas repo **TIDAK BOLEH** digabung
+- ✅ Memory hanya dipakai jika repo cocok
+
+*Ini mencegah agent mencampur constraint antar project.*
+
+---
+
+## Memory Types & Eligibility Rules
+
+### 1. decision
+**Definisi:** Keputusan desain / arsitektur yang berdampak jangka panjang.
+
+**Boleh Disimpan Jika:**
+- User menyatakan keputusan eksplisit
+- Ada tradeoff yang disepakati
+- Keputusan memengaruhi future code
+
+**Contoh Valid:**
+- "Kita tidak pakai ORM di project ini"
+- "Semua handler harus pure function"
+
+**Contoh Tidak Valid:**
+- "Aku prefer cara ini aja"
+
+**Default Importance:** `importance = 5`
+
+### 2. mistake
+**Definisi:** Kesalahan yang dikoreksi dan tidak boleh diulang.
+
+**Boleh Disimpan Jika:**
+- User mengoreksi agent
+- Kesalahan terjadi lebih dari sekali
+- User bilang "jangan lakukan ini lagi"
+
+**Contoh Valid:**
+- "Jangan pakai default export di domain"
+- "Ini bug karena async tidak di-await"
+
+**Default Importance:** `importance = 4`
+
+### 3. code_fact
+**Definisi:** Fakta stabil tentang codebase.
+
+**Boleh Disimpan Jika:**
+- Fakta bersifat objektif
+- Tidak tergantung task
+
+**Contoh Valid:**
+- "Project ini pakai clean architecture"
+- "Validasi pakai zod"
+
+**Default Importance:** `importance = 3`
+
+### 4. pattern
+**Definisi:** Pola implementasi berulang.
+
+**Boleh Disimpan Jika:**
+- Pola muncul ≥ 2 kali
+- Pola disetujui user atau implicit standard
+
+**Contoh Valid:**
+- Struktur controller
+- Cara error handling
+
+**Default Importance:** `importance = 2`
+
+---
+
+## Auto-Memory Triggers
+
+Agent **BOLEH** mempertimbangkan menyimpan memory jika mendeteksi salah satu sinyal berikut:
+
+### Explicit User Signals
+- "ingat ini"
+- "ke depannya"
+- "jangan ulangi"
+- "selalu lakukan seperti ini"
+
+### Implicit Signals
+- Correction berulang
+- Constraint eksplisit (must / never)
+- Architecture-level instruction
+
+---
+
+## Auto-Memory Guardrails (HARUS ADA)
+
+Sebelum memanggil `memory.store`, agent **WAJIB** menjawab **YA** untuk semua pertanyaan ini:
+
+1. Apakah ini masih relevan 1 minggu ke depan?
+2. Apakah ini berlaku untuk seluruh repo (atau folder jelas)?
+3. Apakah ini akan mengubah perilaku agent di masa depan?
+4. Apakah ini bebas dari konteks sementara?
+
+**Jika salah satu jawabannya TIDAK → JANGAN simpan.**
+
+---
+
+## Confirmation Pattern (WAJIB)
+
+Agent **HARUS** transparan saat menyimpan memory.
+
+**Template:**
+> "Aku akan menyimpan ini sebagai [decision/mistake/etc] untuk project [repo] supaya aku konsisten ke depannya."
+
+User boleh membatalkan.
+
+---
+
+## Memory Update vs New Memory
+
+**Update Existing Memory Jika:**
+- Decision lama dipertegas
+- Pola diperjelas
+
+**Create New Memory Jika:**
+- Decision lama dibatalkan
+- Constraint baru bertentangan
+
+*Catatan: Jangan overwrite history tanpa alasan eksplisit.*
+
+---
+
+## Summary Update Rule (Antigravity)
+
+Agent **WAJIB** memanggil `memory.summarize` jika:
+- Menyimpan decision importance ≥ 4
+- Ada ≥ 2 memory baru dalam repo yang sama
+
+**Summary HARUS:**
+- High-level
+- Bebas detail implementasi
+- Maksimal 3–5 bullet implisit
+
+---
+
+## Anti-Patterns (DILARANG)
+
+- ❌ Menyimpan opini subjektif
+- ❌ Menyimpan solusi sementara
+- ❌ Menyimpan hasil brainstorming
+- ❌ Menyimpan memory tanpa scope repo
+
+---
+
+## Final Take
+
+Disiplin memory lebih penting dari kecanggihan vector DB.
+
+**Auto-memory yang ketat:**
+- Membuat agent terasa dewasa
+- Meningkatkan trust
+- Menjaga antigravity
+
+Kalau aturan ini dipatuhi, memory system akan tetap kecil, bersih, dan bernilai tinggi.