@vheins/local-memory-mcp 0.1.0

package/docs/SPEC-server.md

@@ -0,0 +1,243 @@
+# MCP Local Memory Server – Skeleton Documentation
+
+## Purpose
+
+Dokumen ini mendefinisikan skeleton MCP server lokal (Node.js) yang:
+- Kompatibel secara konsep dengan MCP Memory berbasis remote API
+- Minimal tapi lengkap: resources, tools, prompts
+- Siap dikembangkan ke SQLite + vector DB
+- Dirancang untuk coding copilot & antigravity agent
+
+Skeleton ini bukan full implementation, tapi contract + struktur agar:
+- Agent tidak perlu diubah
+- Remote MCP bisa diganti local MCP tanpa friction
+
+---
+
+## Design Principles
+
+1. **Contract-first, storage-second**
+2. **Agent-facing API harus stabil**
+3. **Memory high-signal only**
+4. **Strict project / git scoping**
+5. **Local-first, no auth by default**
+
+---
+
+## Server Capabilities
+
+```json
+{
+  "resources": { "list": true, "read": true, "templates": true },
+  "tools": { "list": true, "call": true },
+  "prompts": { "list": true, "get": true }
+}
+```
+
+---
+
+## Resources
+
+### 1. `memory://index`
+**Purpose:** Lightweight discovery index (metadata only).
+**Contract:**
+- Returns list of recent memory entries
+- **MUST NOT** include full content
+- Used for de-duplication & inspection
+
+### 2. `memory://{id}`
+**Purpose:** Read a single memory entry.
+**Returned Fields:**
+```typescript
+{
+  id: string
+  type: "code_fact" | "decision" | "mistake" | "pattern"
+  content: string
+  importance: number
+  scope: { repo: string }
+  created_at: string
+}
+```
+
+### 3. `memory://summary/{repo}`
+**Purpose:** Antigravity snapshot per project / repo.
+**Notes:**
+- High-level only
+- Used before any search
+
+### 4. `schema://mcp`
+**Purpose:** Machine-readable schema for tools, resources, prompts.
+
+---
+
+## Resource Templates
+
+```json
+[
+  { "uriTemplate": "memory://index", "description": "Recent memory index (metadata only)" },
+  { "uriTemplate": "memory://{id}", "description": "Read individual memory" },
+  { "uriTemplate": "memory://summary/{repo}", "description": "Project summary" },
+  { "uriTemplate": "schema://mcp", "description": "MCP schema" }
+]
+```
+
+---
+
+## Tools (Minimal Set)
+
+> Tool names intentionally mirip secara semantik dengan remote MCP, tapi disederhanakan untuk local usage.
+
+### 1. `memory.store`
+Create a new memory entry.
+
+**Input:**
+```typescript
+{
+  type: "code_fact" | "decision" | "mistake" | "pattern"
+  content: string
+  importance: number
+  scope: { repo: string, folder?: string, language?: string }
+}
+```
+**Rules:**
+- `repo` is **REQUIRED**
+- No speculative or temporary info
+
+### 2. `memory.update`
+Update existing memory.
+
+**Input:**
+```typescript
+{
+  id: string
+  content?: string
+  importance?: number
+}
+```
+
+### 3. `memory.search`
+Semantic + filtered search.
+
+**Input:**
+```typescript
+{
+  query: string
+  repo: string
+  types?: ("code_fact" | "decision" | "mistake" | "pattern")[]
+  minImportance?: number
+  limit?: number
+}
+```
+**Behavior:**
+- Vector similarity search
+- Repo match is **mandatory**
+
+### 4. `memory.summarize`
+Update antigravity summary.
+
+**Input:**
+```typescript
+{
+  repo: string
+  signals: string[]
+}
+```
+
+---
+
+## Prompts
+
+### 1. `memory-agent-core`
+**Purpose:** Core behavioral contract.
+
+> You are a coding copilot agent.
+>
+> You must:
+> - Respect stored decisions and constraints
+> - Avoid repeating known mistakes
+> - Use memory only when relevant
+>
+> Memory is a source of truth, not a suggestion.
+
+### 2. `memory-index-policy`
+**Purpose:** Enforce strict memory discipline.
+
+> Do not store:
+> - Temporary discussions
+> - Brainstorming
+> - Subjective opinions
+>
+> Only store durable knowledge.
+
+### 3. `tool-usage-guidelines`
+**Purpose:** Prevent tool abuse.
+
+> Only call memory.store when:
+> - The information affects future behavior
+> - The scope (repo) is clear
+> - The memory will still matter later
+
+---
+
+## Git / Project Scoping (Hard Requirement)
+
+### Rule
+Every memory entry **MUST** include:
+`scope.repo`
+
+### Resolution Order
+1. Git repository root
+2. Project folder name
+
+### Enforcement
+- Search without repo → **reject**
+- Store without repo → **reject**
+
+*This prevents cross-project contamination.*
+
+---
+
+## Suggested Internal Folder Structure
+
+```
+mcp-memory-local/
+├─ server.ts          # MCP JSON-RPC loop
+├─ capabilities.ts    # static MCP contract
+├─ tools/
+│  ├─ store.ts
+│  ├─ search.ts
+│  └─ summarize.ts
+├─ resources/
+│  ├─ index.ts
+│  └─ read.ts
+├─ prompts/
+│  └─ registry.ts
+├─ storage/
+│  ├─ sqlite.ts
+│  └─ vectors.ts
+└─ utils/
+   └─ git-scope.ts
+```
+
+---
+
+## Explicit Non-Goals (for Skeleton)
+
+- ❌ Auth & tokens
+- ❌ Organization-level scope
+- ❌ Knowledge graph
+- ❌ Audit & versioning
+- ❌ Bulk operations
+
+*These can be added later without breaking contract.*
+
+---
+
+## Final Note
+
+Skeleton ini cukup kecil untuk dibangun cepat, tapi cukup kuat untuk:
+- Menggantikan remote MCP
+- Menjadi fondasi agent yang konsisten
+- Menjaga antigravity behavior
+
+Kalau kontrak ini dijaga, backend bisa berubah tanpa menyentuh agent.

