@vheins/local-memory-mcp 0.1.0

package/src/utils/logger.test.ts

@@ -0,0 +1,125 @@
+// Feature: memory-mcp-optimization
+// Property 20: StructuredLogger output adalah JSON valid dengan field wajib
+// Validates: Requirements 21.1, 21.2
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as fc from "fast-check";
+
+// ─── Property 20: StructuredLogger output adalah JSON valid dengan field wajib ─
+// Feature: memory-mcp-optimization, Property 20: StructuredLogger output JSON valid
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+
+describe("Property 20: StructuredLogger output adalah JSON valid dengan field wajib", () => {
+  let stderrOutput: string[] = [];
+  let stderrSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    stderrOutput = [];
+    stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+      stderrOutput.push(typeof chunk === "string" ? chunk : chunk.toString());
+      return true;
+    });
+    // Reset LOG_LEVEL to ensure all levels are logged
+    process.env.LOG_LEVEL = "debug";
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+    delete process.env.LOG_LEVEL;
+  });
+
+  it("each log call produces valid JSON output with required fields", async () => {
+    // Re-import logger after setting LOG_LEVEL
+    const { logger } = await import("./logger.js?t=" + Date.now());
+
+    fc.assert(
+      fc.property(
+        fc.oneof(
+          fc.constant<LogLevel>("debug"),
+          fc.constant<LogLevel>("info"),
+          fc.constant<LogLevel>("warn"),
+          fc.constant<LogLevel>("error")
+        ),
+        fc.string({ minLength: 1, maxLength: 100 }),
+        (level: LogLevel, message: string) => {
+          stderrOutput = [];
+          logger[level](message);
+
+          expect(stderrOutput.length).toBeGreaterThanOrEqual(1);
+          const lastOutput = stderrOutput[stderrOutput.length - 1];
+
+          // Must be parseable JSON
+          let parsed: Record<string, unknown>;
+          expect(() => {
+            parsed = JSON.parse(lastOutput.trim());
+          }).not.toThrow();
+
+          parsed = JSON.parse(lastOutput.trim());
+
+          // Must have required fields
+          expect(parsed).toHaveProperty("level");
+          expect(parsed).toHaveProperty("timestamp");
+          expect(parsed).toHaveProperty("message");
+
+          // level must match
+          expect(parsed.level).toBe(level);
+
+          // message must match
+          expect(parsed.message).toBe(message);
+
+          // timestamp must be ISO 8601
+          expect(typeof parsed.timestamp).toBe("string");
+          const ts = new Date(parsed.timestamp as string);
+          expect(isNaN(ts.getTime())).toBe(false);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it("log output with context includes context field", async () => {
+    const { logger } = await import("./logger.js?t=" + Date.now() + "ctx");
+
+    stderrOutput = [];
+    logger.info("test message", { key: "value", count: 42 });
+
+    expect(stderrOutput.length).toBeGreaterThanOrEqual(1);
+    const lastOutput = stderrOutput[stderrOutput.length - 1];
+    const parsed = JSON.parse(lastOutput.trim());
+
+    expect(parsed).toHaveProperty("context");
+    expect(parsed.context).toEqual({ key: "value", count: 42 });
+  });
+
+  it("log output without context does not include context field", async () => {
+    const { logger } = await import("./logger.js?t=" + Date.now() + "noctx");
+
+    stderrOutput = [];
+    logger.info("no context message");
+
+    expect(stderrOutput.length).toBeGreaterThanOrEqual(1);
+    const lastOutput = stderrOutput[stderrOutput.length - 1];
+    const parsed = JSON.parse(lastOutput.trim());
+
+    expect(parsed).not.toHaveProperty("context");
+  });
+
+  it("all four log levels produce valid JSON with correct level field", async () => {
+    const { logger } = await import("./logger.js?t=" + Date.now() + "levels");
+
+    const levels: LogLevel[] = ["debug", "info", "warn", "error"];
+    for (const level of levels) {
+      stderrOutput = [];
+      logger[level](`test ${level} message`);
+
+      expect(stderrOutput.length).toBeGreaterThanOrEqual(1);
+      const lastOutput = stderrOutput[stderrOutput.length - 1];
+      const parsed = JSON.parse(lastOutput.trim());
+
+      expect(parsed.level).toBe(level);
+      expect(parsed.message).toBe(`test ${level} message`);
+      expect(typeof parsed.timestamp).toBe("string");
+    }
+  });
+});

package/src/utils/logger.ts

@@ -0,0 +1,53 @@
+// Structured logger — outputs JSON to stderr
+// Requirements: 21.1, 21.2
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+
+interface LogEntry {
+  level: LogLevel;
+  timestamp: string; // ISO 8601
+  message: string;
+  context?: Record<string, unknown>;
+}
+
+const LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+function parseLevel(raw: string | undefined): LogLevel {
+  if (raw && raw in LEVELS) return raw as LogLevel;
+  return "info";
+}
+
+const configuredLevel: LogLevel = parseLevel(process.env.LOG_LEVEL?.toLowerCase());
+
+function log(level: LogLevel, message: string, context?: Record<string, unknown>): void {
+  if (LEVELS[level] < LEVELS[configuredLevel]) return;
+
+  const entry: LogEntry = {
+    level,
+    timestamp: new Date().toISOString(),
+    message,
+    ...(context !== undefined ? { context } : {}),
+  };
+
+  process.stderr.write(JSON.stringify(entry) + "\n");
+}
+
+export const logger = {
+  debug(message: string, context?: Record<string, unknown>): void {
+    log("debug", message, context);
+  },
+  info(message: string, context?: Record<string, unknown>): void {
+    log("info", message, context);
+  },
+  warn(message: string, context?: Record<string, unknown>): void {
+    log("warn", message, context);
+  },
+  error(message: string, context?: Record<string, unknown>): void {
+    log("error", message, context);
+  },
+};

package/src/utils/mcp-response.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+
+export const McpContentSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("text"),
+    text: z.string(),
+  }),
+  z.object({
+    type: z.literal("image"),
+    data: z.string(),
+    mimeType: z.string(),
+  }),
+  z.object({
+    type: z.literal("resource"),
+    resource: z.object({
+      uri: z.string(),
+      mimeType: z.string().optional(),
+      text: z.string().optional(),
+    }),
+  }),
+]);
+
+export type McpContent = z.infer<typeof McpContentSchema>;
+
+export type McpResponse = {
+  content: McpContent[];
+};
+
+export function createMcpResponse(
+  data: unknown,
+  summary: string,
+  options?: { 
+    query?: string; 
+    results?: Array<{ 
+      id: string; 
+      type: string; 
+      title?: string; 
+      content: string;
+      importance?: number;
+      scope?: { repo: string; folder?: string; language?: string };
+      created_at?: string;
+      updated_at?: string;
+      hit_count?: number;
+      recall_count?: number;
+      last_used_at?: string | null;
+      expires_at?: string | null;
+    }> 
+  }
+): McpResponse {
+  const { query, results } = options || {};
+  
+  const content: McpContent[] = [
+    {
+      type: "text",
+      text: summary,
+    },
+  ];
+
+  // Add resource for each result with embedded content
+  if (results && results.length > 0) {
+    for (const result of results) {
+      const resultId = Buffer.from(result.id).toString('base64').substring(0, 8);
+      
+      // Generate title from content if not present
+      const title = result.title || (result.content.length > 50 ? result.content.substring(0, 50) + '...' : result.content);
+      
+      content.push({
+        type: "resource",
+        resource: {
+          uri: `memory://${resultId}`,
+          mimeType: "application/json",
+          text: JSON.stringify({
+            id: result.id,
+            type: result.type,
+            title: title,
+            content: result.content,
+            importance: result.importance,
+            scope: result.scope,
+            created_at: result.created_at,
+            updated_at: result.updated_at,
+            hit_count: result.hit_count,
+            recall_count: result.recall_count,
+            last_used_at: result.last_used_at,
+            expires_at: result.expires_at
+          })
+        }
+      });
+    }
+  }
+
+  return { content };
+}
+
+export function createTextOnlyResponse(text: string): McpResponse {
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+  };
+}
+
+export function isMcpResponse(obj: unknown): obj is McpResponse {
+  if (typeof obj !== "object" || obj === null) return false;
+  const response = obj as Record<string, unknown>;
+  if (!Array.isArray(response.content)) return false;
+  return response.content.every(
+    (item) =>
+      typeof item === "object" &&
+      item !== null &&
+      "type" in item &&
+      typeof item.type === "string"
+  );
+}

