@vheins/local-memory-mcp 0.1.0

package/docs/SPEC-tool-schema.md

@@ -0,0 +1,201 @@
+# Spec – MCP Tool Schema & Validation
+
+## Purpose
+
+Dokumen ini mendefinisikan tool schema final + aturan validasi untuk MCP Local Memory Server.
+
+**Fokus dokumen ini:**
+- Kontrak tool yang stabil & agent-safe
+- Validasi ketat untuk mencegah memory pollution
+- Konsisten dengan skeleton server & git scope resolver
+
+> *Prinsip: tolak request buruk lebih awal. Memory jelek lebih berbahaya daripada tidak ada memory.*
+
+---
+
+## Design Principles
+
+1. **Schema-first** – logic mengikuti schema, bukan sebaliknya
+2. **Fail fast** – invalid input langsung reject
+3. **Repo-scoped by default**
+4. **Minimal surface area**
+
+---
+
+## Shared Types
+
+```typescript
+type MemoryType = "code_fact" | "decision" | "mistake" | "pattern";
+
+type MemoryScope = {
+  repo: string;
+  branch?: string;
+  folder?: string;
+  language?: string;
+};
+```
+
+---
+
+## Tool: `memory.store`
+
+**Purpose:**
+Menyimpan memory baru yang berdampak jangka panjang.
+
+**Input Schema:**
+```typescript
+{
+  type: MemoryType;
+  content: string;
+  importance: number;      // 1–5
+  scope: MemoryScope;
+}
+```
+
+**Validation Rules (WAJIB):**
+- `content.length >= 10`
+- `importance` antara 1–5
+- `scope.repo` **REQUIRED** & non-empty
+- `content` **tidak boleh**:
+    - pertanyaan
+    - speculative language ("mungkin", "kayaknya")
+
+**Semantic Guardrails:**
+- Tolak jika `content` mengandung:
+    - brainstorming
+    - diskusi sementara
+    - opini subjektif
+
+---
+
+## Tool: `memory.update`
+
+**Purpose:**
+Update memory yang sudah ada.
+
+**Input Schema:**
+```typescript
+{
+  id: string;              // uuid
+  content?: string;
+  importance?: number;
+}
+```
+
+**Validation Rules:**
+- `id` **REQUIRED**
+- Minimal 1 field selain id
+- Update tidak boleh mengubah `scope.repo`
+
+---
+
+## Tool: `memory.search`
+
+**Purpose:**
+Mencari memory relevan untuk augment prompt.
+
+**Input Schema:**
+```typescript
+{
+  query: string;
+  repo: string;
+  types?: MemoryType[];
+  minImportance?: number;
+  limit?: number;          // default 5
+}
+```
+
+**Validation Rules:**
+- `query.length >= 3`
+- `repo` **REQUIRED**
+- `limit` max 10
+
+**Behavioral Rules:**
+- Repo mismatch → **reject**
+- No global search
+
+---
+
+## Tool: `memory.summarize`
+
+**Purpose:**
+Update antigravity summary per repo.
+
+**Input Schema:**
+```typescript
+{
+  repo: string;
+  signals: string[];
+}
+```
+
+**Validation Rules:**
+- `repo` **REQUIRED**
+- `signals.length >= 1`
+- Setiap signal max 200 chars
+
+---
+
+## Zod Validation Example
+
+```typescript
+import { z } from "zod";
+
+export const MemoryStoreSchema = z.object({
+  type: z.enum(["code_fact", "decision", "mistake", "pattern"]),
+  content: z.string().min(10),
+  importance: z.number().min(1).max(5),
+  scope: z.object({
+    repo: z.string().min(1),
+    branch: z.string().optional(),
+    folder: z.string().optional(),
+    language: z.string().optional()
+  })
+});
+```
+
+---
+
+## Tool Registration (`router.ts`)
+
+```typescript
+case "tools/list":
+  return {
+    tools: [
+      { name: "memory.store", inputSchema: MemoryStoreSchema },
+      { name: "memory.search", inputSchema: MemorySearchSchema },
+      { name: "memory.update", inputSchema: MemoryUpdateSchema },
+      { name: "memory.summarize", inputSchema: MemorySummarizeSchema }
+    ]
+  };
+```
+
+---
+
+## Error Strategy (Opinionated)
+
+- Validation error → `-32602 Invalid params`
+- Scope missing → **hard error**
+- Silent fallback → **DILARANG**
+
+---
+
+## Anti-Patterns (DILARANG)
+
+- ❌ Auto-coerce input
+- ❌ Infer repo implicitly in search
+- ❌ Store memory without scope
+- ❌ Accept vague content
+
+---
+
+## Final Take
+
+Tool schema adalah kontrak moral antara agent dan memory.
+
+**Kalau schema ini dijaga ketat:**
+- Memory tetap bersih
+- Agent makin konsisten
+- Antigravity benar-benar terasa
+
+Ini fondasi sebelum masuk ke SQLite & vector DB.