package/docs/SPEC-skeleton.md

@@ -0,0 +1,255 @@
+# Skeleton – MCP Local Memory Server Loop (Node.js)
+
+## Purpose
+
+Dokumen ini mendefinisikan server loop MCP JSON-RPC minimal untuk MCP Local Memory Server.
+
+**Tujuan skeleton ini:**
+- Menjadi *drop-in replacement* untuk MCP memory remote
+- Fokus ke contract & flow, bukan storage
+- Mudah dikembangkan ke SQLite + vector DB
+
+> *Catatan: Skeleton ini sengaja boring & eksplisit. MCP server yang bagus itu stabil, bukan pintar.*
+
+---
+
+## High-Level Flow
+
+```mermaid
+graph TD
+    A[stdin JSON-RPC] --> B[Parse message]
+    B --> C[Handle initialize]
+    C --> D[Advertise capabilities]
+    B --> E[Route method -> handler]
+    E --> F[Return JSON-RPC response]
+```
+
+---
+
+## Required Files
+
+```
+mcp-memory-local/
+├─ server.ts            # entrypoint (JSON-RPC loop)
+├─ capabilities.ts      # static MCP contract
+├─ router.ts            # method dispatcher
+├─ tools/
+│  ├─ memory.store.ts
+│  ├─ memory.search.ts
+│  └─ memory.summarize.ts
+├─ resources/
+│  ├─ list.ts
+│  └─ read.ts
+└─ prompts/
+   └─ registry.ts
+```
+
+---
+
+## `server.ts` (JSON-RPC Loop)
+
+```typescript
+import readline from "node:readline";
+import { handleMethod } from "./router.js";
+import { CAPABILITIES } from "./capabilities.js";
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false
+});
+
+function reply(payload: unknown) {
+  process.stdout.write(JSON.stringify(payload) + "\n");
+}
+
+rl.on("line", async (line) => {
+  if (!line.trim()) return;
+
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+
+  const { id, method, params } = msg;
+
+  // --- initialize ---
+  if (method === "initialize") {
+    reply({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion: "2024-11-05",
+        serverInfo: CAPABILITIES.serverInfo,
+        capabilities: CAPABILITIES.capabilities
+      }
+    });
+
+    reply({
+      jsonrpc: "2.0",
+      method: "notifications/initialized",
+      params: {}
+    });
+    return;
+  }
+
+  // --- ignore notification ---
+  if (method === "notifications/initialized") return;
+
+  // --- route method ---
+  try {
+    const result = await handleMethod(method, params);
+
+    reply({
+      jsonrpc: "2.0",
+      id,
+      result
+    });
+  } catch (err: any) {
+    reply({
+      jsonrpc: "2.0",
+      id,
+      error: {
+        code: -32603,
+        message: err.message || "Internal error"
+      }
+    });
+  }
+});
+```
+
+---
+
+## `capabilities.ts`
+
+```typescript
+export const CAPABILITIES = {
+  serverInfo: {
+    name: "mcp-memory-local",
+    version: "0.1.0"
+  },
+  capabilities: {
+    resources: {
+      list: true,
+      read: true,
+      templates: true
+    },
+    tools: {
+      list: true,
+      call: true
+    },
+    prompts: {
+      list: true,
+      get: true
+    }
+  }
+};
+```
+
+---
+
+## `router.ts` (Method Dispatcher)
+
+```typescript
+import { listResources, readResource } from "./resources/index.js";
+import { PROMPTS } from "./prompts/registry.js";
+
+export async function handleMethod(method: string, params: any) {
+  switch (method) {
+    // ---- tools ----
+    case "tools/list":
+      return { tools: [] };
+
+    case "tools/call":
+      return { result: "not implemented" };
+
+    // ---- resources ----
+    case "resources/list":
+      return listResources();
+
+    case "resources/read":
+      return readResource(params?.uri);
+
+    // ---- prompts ----
+    case "prompts/list":
+      return { prompts: Object.values(PROMPTS) };
+
+    case "prompts/get":
+      return { prompt: PROMPTS[params.name] };
+
+    default:
+      throw new Error(`Unsupported method: ${method}`);
+  }
+}
+```
+
+---
+
+## `prompts/registry.ts`
+
+```typescript
+export const PROMPTS = {
+  "memory-agent-core": {
+    name: "memory-agent-core",
+    description: "Core behavioral contract for memory-aware agents",
+    content: `You are a coding copilot agent.
+
+Respect stored decisions.
+Avoid repeating mistakes.
+Memory is a source of truth.`
+  }
+};
+```
+
+---
+
+## `resources/index.ts`
+
+```typescript
+export function listResources() {
+  return {
+    resources: [
+      { uri: "memory://index", title: "Memory Index" }
+    ]
+  };
+}
+
+export function readResource(uri: string) {
+  return {
+    resource: {
+      uri,
+      title: "Not implemented",
+      content: ""
+    }
+  };
+}
+```
+
+---
+
+## Why This Skeleton Works
+
+- Matches MCP lifecycle exactly
+- Easy to extend per tool
+- No storage coupling
+- Agent-safe (no breaking contract)
+
+*Ini adalah fondasi yang tepat sebelum:*
+1. SQLite
+2. Vector search
+3. Auto-memory logic
+
+---
+
+## Next Recommended Step
+
+1. Tambah tool definitions (`memory.store`, `memory.search`)
+2. Tambah git-scope resolver
+3. Baru wiring ke SQLite
+
+*Kalau kamu mau, langkah berikutnya aku bisa:*
+- Tambahkan tool schema lengkap
+- Tambahkan git scope resolver code
+- Tambahkan SQLite + vector stub