package/src/utils/normalize.test.ts

@@ -0,0 +1,203 @@
+// Feature: memory-mcp-optimization
+// Unit + Property tests for normalize(), tokenize(), and STOPWORDS
+// Requirements: 5.4, 5.5, 17.3, 17.4, 17.7
+
+import { describe, it, expect } from "vitest";
+import * as fc from "fast-check";
+import { normalize, tokenize, STOPWORDS } from "./normalize.js";
+
+// ─── Unit Tests: normalize() ─────────────────────────────────────────────────
+
+describe("normalize() — unit tests", () => {
+  it("converts text to lowercase", () => {
+    expect(normalize("Hello World")).toBe("hello world");
+    expect(normalize("TYPESCRIPT")).toBe("typescript");
+    expect(normalize("CamelCase")).toBe("camelcase");
+  });
+
+  it("trims leading and trailing whitespace", () => {
+    expect(normalize("  hello  ")).toBe("hello");
+    expect(normalize("\t  text  \n")).toBe("text");
+  });
+
+  it("replaces special characters with spaces", () => {
+    const result = normalize("hello!world@test#value");
+    // Special chars replaced by spaces, then collapsed
+    expect(result).not.toContain("!");
+    expect(result).not.toContain("@");
+    expect(result).not.toContain("#");
+  });
+
+  it("collapses multiple spaces into one", () => {
+    expect(normalize("hello   world")).toBe("hello world");
+    expect(normalize("a  b  c")).toBe("a b c");
+  });
+
+  it("handles empty string", () => {
+    expect(normalize("")).toBe("");
+  });
+
+  it("handles string with only special characters", () => {
+    expect(normalize("!!!@@@###")).toBe("");
+  });
+
+  it("preserves alphanumeric characters", () => {
+    expect(normalize("abc123")).toBe("abc123");
+  });
+});
+
+// ─── Unit Tests: tokenize() ──────────────────────────────────────────────────
+
+describe("tokenize() — unit tests", () => {
+  it("removes stopwords from output", () => {
+    const tokens = tokenize("the quick brown fox");
+    expect(tokens).not.toContain("the");
+    expect(tokens).toContain("quick");
+    expect(tokens).toContain("brown");
+    expect(tokens).toContain("fox");
+  });
+
+  it("removes short words (length <= 0 after normalize)", () => {
+    // tokenize filters tokens with length > 0 and not in STOPWORDS
+    const tokens = tokenize("a b c hello");
+    // "a", "b", "c" are stopwords or single chars
+    expect(tokens).toContain("hello");
+  });
+
+  it("returns empty array for all-stopword input", () => {
+    const tokens = tokenize("the and or but");
+    expect(tokens).toEqual([]);
+  });
+
+  it("handles empty string", () => {
+    expect(tokenize("")).toEqual([]);
+  });
+
+  it("normalizes before tokenizing (lowercase, trim)", () => {
+    const tokens1 = tokenize("TypeScript");
+    const tokens2 = tokenize("typescript");
+    expect(tokens1).toEqual(tokens2);
+  });
+
+  it("removes Indonesian stopwords", () => {
+    const tokens = tokenize("yang dan di ke dari ini itu coding");
+    expect(tokens).not.toContain("yang");
+    expect(tokens).not.toContain("dan");
+    expect(tokens).toContain("coding");
+  });
+});
+
+// ─── Property 4: Tokenisasi konsisten antara SQLiteStore dan StubVectorStore ──
+// Feature: memory-mcp-optimization, Property 4: Tokenisasi konsisten
+// Validates: Requirements 4.4, 5.2, 5.3
+
+describe("Property 4: Tokenisasi konsisten antara SQLiteStore dan StubVectorStore", () => {
+  it("tokenize() is deterministic — same input always produces same output", () => {
+    fc.assert(
+      fc.property(
+        fc.string({ minLength: 0, maxLength: 100 }),
+        (text: string) => {
+          // Both SQLiteStore and StubVectorStore use tokenize() from normalize.ts
+          // So testing tokenize() determinism validates consistency between them
+          const result1 = tokenize(text);
+          const result2 = tokenize(text);
+          expect(result1).toEqual(result2);
+        }
+      ),
+      { numRuns: 200 }
+    );
+  });
+
+  it("tokenize() output is a subset of normalize() tokens", () => {
+    fc.assert(
+      fc.property(
+        fc.string({ minLength: 0, maxLength: 100 }),
+        (text: string) => {
+          const normalized = normalize(text);
+          const allTokens = normalized.split(" ").filter((t) => t.length > 0);
+          const filtered = tokenize(text);
+          // Every token in filtered must appear in allTokens
+          for (const token of filtered) {
+            expect(allTokens).toContain(token);
+          }
+        }
+      ),
+      { numRuns: 200 }
+    );
+  });
+});
+
+// ─── Property 5: normalize() idempoten ganda ─────────────────────────────────
+// Feature: memory-mcp-optimization, Property 5: normalize() idempoten ganda
+// Validates: Requirements 5.4, 5.5
+
+describe("Property 5: normalize() idempoten ganda", () => {
+  it("normalize(normalize(text)) === normalize(text) for 100+ random inputs", () => {
+    fc.assert(
+      fc.property(
+        fc.string({ minLength: 0, maxLength: 200 }),
+        (text: string) => {
+          const once = normalize(text);
+          const twice = normalize(once);
+          expect(twice).toBe(once);
+        }
+      ),
+      { numRuns: 200 }
+    );
+  });
+
+  it("normalize is idempotent for specific edge cases", () => {
+    const cases = [
+      "",
+      "   ",
+      "Hello World!",
+      "UPPERCASE",
+      "already normalized",
+      "multiple   spaces",
+      "special!@#chars",
+      "123numbers456",
+    ];
+    for (const text of cases) {
+      const once = normalize(text);
+      const twice = normalize(once);
+      expect(twice).toBe(once);
+    }
+  });
+});
+
+// ─── Property 21: Stopword list tidak mengandung duplikat ────────────────────
+// Feature: memory-mcp-optimization, Property 21: Stopword no duplicates
+// Validates: Requirement 17.4
+
+describe("Property 21: Stopword list tidak mengandung duplikat", () => {
+  it("STOPWORDS has no duplicate entries", () => {
+    // Since STOPWORDS is a Set, duplicates are automatically removed.
+    // We verify the source array (before Set construction) has no duplicates
+    // by checking that Set size equals the number of unique entries.
+    // The Set itself guarantees uniqueness, so we verify the exported Set is consistent.
+    const stopwordsArray = Array.from(STOPWORDS);
+    const uniqueSet = new Set(stopwordsArray);
+    expect(uniqueSet.size).toBe(stopwordsArray.length);
+  });
+
+  it("all STOPWORDS entries are lowercase strings", () => {
+    for (const word of STOPWORDS) {
+      expect(typeof word).toBe("string");
+      expect(word).toBe(word.toLowerCase());
+    }
+  });
+
+  it("STOPWORDS is non-empty", () => {
+    expect(STOPWORDS.size).toBeGreaterThan(0);
+  });
+
+  it("property: no string appears more than once in STOPWORDS", () => {
+    // This is a structural property — verified once (not random inputs needed)
+    // since STOPWORDS is a constant Set
+    const seen = new Set<string>();
+    for (const word of STOPWORDS) {
+      expect(seen.has(word)).toBe(false);
+      seen.add(word);
+    }
+  });
+});