package/docs/SPEC-vector-search.md

@@ -0,0 +1,198 @@
+# Spec – Vector Search Stub & Similarity Layer
+
+## Purpose
+
+Dokumen ini mendefinisikan vector search layer (stub) untuk MCP Local Memory Server.
+
+**Fokus dokumen ini:**
+- Menyediakan abstraction yang benar sebelum embedding/model dipilih
+- Mendukung typo, paraphrase, dan semantic similarity
+- Aman untuk diintegrasikan dengan SQLite schema yang sudah ada
+
+> *Prinsip: jangan nikahi embedding atau library terlalu cepat.*
+
+---
+
+## Design Goals
+
+1. **Replaceable** – embedding & index bisa diganti
+2. **Predictable** – ranking stabil
+3. **Repo-scoped** – tidak ada cross-project similarity
+4. **Fail-safe** – jika vector gagal, agent tetap jalan
+
+---
+
+## Conceptual Model
+
+```mermaid
+graph TD
+    A[query text] --> B[normalize]
+    B --> C[embed - stub dulu]
+    C --> D[vector search]
+    D --> E[rank + filter]
+    E --> F[return memory IDs]
+```
+
+*Vector layer tidak pernah return full memory.*
+
+---
+
+## Vector Responsibility Boundary
+
+**Vector Layer BOLEH:**
+- Hitung similarity
+- Return memory_id + score
+
+**Vector Layer TIDAK BOLEH:**
+- Filter by repo (harus sudah dilakukan)
+- Filter by type / importance
+- Mengubah atau menulis data
+
+---
+
+## Vector Interface (Canonical)
+
+```typescript
+export type VectorResult = {
+  id: string;
+  score: number;   // 0.0 – 1.0
+};
+
+export interface VectorStore {
+  upsert(id: string, text: string): Promise<void>;
+  remove(id: string): Promise<void>;
+  search(query: string, limit: number): Promise<VectorResult[]>;
+}
+```
+
+*Ini kontrak WAJIB dijaga.*
+
+---
+
+## Stub Implementation (No Embedding Yet)
+
+`storage/vectors.stub.ts`
+
+```typescript
+import { VectorStore, VectorResult } from "./types.js";
+
+export class StubVectorStore implements VectorStore {
+  async upsert(id: string, text: string) {
+    // no-op
+  }
+
+  async remove(id: string) {
+    // no-op
+  }
+
+  async search(query: string, limit: number): Promise<VectorResult[]> {
+    return [];
+  }
+}
+```
+
+**Dengan stub ini:**
+- MCP server jalan
+- Tool contract stabil
+- Vector bisa ditambahkan belakangan
+
+---
+
+## Normalization Layer (WAJIB)
+
+Normalization dilakukan sebelum embedding.
+
+```typescript
+export function normalize(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+```
+
+*Normalization ini sudah membantu typo ringan, bahkan tanpa vector.*
+
+---
+
+## Ranking Strategy (Server-side)
+
+Vector similarity **BUKAN** satu-satunya sinyal.
+
+**Final score =**
+```
+(similarity * 0.7)
++ (importanceBoost * 0.2)
++ (recencyBoost * 0.1)
+```
+
+**Dimana:**
+- `importanceBoost` = `importance / 5`
+- `recencyBoost` = decay berdasarkan `created_at`
+
+> *Ini bikin agent terasa stabil & dewasa.*
+
+---
+
+## `memory.search` Integration Flow
+
+```typescript
+// 1. fetch candidates by repo + importance
+// 2. vector.search(query)
+// 3. merge scores
+// 4. threshold + limit
+```
+
+*Jika vector kosong → fallback ke keyword match.*
+
+---
+
+## Fallback Strategy (WAJIB)
+
+**Jika:**
+- embedding service down
+- vector index corrupt
+
+**Maka:**
+- Gunakan `LIKE %query%` di SQLite
+- Tetap hormati repo boundary
+
+*Agent tidak boleh error karena vector.*
+
+---
+
+## Future Implementations (Drop-in)
+
+VectorStore bisa diganti dengan:
+- sqlite-vec
+- sqlite-vss
+- hnswlib-node
+- faiss (via binding)
+
+**Tanpa mengubah:**
+- tool schema
+- MCP contract
+- agent prompt
+
+---
+
+## Anti-Patterns (DILARANG)
+
+- ❌ Store vector tanpa text canonical
+- ❌ Vector sebagai source of truth
+- ❌ Global vector index lintas repo
+- ❌ Tuning threshold tanpa test
+
+---
+
+## Final Take
+
+Vector layer adalah **amplifier**, bukan otak.
+
+**Kalau stub + boundary ini dijaga:**
+- Kamu bisa eksperimen bebas
+- Agent tetap stabil
+- Produk tidak terkunci vendor
+
+Ini langkah terakhir sebelum implementasi embedding nyata.

