gitmem-mcp 0.2.0

package/dist/services/embedding.js

@@ -0,0 +1,243 @@
+/**
+ * Embedding Service — Multi-provider embedding abstraction
+ *
+ * Generates text embeddings for semantic search using multiple providers.
+ * Auto-detects provider from available API keys.
+ *
+ * Provider detection (in priority order):
+ *   GITMEM_EMBEDDING_PROVIDER=openai|openrouter|ollama — force provider
+ *   OPENAI_API_KEY → OpenAI direct (text-embedding-3-small)
+ *   OPENROUTER_API_KEY → OpenRouter (text-embedding-3-small via openrouter.ai)
+ *   OLLAMA_URL → Ollama local (nomic-embed-text, 768-dim — requires pgvector dimension match)
+ *
+ * If no provider is configured, embed() returns null (graceful degradation).
+ * Records stored without embeddings can still be retrieved by ID/filters,
+ * but won't appear in semantic search results.
+ */
+// Default embedding dimensions per provider
+const OPENAI_EMBEDDING_DIM = 1536;
+const OLLAMA_DEFAULT_DIM = 768;
+// Model configuration
+const OPENAI_EMBEDDING_MODEL = "text-embedding-3-small";
+const OPENROUTER_EMBEDDING_MODEL = "openai/text-embedding-3-small";
+const OLLAMA_EMBEDDING_MODEL = "nomic-embed-text";
+// API URLs
+const OPENAI_API_URL = "https://api.openai.com/v1/embeddings";
+const OPENROUTER_API_URL = "https://openrouter.ai/api/v1/embeddings";
+/**
+ * Normalize a vector to unit length
+ */
+function normalize(vec) {
+    let magnitude = 0;
+    for (const v of vec) {
+        magnitude += v * v;
+    }
+    magnitude = Math.sqrt(magnitude);
+    if (magnitude === 0)
+        return vec;
+    return vec.map((v) => v / magnitude);
+}
+/**
+ * Detect the best available embedding provider from environment
+ */
+export function detectProvider() {
+    const forced = process.env.GITMEM_EMBEDDING_PROVIDER?.toLowerCase();
+    // Forced provider
+    if (forced && forced !== "auto") {
+        switch (forced) {
+            case "openai": {
+                const key = process.env.OPENAI_API_KEY;
+                if (!key) {
+                    console.warn("[embedding] GITMEM_EMBEDDING_PROVIDER=openai but OPENAI_API_KEY not set");
+                    return { provider: "none", apiUrl: "", apiKey: "", model: "", expectedDim: 0 };
+                }
+                return {
+                    provider: "openai",
+                    apiUrl: OPENAI_API_URL,
+                    apiKey: key,
+                    model: OPENAI_EMBEDDING_MODEL,
+                    expectedDim: OPENAI_EMBEDDING_DIM,
+                };
+            }
+            case "openrouter": {
+                const key = process.env.OPENROUTER_API_KEY;
+                if (!key) {
+                    console.warn("[embedding] GITMEM_EMBEDDING_PROVIDER=openrouter but OPENROUTER_API_KEY not set");
+                    return { provider: "none", apiUrl: "", apiKey: "", model: "", expectedDim: 0 };
+                }
+                return {
+                    provider: "openrouter",
+                    apiUrl: OPENROUTER_API_URL,
+                    apiKey: key,
+                    model: OPENROUTER_EMBEDDING_MODEL,
+                    expectedDim: OPENAI_EMBEDDING_DIM,
+                };
+            }
+            case "ollama": {
+                const url = process.env.OLLAMA_URL || "http://localhost:11434";
+                return {
+                    provider: "ollama",
+                    apiUrl: `${url}/api/embed`,
+                    apiKey: "",
+                    model: process.env.GITMEM_OLLAMA_MODEL || OLLAMA_EMBEDDING_MODEL,
+                    expectedDim: parseInt(process.env.GITMEM_EMBEDDING_DIM || String(OLLAMA_DEFAULT_DIM), 10),
+                };
+            }
+            default:
+                console.warn(`[embedding] Unknown provider: ${forced}`);
+                return { provider: "none", apiUrl: "", apiKey: "", model: "", expectedDim: 0 };
+        }
+    }
+    // Auto-detect from available keys (priority: OpenAI > OpenRouter > Ollama)
+    if (process.env.OPENAI_API_KEY) {
+        return {
+            provider: "openai",
+            apiUrl: OPENAI_API_URL,
+            apiKey: process.env.OPENAI_API_KEY,
+            model: OPENAI_EMBEDDING_MODEL,
+            expectedDim: OPENAI_EMBEDDING_DIM,
+        };
+    }
+    if (process.env.OPENROUTER_API_KEY) {
+        return {
+            provider: "openrouter",
+            apiUrl: OPENROUTER_API_URL,
+            apiKey: process.env.OPENROUTER_API_KEY,
+            model: OPENROUTER_EMBEDDING_MODEL,
+            expectedDim: OPENAI_EMBEDDING_DIM,
+        };
+    }
+    if (process.env.OLLAMA_URL) {
+        const url = process.env.OLLAMA_URL;
+        return {
+            provider: "ollama",
+            apiUrl: `${url}/api/embed`,
+            apiKey: "",
+            model: process.env.GITMEM_OLLAMA_MODEL || OLLAMA_EMBEDDING_MODEL,
+            expectedDim: parseInt(process.env.GITMEM_EMBEDDING_DIM || String(OLLAMA_DEFAULT_DIM), 10),
+        };
+    }
+    return { provider: "none", apiUrl: "", apiKey: "", model: "", expectedDim: 0 };
+}
+// Cached config (loaded once per process)
+let _config = null;
+/**
+ * Get the current embedding configuration (cached)
+ */
+export function getEmbeddingConfig() {
+    if (!_config) {
+        _config = detectProvider();
+        if (_config.provider !== "none") {
+            console.error(`[embedding] Provider: ${_config.provider} (model: ${_config.model}, dim: ${_config.expectedDim})`);
+        }
+        else {
+            console.error("[embedding] No embedding provider configured — scars will be stored without embeddings");
+        }
+    }
+    return _config;
+}
+/**
+ * Reset cached config (for testing)
+ */
+export function resetEmbeddingConfig() {
+    _config = null;
+}
+/**
+ * Generate an embedding for text using OpenAI-compatible API (OpenAI or OpenRouter)
+ */
+async function embedOpenAI(text, config) {
+    const response = await fetch(config.apiUrl, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: config.model,
+            input: text,
+        }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`${config.provider} embedding error (${response.status}): ${errorText}`);
+    }
+    const data = (await response.json());
+    if (!data.data || data.data.length === 0) {
+        throw new Error(`No embedding data in ${config.provider} response`);
+    }
+    return data.data[0].embedding;
+}
+/**
+ * Generate an embedding using Ollama local API
+ */
+async function embedOllama(text, config) {
+    const response = await fetch(config.apiUrl, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: config.model,
+            input: text,
+        }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Ollama embedding error (${response.status}): ${errorText}`);
+    }
+    const data = (await response.json());
+    if (!data.embeddings || data.embeddings.length === 0) {
+        throw new Error("No embedding data in Ollama response");
+    }
+    return data.embeddings[0];
+}
+/**
+ * Generate an embedding for the given text.
+ *
+ * Returns normalized embedding vector, or null if no provider is configured.
+ * Throws on API errors (network, auth, rate limit).
+ */
+export async function embed(text) {
+    const config = getEmbeddingConfig();
+    if (config.provider === "none") {
+        return null;
+    }
+    let raw;
+    switch (config.provider) {
+        case "openai":
+        case "openrouter":
+            raw = await embedOpenAI(text, config);
+            break;
+        case "ollama":
+            raw = await embedOllama(text, config);
+            break;
+        default:
+            return null;
+    }
+    // Validate dimensions
+    if (raw.length !== config.expectedDim) {
+        console.warn(`[embedding] Unexpected dimensions: got ${raw.length}, expected ${config.expectedDim}`);
+        // Don't throw — store what we got, let pgvector validate
+    }
+    return normalize(raw);
+}
+/**
+ * Get the expected embedding dimension for the current provider.
+ * Returns 0 if no provider configured.
+ */
+export function getEmbeddingDim() {
+    return getEmbeddingConfig().expectedDim;
+}
+/**
+ * Check if embedding generation is available.
+ */
+export function isEmbeddingAvailable() {
+    return getEmbeddingConfig().provider !== "none";
+}
+/**
+ * Get the current provider name.
+ */
+export function getProviderName() {
+    return getEmbeddingConfig().provider;
+}
+//# sourceMappingURL=embedding.js.map

package/dist/services/embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../src/services/embedding.ts"],"names":[],"mappings":"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"}

package/dist/services/gitmem-dir.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Resolved .gitmem directory path
+ *
+ * Solves: process.cwd() changes when agents cd into other repos (e.g., /workspace/gitmem),
+ * but .gitmem/ was created in the project root (e.g., /workspace/orchestra/).
+ * The MCP server is long-running, so we resolve the path once and cache it.
+ *
+ * Resolution order:
+ * 1. Cached path from session_start (most reliable — session_start created the directory)
+ * 2. Walk up from process.cwd() looking for existing .gitmem/ sentinels
+ * 3. Fall back to process.cwd()/.gitmem (original behavior)
+ */
+/**
+ * Set the .gitmem directory path (called by session_start after creating it)
+ */
+export declare function setGitmemDir(dir: string): void;
+/**
+ * Get the resolved .gitmem directory path
+ */
+export declare function getGitmemDir(): string;
+/**
+ * Get a file path within the .gitmem directory
+ */
+export declare function getGitmemPath(filename: string): string;
+/**
+ * Get the per-session directory path: .gitmem/sessions/<sessionId>/
+ * Creates the directory if it doesn't exist.
+ */
+export declare function getSessionDir(sessionId: string): string;
+/**
+ * Get a file path within a per-session directory.
+ */
+export declare function getSessionPath(sessionId: string, filename: string): string;
+/**
+ * Clear the cached path (for testing)
+ */
+export declare function clearGitmemDirCache(): void;
+//# sourceMappingURL=gitmem-dir.d.ts.map

package/dist/services/gitmem-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitmem-dir.d.ts","sourceRoot":"","sources":["../../src/services/gitmem-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAG9C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA6BrC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/services/gitmem-dir.js

@@ -0,0 +1,84 @@
+/**
+ * Resolved .gitmem directory path
+ *
+ * Solves: process.cwd() changes when agents cd into other repos (e.g., /workspace/gitmem),
+ * but .gitmem/ was created in the project root (e.g., /workspace/orchestra/).
+ * The MCP server is long-running, so we resolve the path once and cache it.
+ *
+ * Resolution order:
+ * 1. Cached path from session_start (most reliable — session_start created the directory)
+ * 2. Walk up from process.cwd() looking for existing .gitmem/ sentinels
+ * 3. Fall back to process.cwd()/.gitmem (original behavior)
+ */
+import * as path from "path";
+import * as fs from "fs";
+let cachedGitmemDir = null;
+/**
+ * Set the .gitmem directory path (called by session_start after creating it)
+ */
+export function setGitmemDir(dir) {
+    cachedGitmemDir = dir;
+    console.error(`[gitmem-dir] Cached .gitmem path: ${dir}`);
+}
+/**
+ * Get the resolved .gitmem directory path
+ */
+export function getGitmemDir() {
+    // 1. Use cached path from session_start
+    if (cachedGitmemDir && fs.existsSync(cachedGitmemDir)) {
+        return cachedGitmemDir;
+    }
+    // 2. Walk up from CWD looking for existing .gitmem directory
+    //    Sentinel files checked in priority order:
+    //    - active-sessions.json  (multi-session registry, GIT-19)
+    //    - config.json           (project-level gitmem config)
+    const sentinels = ["active-sessions.json", "config.json"];
+    let dir = process.cwd();
+    const root = path.parse(dir).root;
+    while (dir !== root) {
+        const candidate = path.join(dir, ".gitmem");
+        for (const sentinel of sentinels) {
+            if (fs.existsSync(path.join(candidate, sentinel))) {
+                cachedGitmemDir = candidate;
+                console.error(`[gitmem-dir] Found .gitmem via walk-up (${sentinel}): ${candidate}`);
+                return candidate;
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    // 3. Fall back to CWD (original behavior)
+    const fallback = path.join(process.cwd(), ".gitmem");
+    console.error(`[gitmem-dir] Falling back to CWD: ${fallback}`);
+    return fallback;
+}
+/**
+ * Get a file path within the .gitmem directory
+ */
+export function getGitmemPath(filename) {
+    return path.join(getGitmemDir(), filename);
+}
+/**
+ * Get the per-session directory path: .gitmem/sessions/<sessionId>/
+ * Creates the directory if it doesn't exist.
+ */
+export function getSessionDir(sessionId) {
+    const sessionsDir = path.join(getGitmemDir(), "sessions", sessionId);
+    if (!fs.existsSync(sessionsDir)) {
+        fs.mkdirSync(sessionsDir, { recursive: true });
+        console.error(`[gitmem-dir] Created session directory: ${sessionsDir}`);
+    }
+    return sessionsDir;
+}
+/**
+ * Get a file path within a per-session directory.
+ */
+export function getSessionPath(sessionId, filename) {
+    return path.join(getSessionDir(sessionId), filename);
+}
+/**
+ * Clear the cached path (for testing)
+ */
+export function clearGitmemDirCache() {
+    cachedGitmemDir = null;
+}
+//# sourceMappingURL=gitmem-dir.js.map

package/dist/services/gitmem-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitmem-dir.js","sourceRoot":"","sources":["../../src/services/gitmem-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB,IAAI,eAAe,GAAkB,IAAI,CAAC;AAE1C;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,eAAe,GAAG,GAAG,CAAC;IACtB,OAAO,CAAC,KAAK,CAAC,qCAAqC,GAAG,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,wCAAwC;IACxC,IAAI,eAAe,IAAI,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACtD,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,6DAA6D;IAC7D,+CAA+C;IAC/C,8DAA8D;IAC9D,2DAA2D;IAC3D,MAAM,SAAS,GAAG,CAAC,sBAAsB,EAAE,aAAa,CAAC,CAAC;IAC1D,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IACxB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAClC,OAAO,GAAG,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC5C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;gBAClD,eAAe,GAAG,SAAS,CAAC;gBAC5B,OAAO,CAAC,KAAK,CAAC,2CAA2C,QAAQ,MAAM,SAAS,EAAE,CAAC,CAAC;gBACpF,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QACD,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,0CAA0C;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC;IACrD,OAAO,CAAC,KAAK,CAAC,qCAAqC,QAAQ,EAAE,CAAC,CAAC;IAC/D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACrE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,2CAA2C,WAAW,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,QAAgB;IAChE,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,eAAe,GAAG,IAAI,CAAC;AACzB,CAAC"}

package/dist/services/local-file-storage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Local File Storage — Free Tier Backend
+ *
+ * Stores scars, sessions, decisions, and scar usage as JSON files
+ * in the .gitmem/ directory of the current project.
+ *
+ * Provides keyword-based search (no embeddings needed).
+ */
+import type { RelevantScar } from "../types/index.js";
+export declare class LocalFileStorage {
+    private basePath;
+    constructor(basePath?: string);
+    private ensureDir;
+    private getFilePath;
+    private readCollection;
+    private writeCollection;
+    /**
+     * List records with optional filters
+     */
+    list<T extends Record<string, unknown>>(collection: string, options?: {
+        filters?: Record<string, string>;
+        order?: string;
+        limit?: number;
+    }): Promise<T[]>;
+    /**
+     * Get a single record by ID
+     */
+    get<T extends Record<string, unknown>>(collection: string, id: string): Promise<T | null>;
+    /**
+     * Upsert a record (insert or update by ID)
+     */
+    upsert<T extends Record<string, unknown>>(collection: string, data: T & {
+        id: string;
+    }): Promise<T>;
+    /**
+     * Delete a record by ID
+     */
+    delete(collection: string, id: string): Promise<boolean>;
+    /**
+     * Keyword-based search for scars (free tier alternative to semantic search)
+     *
+     * Scores by: title match (3x), keyword match (2x), description match (1x)
+     */
+    keywordSearch(query: string, k?: number): Promise<RelevantScar[]>;
+    /**
+     * Get the count of learnings stored locally
+     */
+    getLearningCount(): number;
+    /**
+     * Load starter scars from a JSON file into local storage
+     */
+    loadStarterScars(scarsPath: string): Promise<number>;
+}
+export declare function getLocalFileStorage(): LocalFileStorage;
+export declare function resetLocalFileStorage(): void;
+//# sourceMappingURL=local-file-storage.d.ts.map

package/dist/services/local-file-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-storage.d.ts","sourceRoot":"","sources":["../../src/services/local-file-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAKtD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,CAAC,EAAE,MAAM;IAK7B,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,eAAe;IAoBvB;;OAEG;IACG,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GACL,OAAO,CAAC,CAAC,EAAE,CAAC;IA8Bf;;OAEG;IACG,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzC,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAKpB;;OAEG;IACG,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,CAAC,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GACvB,OAAO,CAAC,CAAC,CAAC;IAcb;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ9D;;;;OAIG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAyClE;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAyB3D;AAeD,wBAAgB,mBAAmB,IAAI,gBAAgB,CAKtD;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/services/local-file-storage.js

@@ -0,0 +1,213 @@
+/**
+ * Local File Storage — Free Tier Backend
+ *
+ * Stores scars, sessions, decisions, and scar usage as JSON files
+ * in the .gitmem/ directory of the current project.
+ *
+ * Provides keyword-based search (no embeddings needed).
+ */
+import * as fs from "fs";
+import * as path from "path";
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+const WARN_FILE_SIZE = 1 * 1024 * 1024; // 1MB
+export class LocalFileStorage {
+    basePath;
+    constructor(basePath) {
+        this.basePath = basePath || path.join(process.cwd(), ".gitmem");
+        this.ensureDir();
+    }
+    ensureDir() {
+        if (!fs.existsSync(this.basePath)) {
+            fs.mkdirSync(this.basePath, { recursive: true });
+        }
+    }
+    getFilePath(collection) {
+        return path.join(this.basePath, `${collection}.json`);
+    }
+    readCollection(collection) {
+        const filePath = this.getFilePath(collection);
+        if (!fs.existsSync(filePath))
+            return [];
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            console.error(`[local-storage] Failed to read ${collection}.json, starting fresh`);
+            return [];
+        }
+    }
+    writeCollection(collection, data) {
+        const filePath = this.getFilePath(collection);
+        const json = JSON.stringify(data, null, 2);
+        const size = Buffer.byteLength(json, "utf-8");
+        if (size > WARN_FILE_SIZE) {
+            console.error(`[local-storage] Warning: ${collection}.json is ${(size / 1024).toFixed(0)}KB`);
+        }
+        if (size > MAX_FILE_SIZE) {
+            console.error(`[local-storage] ${collection}.json exceeds 10MB, evicting oldest entries`);
+            // Keep most recent 80% of entries
+            const trimmed = data.slice(Math.floor(data.length * 0.2));
+            fs.writeFileSync(filePath, JSON.stringify(trimmed, null, 2), "utf-8");
+            return;
+        }
+        fs.writeFileSync(filePath, json, "utf-8");
+    }
+    /**
+     * List records with optional filters
+     */
+    async list(collection, options = {}) {
+        let records = this.readCollection(collection);
+        // Apply simple filters
+        if (options.filters) {
+            for (const [key, value] of Object.entries(options.filters)) {
+                const cleanValue = value.startsWith("eq.") ? value.slice(3) : value;
+                records = records.filter((r) => String(r[key]) === cleanValue);
+            }
+        }
+        // Apply ordering
+        if (options.order) {
+            const [field, direction] = options.order.split(".");
+            const asc = direction !== "desc";
+            records.sort((a, b) => {
+                const av = String(a[field] || "");
+                const bv = String(b[field] || "");
+                return asc ? av.localeCompare(bv) : bv.localeCompare(av);
+            });
+        }
+        // Apply limit
+        if (options.limit) {
+            records = records.slice(0, options.limit);
+        }
+        return records;
+    }
+    /**
+     * Get a single record by ID
+     */
+    async get(collection, id) {
+        const records = this.readCollection(collection);
+        return records.find((r) => r.id === id) || null;
+    }
+    /**
+     * Upsert a record (insert or update by ID)
+     */
+    async upsert(collection, data) {
+        const records = this.readCollection(collection);
+        const existingIndex = records.findIndex((r) => r.id === data.id);
+        if (existingIndex >= 0) {
+            records[existingIndex] = { ...records[existingIndex], ...data };
+        }
+        else {
+            records.push(data);
+        }
+        this.writeCollection(collection, records);
+        return data;
+    }
+    /**
+     * Delete a record by ID
+     */
+    async delete(collection, id) {
+        const records = this.readCollection(collection);
+        const filtered = records.filter((r) => r.id !== id);
+        if (filtered.length === records.length)
+            return false;
+        this.writeCollection(collection, filtered);
+        return true;
+    }
+    /**
+     * Keyword-based search for scars (free tier alternative to semantic search)
+     *
+     * Scores by: title match (3x), keyword match (2x), description match (1x)
+     */
+    async keywordSearch(query, k = 5) {
+        const learnings = this.readCollection("learnings");
+        const queryTokens = tokenize(query.toLowerCase());
+        if (queryTokens.length === 0)
+            return [];
+        const maxScore = queryTokens.length * 6; // max possible per token: 3+2+1
+        const scored = learnings.map((l) => {
+            let score = 0;
+            const titleTokens = tokenize(String(l.title || "").toLowerCase());
+            const descTokens = tokenize(String(l.description || "").toLowerCase());
+            const kwTokens = (l.keywords || []).map((k) => k.toLowerCase());
+            for (const qt of queryTokens) {
+                if (titleTokens.some((t) => t.includes(qt) || qt.includes(t)))
+                    score += 3;
+                if (kwTokens.some((k) => k.includes(qt) || qt.includes(k)))
+                    score += 2;
+                if (descTokens.some((t) => t.includes(qt) || qt.includes(t)))
+                    score += 1;
+            }
+            return {
+                learning: l,
+                score,
+                similarity: Math.round((score / maxScore) * 1000) / 1000,
+            };
+        });
+        return scored
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k)
+            .map((s) => ({
+            id: String(s.learning.id),
+            title: String(s.learning.title),
+            description: String(s.learning.description),
+            severity: String(s.learning.severity || "medium"),
+            counter_arguments: s.learning.counter_arguments || [],
+            similarity: s.similarity,
+        }));
+    }
+    /**
+     * Get the count of learnings stored locally
+     */
+    getLearningCount() {
+        return this.readCollection("learnings").length;
+    }
+    /**
+     * Load starter scars from a JSON file into local storage
+     */
+    async loadStarterScars(scarsPath) {
+        try {
+            const raw = fs.readFileSync(scarsPath, "utf-8");
+            const scars = JSON.parse(raw);
+            const existing = this.readCollection("learnings");
+            const existingIds = new Set(existing.map((e) => e.id));
+            let loaded = 0;
+            for (const scar of scars) {
+                if (!existingIds.has(scar.id)) {
+                    existing.push(scar);
+                    loaded++;
+                }
+            }
+            if (loaded > 0) {
+                this.writeCollection("learnings", existing);
+            }
+            return loaded;
+        }
+        catch (error) {
+            console.error("[local-storage] Failed to load starter scars:", error);
+            return 0;
+        }
+    }
+}
+/**
+ * Tokenize text into words, stripping punctuation
+ */
+function tokenize(text) {
+    return text
+        .replace(/[^\w\s-]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 1);
+}
+// Singleton instance
+let _instance = null;
+export function getLocalFileStorage() {
+    if (!_instance) {
+        _instance = new LocalFileStorage();
+    }
+    return _instance;
+}
+export function resetLocalFileStorage() {
+    _instance = null;
+}
+//# sourceMappingURL=local-file-storage.js.map