package/src/utils/normalize.ts

@@ -0,0 +1,53 @@
+// Normalization layer for text processing
+// Requirements: 4.1, 5.1, 17.4
+
+// Combined English + Indonesian stopwords (all lowercase, no duplicates)
+export const STOPWORDS: ReadonlySet<string> = new Set([
+  // English stopwords
+  "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+  "of", "with", "by", "from", "up", "about", "into", "through", "during",
+  "is", "are", "was", "were", "be", "been", "being", "have", "has", "had",
+  "do", "does", "did", "will", "would", "could", "should", "may", "might",
+  "shall", "can", "need", "dare", "ought", "used",
+  "i", "me", "my", "myself", "we", "our", "ours", "ourselves",
+  "you", "your", "yours", "yourself", "yourselves",
+  "he", "him", "his", "himself", "she", "her", "hers", "herself",
+  "it", "its", "itself", "they", "them", "their", "theirs", "themselves",
+  "what", "which", "who", "whom", "this", "that", "these", "those",
+  "am", "if", "then", "else", "when", "where", "why", "how",
+  "all", "both", "each", "few", "more", "most", "other", "some", "such",
+  "no", "not", "only", "same", "so", "than", "too", "very",
+  "just", "because", "as", "until", "while", "although", "though",
+  "after", "before", "since", "between", "out", "off", "over", "under",
+  "again", "further", "once", "here", "there", "any", "also",
+  // Indonesian stopwords
+  "yang", "dan", "di", "ke", "dari", "ini", "itu", "dengan", "untuk",
+  "pada", "adalah", "dalam", "tidak", "akan", "juga", "ada", "saya",
+  "kita", "kami", "mereka", "dia", "ia", "anda", "kamu", "aku",
+  "bisa", "dapat", "harus", "sudah", "telah", "sedang", "masih",
+  "lebih", "sangat", "paling", "hanya", "jika", "kalau", "karena",
+  "sehingga", "namun", "tetapi", "tapi", "atau", "maupun", "bahwa",
+  "oleh", "seperti", "antara", "setelah", "sebelum", "ketika", "saat",
+  "semua", "setiap", "beberapa", "banyak", "sedikit", "lain", "lainnya",
+  "tersebut", "nya", "pun", "lah", "kah", "dah",
+  "agar", "supaya", "maka", "meski", "walaupun", "meskipun",
+  "selain", "selama", "sejak", "hingga", "sampai", "tentang",
+  "terhadap", "melalui", "tanpa", "bagi", "atas", "bawah",
+  "depan", "belakang", "kiri", "kanan", "sini", "sana", "situ",
+  "begitu", "begini", "demikian", "hal", "cara", "waktu", "tempat",
+]);
+
+export function normalize(text: string): string {
+  return text
+    .toLowerCase()
+    // Keep alphanumeric characters and spaces, including Unicode letters (for Indonesian, etc.)
+    .replace(/[^\w\s\u00C0-\u017F]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function tokenize(text: string): string[] {
+  return normalize(text)
+    .split(" ")
+    .filter((token) => token.length > 0 && !STOPWORDS.has(token));
+}

package/src/utils/query-expander.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { expandQuery } from "../utils/query-expander.js";
+
+describe("expandQuery", () => {
+  it("returns original query when no prompt provided", () => {
+    expect(expandQuery("database")).toBe("database");
+    expect(expandQuery("api endpoint")).toBe("api endpoint");
+  });
+
+  it("expands query with prompt keywords", () => {
+    const result = expandQuery("database", "user authentication implementation");
+    expect(result).toContain("database");
+    expect(result).toContain("user");
+    expect(result).toContain("auth");
+  });
+
+  it("expands known keywords", () => {
+    const result = expandQuery("auth", "login system");
+    expect(result).toContain("auth");
+    expect(result).toContain("login");
+    expect(result).toContain("password");
+  });
+
+  it("limits to 10 keywords", () => {
+    const result = expandQuery("api", "building a rest endpoint with controller and route handling");
+    const words = result.split(" ");
+    expect(words.length).toBeLessThanOrEqual(10);
+  });
+
+  it("removes duplicates", () => {
+    const result = expandQuery("database", "database query optimization");
+    const words = result.split(" ");
+    const unique = new Set(words);
+    expect(words.length).toBe(unique.size);
+  });
+
+  it("handles empty prompt gracefully", () => {
+    expect(expandQuery("test", "")).toBe("test");
+  });
+});

package/src/utils/query-expander.ts

@@ -0,0 +1,60 @@
+import { tokenize, normalize } from "./normalize.js";
+
+const KEYWORD_EXPANSION: Record<string, string[]> = {
+  database: ["sql", "orm", "query", "migration", "schema", "postgresql", "mysql"],
+  auth: ["authentication", "login", "password", "jwt", "token", "session", "oauth"],
+  login: ["auth", "authentication", "password", "jwt", "session", "credential"],
+  api: ["rest", "endpoint", "controller", "route", "request", "response"],
+  test: ["testing", "unit", "integration", "vitest", "jest", "mock"],
+  model: ["entity", "schema", "relation", "eloquent", "migration"],
+  frontend: ["ui", "react", "vue", "component", "tailwind", "css"],
+  backend: ["server", "api", "controller", "service", "database"],
+  security: ["encryption", "hash", "csrf", "xss", "sanitize", "validation"],
+  performance: ["cache", "optimization", "index", "query", "lazy", "eager"],
+  deployment: ["docker", "nginx", "ci", "cd", "pipeline", "deploy"],
+};
+
+function expandKeyword(keyword: string): string[] {
+  const normalized = normalize(keyword).toLowerCase();
+  return KEYWORD_EXPANSION[normalized] || [];
+}
+
+function extractIntentKeywords(prompt: string): string[] {
+  const tokens = tokenize(prompt);
+  
+  const important = tokens.filter((t) => {
+    if (t.length < 3) return false;
+    const stopWords = [
+      "need", "want", "how", "what", "when", "where", "why",
+      "using", "with", "implement", "create", "build", "make",
+      "have", "get", "find", "look", "search", "trying",
+    ];
+    return !stopWords.includes(t);
+  });
+
+  const expanded: string[] = [];
+  for (const token of important) {
+    expanded.push(token);
+    const expansions = expandKeyword(token);
+    expanded.push(...expansions);
+  }
+
+  return [...new Set(expanded)];
+}
+
+export function expandQuery(query: string, prompt?: string): string {
+  const normalizedQuery = normalize(query);
+  const queryTokens = normalizedQuery.split(/\s+/).filter((t) => t.length > 0);
+
+  if (!prompt) {
+    return queryTokens.join(" ");
+  }
+
+  const intentKeywords = extractIntentKeywords(prompt);
+
+  const combined = new Set<string>([...queryTokens, ...intentKeywords]);
+
+  const result = Array.from(combined).slice(0, 10).join(" ");
+
+  return result.length > 3 ? result : queryTokens.join(" ");
+}

package/storage/.gitkeep

@@ -0,0 +1,5 @@
+# Storage Directory
+
+This directory contains the SQLite database file for MCP Local Memory.
+
+The database file (`memory.db`) is excluded from git via `.gitignore`.