@jungjaehoon/mama-core 1.1.2 → 1.1.3

package/dist/embedding-cache.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * MAMA (Memory-Augmented MCP Architecture) - Embedding Cache
+ *
+ * LRU cache for embedding vectors to avoid re-computation
+ *
+ * Task 2: Implement Embedding Cache
+ * AC #3: Cache embeddings to avoid re-computation
+ * Target: > 80% cache hit ratio
+ *
+ * @module embedding-cache
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.embeddingCache = exports.EmbeddingCache = exports.MAX_CACHE_SIZE = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+// Cache configuration
+exports.MAX_CACHE_SIZE = 1000; // Max 1000 entries (story req 2.2)
+const CLEANUP_THRESHOLD = 1100; // Trigger cleanup at 110%
+/**
+ * LRU Cache for embeddings
+ *
+ * Key: SHA-256 hash of decision text
+ * Value: {embedding: Float32Array, timestamp: number, hits: number}
+ *
+ * Eviction: Least Recently Used when size > MAX_CACHE_SIZE
+ */
+class EmbeddingCache {
+    cache;
+    stats;
+    constructor() {
+        this.cache = new Map();
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            totalSize: 0,
+        };
+    }
+    /**
+     * Generate cache key from text
+     *
+     * Task 2.3: Key = decision text hash (SHA-256)
+     */
+    generateKey(text) {
+        if (!text || typeof text !== 'string') {
+            throw new Error('Text must be a non-empty string');
+        }
+        return crypto_1.default.createHash('sha256').update(text).digest('hex');
+    }
+    /**
+     * Get embedding from cache
+     *
+     * Task 2.2: Cache hit updates LRU position
+     */
+    get(text) {
+        const key = this.generateKey(text);
+        const entry = this.cache.get(key);
+        if (entry) {
+            // Cache hit - update LRU position
+            this.stats.hits++;
+            entry.hits++;
+            entry.lastAccessed = Date.now();
+            // Move to end (most recently used)
+            this.cache.delete(key);
+            this.cache.set(key, entry);
+            return entry.embedding;
+        }
+        // Cache miss
+        this.stats.misses++;
+        return null;
+    }
+    /**
+     * Store embedding in cache
+     *
+     * Task 2.2: Add to cache with LRU tracking
+     * Task 2.5: Implement cache eviction (LRU)
+     */
+    set(text, embedding) {
+        const key = this.generateKey(text);
+        // Check if already exists (update case)
+        if (this.cache.has(key)) {
+            const entry = this.cache.get(key);
+            entry.embedding = embedding;
+            entry.lastAccessed = Date.now();
+            // Move to end (most recently used)
+            this.cache.delete(key);
+            this.cache.set(key, entry);
+            return;
+        }
+        // New entry
+        const entry = {
+            embedding,
+            timestamp: Date.now(),
+            lastAccessed: Date.now(),
+            hits: 0,
+        };
+        this.cache.set(key, entry);
+        this.stats.totalSize++;
+        // Trigger cleanup if threshold exceeded
+        if (this.cache.size > CLEANUP_THRESHOLD) {
+            this.evictLRU();
+        }
+    }
+    /**
+     * Evict least recently used entries
+     *
+     * Task 2.5: Implement cache eviction (LRU)
+     * Strategy: Remove entries until size <= MAX_CACHE_SIZE
+     *
+     * Eviction order:
+     * 1. Oldest lastAccessed (LRU)
+     * 2. If tied, lowest hits
+     */
+    evictLRU() {
+        const targetEvictions = this.cache.size - exports.MAX_CACHE_SIZE;
+        if (targetEvictions <= 0) {
+            return;
+        }
+        // Convert to array for sorting
+        const entries = Array.from(this.cache.entries());
+        // Sort by LRU (oldest first), then by hits (lowest first)
+        entries.sort((a, b) => {
+            const [, entryA] = a;
+            const [, entryB] = b;
+            // Primary: lastAccessed (ascending - oldest first)
+            if (entryA.lastAccessed !== entryB.lastAccessed) {
+                return entryA.lastAccessed - entryB.lastAccessed;
+            }
+            // Secondary: hits (ascending - lowest first)
+            return entryA.hits - entryB.hits;
+        });
+        // Evict oldest entries
+        for (let i = 0; i < targetEvictions; i++) {
+            const [key] = entries[i];
+            this.cache.delete(key);
+            this.stats.evictions++;
+            this.stats.totalSize--;
+        }
+    }
+    /**
+     * Get cache hit ratio
+     *
+     * Task 2.4: Cache hit ratio target: > 80%
+     */
+    getHitRatio() {
+        const total = this.stats.hits + this.stats.misses;
+        if (total === 0) {
+            return 0;
+        }
+        return this.stats.hits / total;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            hitRatio: this.getHitRatio(),
+            size: this.cache.size,
+            maxSize: exports.MAX_CACHE_SIZE,
+        };
+    }
+    /**
+     * Clear cache
+     */
+    clear() {
+        this.cache.clear();
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            totalSize: 0,
+        };
+    }
+}
+exports.EmbeddingCache = EmbeddingCache;
+// Singleton instance
+exports.embeddingCache = new EmbeddingCache();
+//# sourceMappingURL=embedding-cache.js.map