package/docs/SPEC-sqlite-schema.md

@@ -0,0 +1,183 @@
+# Spec – SQLite Schema & Migration
+
+## Purpose
+
+Dokumen ini mendefinisikan skema SQLite final untuk MCP Local Memory Server.
+
+**Fokus utama:**
+- Skema tahan lama & mudah di-migrate
+- Selaras dengan tool schema, git scope, dan heuristics
+- Siap dipakai dengan atau tanpa vector DB
+
+> *Prinsip: SQLite adalah source of truth. Vector hanyalah index.*
+
+---
+
+## Design Principles
+
+1. **Append-friendly** (mudah evolve)
+2. **Readable** (debug via sqlite CLI masih masuk akal)
+3. **Strict schema** (hindari JSON berlebihan)
+4. **Repo-scoped by design**
+
+---
+
+## Database File
+
+`storage/memory.db`
+
+Single file, local-only.
+
+---
+
+## Table: `memories`
+
+**Purpose:**
+Menyimpan semua long-term memory berkualitas tinggi.
+
+**Schema:**
+```sql
+CREATE TABLE memories (
+  id TEXT PRIMARY KEY,
+  repo TEXT NOT NULL,
+  type TEXT NOT NULL CHECK (type IN (
+    'code_fact',
+    'decision',
+    'mistake',
+    'pattern'
+  )),
+  content TEXT NOT NULL,
+  importance INTEGER NOT NULL CHECK (importance BETWEEN 1 AND 5),
+  folder TEXT,
+  language TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+```
+
+**Notes:**
+- `repo` adalah **hard boundary**
+- `content` adalah canonical text (untuk embedding)
+- Jangan simpan JSON besar di sini
+
+---
+
+## Indexes (WAJIB)
+
+```sql
+CREATE INDEX idx_memories_repo ON memories(repo);
+CREATE INDEX idx_memories_type ON memories(type);
+CREATE INDEX idx_memories_importance ON memories(importance);
+```
+
+*Index ini cukup untuk tahap awal.*
+
+---
+
+## Table: `memory_summary`
+
+**Purpose:**
+Antigravity snapshot per repo.
+
+**Schema:**
+```sql
+CREATE TABLE memory_summary (
+  repo TEXT PRIMARY KEY,
+  summary TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+```
+
+---
+
+## Optional Table: `memory_embeddings`
+
+> *Opsional – hanya jika embedding tidak disimpan inline.*
+
+```sql
+CREATE TABLE memory_embeddings (
+  memory_id TEXT PRIMARY KEY,
+  embedding BLOB NOT NULL,
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+```
+
+*Jika pakai sqlite-vector extension, table ini bisa diganti.*
+
+---
+
+## Migration Strategy
+
+### v1 – Initial
+
+```sql
+-- 001_init.sql
+BEGIN;
+
+-- memories table
+CREATE TABLE memories (...);
+CREATE INDEX ...;
+
+-- summary table
+CREATE TABLE memory_summary (...);
+
+COMMIT;
+```
+
+### Rules
+- Tidak ada destructive migration di awal
+- Tambah kolom → nullable
+- Jangan rename kolom (add new instead)
+
+---
+
+## Insert Example
+
+```sql
+INSERT INTO memories (
+  id, repo, type, content, importance, created_at, updated_at
+) VALUES (
+  'uuid',
+  'my-repo',
+  'decision',
+  'Do not use ORM; raw SQL only',
+  5,
+  datetime('now'),
+  datetime('now')
+);
+```
+
+---
+
+## Query Patterns
+
+### By Repo (most common)
+
+```sql
+SELECT * FROM memories
+WHERE repo = ?
+ORDER BY importance DESC, created_at DESC
+LIMIT 5;
+```
+
+---
+
+## What NOT to Store
+
+- ❌ Chat logs
+- ❌ Prompt history
+- ❌ Temporary task state
+- ❌ Vector-only data without text
+
+---
+
+## Final Take
+
+Skema ini sengaja tidak kompleks.
+
+**Kalau kamu disiplin di schema & heuristics:**
+- SQLite akan cukup lama
+- Vector DB bisa ditambah belakangan
+- Memory tetap bersih & bernilai tinggi
+
+Ini fondasi terakhir sebelum masuk ke vector search.