package/docs/TEST-scenarios.md

@@ -0,0 +1,179 @@
+# Test Scenarios – MCP Local Memory
+
+## Purpose
+
+Dokumen ini berisi test scenarios konseptual & praktis untuk memverifikasi bahwa MCP Local Memory:
+- Menyimpan memory yang benar
+- Menolak memory yang buruk
+- Tidak bocor lintas repo
+- Mendukung antigravity behavior
+
+*Test ini bukan unit test code, tapi behavioral contract test untuk agent + MCP server.*
+
+---
+
+## Test Category Overview
+
+1. **Memory Quality** (Good vs Bad)
+2. **Repo / Git Scoping**
+3. **Auto-Memory Heuristics**
+4. **Vector & Fallback Behavior**
+5. **Antigravity Consistency**
+
+---
+
+## 1. Memory Quality Tests
+
+### 1.1 GOOD – Architectural Decision
+**Context:** Repo `backend-api`
+
+**User:**
+> "Kita tidak akan pakai ORM di project ini, semua query pakai raw SQL."
+
+**Expected Agent Behavior:**
+- Detect as `decision`
+- `importance = 5`
+- `scope.repo = backend-api`
+- Call `memory.store`
+
+**Expected Stored Memory:**
+```
+Type: decision
+Content: Do not use ORM; use raw SQL for all database access
+```
+
+### 1.2 BAD – Temporary Discussion
+**User:**
+> "Coba dulu pakai cara ini, nanti lihat hasilnya."
+
+**Expected Behavior:**
+- ❌ **DO NOT** store memory
+- Continue task without memory
+
+### 1.3 BAD – Opinion Only
+**User:**
+> "Menurutku style ini lebih enak dibaca."
+
+**Expected Behavior:**
+- ❌ **DO NOT** store memory
+
+---
+
+## 2. Repo / Git Scope Tests
+
+### 2.1 GOOD – Same Repo Retrieval
+**Repo:** `frontend-app`
+
+**Existing Memory:**
+`decision: Use React Query for data fetching`
+
+**User Prompt:**
+> "Buatkan hook untuk fetch user profile"
+
+**Expected Behavior:**
+- `memory.search` with `repo = frontend-app`
+- Inject React Query constraint
+
+### 2.2 BAD – Cross Repo Leakage
+**Repo A:** `backend-api`
+**Repo B:** `frontend-app`
+
+**Existing Memory (Repo A):**
+`decision: Do not use ORM`
+
+**User Prompt (Repo B):**
+> "Setup database access"
+
+**Expected Behavior:**
+- ❌ Memory from Repo A **NOT** retrieved
+
+---
+
+## 3. Auto-Memory Heuristics Tests
+
+### 3.1 GOOD – Repeated Correction
+**Agent Output:**
+Uses default export
+
+**User Correction:**
+> "Jangan pakai default export di domain layer."
+
+**Expected Behavior:**
+- Detect as `mistake`
+- Store memory after confirmation
+
+### 3.2 BAD – Single Minor Correction
+**User:**
+> "Yang ini ganti nama variabel aja."
+
+**Expected Behavior:**
+- ❌ **DO NOT** store memory
+
+---
+
+## 4. Vector & Fallback Tests
+
+### 4.1 Typo Tolerance
+**Stored Memory:**
+`decision: Do not use ORM`
+
+**User Query:**
+> "Jangan pake ormm ya"
+
+**Expected Behavior:**
+- `normalize(query)`
+- `memory.search` returns `decision`
+
+### 4.2 Vector Failure Fallback
+**Condition:**
+Vector index unavailable
+
+**Expected Behavior:**
+- Fallback to SQLite keyword search
+- Agent still works
+
+---
+
+## 5. Antigravity Consistency Tests
+
+### 5.1 Long Session Drift Prevention
+**Day 1:**
+Decision stored: `Use clean architecture`
+
+**Day 5 User Prompt:**
+> "Buat handler cepat aja tanpa layer ribet"
+
+**Expected Behavior:**
+- Agent retrieves decision
+- Push back politely
+- Follow clean architecture
+
+### 5.2 Summary Usage
+**Condition:**
+`memory_summary` exists for repo
+
+**Expected Behavior:**
+- Agent reads summary **BEFORE** `memory.search`
+- Uses summary to guide reasoning
+
+---
+
+## Failure Signals (Red Flags)
+
+- 🚨 Memory count grows rapidly
+- 🚨 Agent output inconsistent day-to-day
+- 🚨 Same correction repeated often
+- 🚨 Cross-project rules applied
+
+*Jika muncul → heuristics atau scope resolver salah.*
+
+---
+
+## Final Take
+
+Kalau semua test ini lulus:
+- Memory kamu bersih
+- Agent kamu stabil
+- Antigravity behavior nyata
+
+Test ini sebaiknya dijalankan manual di awal, lalu dijadikan automated regression tests.

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@vheins/local-memory-mcp",
+	"version": "0.1.0",
+	"description": "MCP Local Memory Service for coding copilot agents",
+	"type": "module",
+	"main": "dist/server.js",
+	"bin": {
+		"mcp-memory-local": "./dist/server.js",
+		"mcp-memory-dashboard": "./dist/dashboard/server.js"
+	},
+	"scripts": {
+		"build": "tsc && mkdir -p dist/dashboard/public && rsync -a --delete src/dashboard/public/ dist/dashboard/public/",
+		"dev": "tsc --watch",
+		"start": "node dist/server.js",
+		"dashboard": "node dist/dashboard/server.js",
+		"both": "npm run start & npm run dashboard",
+		"test": "vitest --run",
+		"test:watch": "vitest"
+	},
+	"keywords": [
+		"mcp",
+		"memory",
+		"ai",
+		"coding-copilot"
+	],
+	"author": "",
+	"license": "MIT",
+	"dependencies": {
+		"better-sqlite3": "^12.6.2",
+		"express": "^5.2.1",
+		"qs": "^6.15.0",
+		"zod": "^4.3.5"
+	},
+	"devDependencies": {
+		"@fast-check/vitest": "^0.3.0",
+		"@types/better-sqlite3": "^7.6.13",
+		"@types/express": "^5.0.6",
+		"@types/node": "^22.19.7",
+		"fast-check": "^4.6.0",
+		"typescript": "^5.7.3",
+		"vitest": "^4.1.1"
+	}
+}