package/dist/embedding-client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * MAMA Embedding Client
+ *
+ * HTTP client for the embedding server running in MCP server.
+ * Used by hooks for fast embedding generation.
+ *
+ * Features:
+ * - Auto-discovery via port file
+ * - Timeout handling
+ * - Fallback to local embedding when server unavailable
+ *
+ * @module embedding-client
+ */
+export declare const DEFAULT_PORT: number;
+export declare const HOST = "127.0.0.1";
+export declare const TIMEOUT_MS = 500;
+export declare const PORT_FILE: string;
+export interface ServerStatus {
+    status: string;
+    model?: string;
+    dimension?: number;
+    uptime?: number;
+}
+/**
+ * Get server port from port file or default
+ */
+export declare function getServerPort(): number;
+/**
+ * Check if embedding server is running
+ */
+export declare function isServerRunning(): Promise<boolean>;
+/**
+ * Generate embedding via HTTP server
+ *
+ * @param text - Text to embed
+ * @returns Embedding or null if failed
+ */
+export declare function getEmbeddingFromServer(text: string): Promise<Float32Array | null>;
+/**
+ * Get server status
+ */
+export declare function getServerStatus(): Promise<ServerStatus | null>;
+//# sourceMappingURL=embedding-client.d.ts.map

package/dist/embedding-client.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * MAMA Embedding Client
+ *
+ * HTTP client for the embedding server running in MCP server.
+ * Used by hooks for fast embedding generation.
+ *
+ * Features:
+ * - Auto-discovery via port file
+ * - Timeout handling
+ * - Fallback to local embedding when server unavailable
+ *
+ * @module embedding-client
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PORT_FILE = exports.TIMEOUT_MS = exports.HOST = exports.DEFAULT_PORT = void 0;
+exports.getServerPort = getServerPort;
+exports.isServerRunning = isServerRunning;
+exports.getEmbeddingFromServer = getEmbeddingFromServer;
+exports.getServerStatus = getServerStatus;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const debug_logger_js_1 = require("./debug-logger.js");
+function resolveConfiguredPort() {
+    const rawPort = process.env.MAMA_EMBEDDING_PORT || process.env.MAMA_HTTP_PORT || '';
+    const parsedPort = parseInt(rawPort, 10);
+    if (Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort < 65536) {
+        return parsedPort;
+    }
+    return 3849;
+}
+// Configuration
+exports.DEFAULT_PORT = resolveConfiguredPort();
+exports.HOST = '127.0.0.1';
+exports.TIMEOUT_MS = 500; // 500ms timeout for fast response
+exports.PORT_FILE = path_1.default.join(process.env.HOME || '/tmp', '.mama-embedding-port');
+/**
+ * Get server port from port file or default
+ */
+function getServerPort() {
+    try {
+        if (fs_1.default.existsSync(exports.PORT_FILE)) {
+            const port = parseInt(fs_1.default.readFileSync(exports.PORT_FILE, 'utf8').trim(), 10);
+            if (port > 0 && port < 65536) {
+                return port;
+            }
+        }
+    }
+    catch {
+        // Ignore errors, use default
+    }
+    return exports.DEFAULT_PORT;
+}
+/**
+ * Check if embedding server is running
+ */
+async function isServerRunning() {
+    const port = getServerPort();
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 200);
+        const response = await fetch(`http://${exports.HOST}:${port}/health`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate embedding via HTTP server
+ *
+ * @param text - Text to embed
+ * @returns Embedding or null if failed
+ */
+async function getEmbeddingFromServer(text) {
+    const port = getServerPort();
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), exports.TIMEOUT_MS);
+        const response = await fetch(`http://${exports.HOST}:${port}/embed`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ text }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (!response.ok) {
+            const error = (await response.json());
+            throw new Error(error.error || 'Server error');
+        }
+        const result = (await response.json());
+        (0, debug_logger_js_1.info)(`[EmbeddingClient] Got embedding in ${result.latency}ms from server`);
+        return new Float32Array(result.embedding);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            (0, debug_logger_js_1.warn)('[EmbeddingClient] Server timeout, will use fallback');
+            return null;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        (0, debug_logger_js_1.warn)(`[EmbeddingClient] Server error: ${message}`);
+        return null;
+    }
+}
+/**
+ * Get server status
+ */
+async function getServerStatus() {
+    const port = getServerPort();
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 200);
+        const response = await fetch(`http://${exports.HOST}:${port}/health`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (response.ok) {
+            return (await response.json());
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=embedding-client.js.map

package/dist/embedding-server/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * MAMA Embedding HTTP Server
+ *
+ * HTTP API for embedding generation, integrated with MCP server.
+ * Provides fast embedding access for Claude Code hooks.
+ *
+ * Features:
+ * - Model stays loaded in memory (singleton)
+ * - HTTP API at localhost:${MAMA_EMBEDDING_PORT || MAMA_HTTP_PORT || 3849}
+ * - Health check endpoint
+ * - Shared model with MCP server
+ *
+ * @module embedding-http-server
+ */
+import type { IncomingMessage, ServerResponse, Server as HTTPServer } from 'http';
+export declare const SHUTDOWN_TOKEN: string;
+export declare const DEFAULT_PORT: number;
+export declare const HOST = "127.0.0.1";
+export declare const PORT_FILE: string;
+/**
+ * Request handler type
+ */
+type RequestHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+/**
+ * MessageRouter interface
+ */
+interface MessageRouter {
+    process(message: unknown): Promise<unknown>;
+}
+/**
+ * SessionStore interface
+ */
+interface SessionStore {
+    getHistory?(sessionId: string): unknown[];
+    getHistoryByChannel?(source: string, channelId: string): unknown[];
+}
+/**
+ * Server options
+ */
+export interface ServerOptions {
+    messageRouter?: MessageRouter;
+    sessionStore?: SessionStore;
+    graphHandler?: RequestHandler;
+}
+/**
+ * Clean up port file on exit
+ */
+export declare function cleanupPortFile(): void;
+/**
+ * Start the HTTP embedding server
+ *
+ * @param port - Port to listen on (default: DEFAULT_PORT)
+ * @returns HTTP server instance
+ */
+export declare function startEmbeddingServer(port?: number, options?: ServerOptions): Promise<HTTPServer | null>;
+/**
+ * Pre-warm the embedding model
+ */
+export declare function warmModel(): Promise<{
+    success: boolean;
+    latency?: number;
+    error?: string;
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map