@iflow-mcp/joleyline-mcp-memory-libsql 0.0.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Scott Spence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# mcp-memory-libsql
+
+A high-performance, persistent memory system for the Model Context
+Protocol (MCP) powered by libSQL. This server provides vector search
+capabilities and efficient knowledge storage using libSQL as the
+backing store.
+
+<a href="https://glama.ai/mcp/servers/22lg4lq768">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/22lg4lq768/badge" alt="Glama badge" />
+</a>
+
+## Features
+
+- 🚀 High-performance vector search using libSQL
+- 💾 Persistent storage of entities and relations
+- 🔍 Semantic search capabilities
+- 🔄 Knowledge graph management
+- 🌐 Compatible with local and remote libSQL databases
+- 🔒 Secure token-based authentication for remote databases
+
+## Configuration
+
+This server is designed to be used as part of an MCP configuration.
+Here are examples for different environments:
+
+### Cline Configuration
+
+Add this to your Cline MCP settings:
+
+```json
+{
+	"mcpServers": {
+		"mcp-memory-libsql": {
+			"command": "npx",
+			"args": ["-y", "mcp-memory-libsql"],
+			"env": {
+				"LIBSQL_URL": "file:/path/to/your/database.db"
+			}
+		}
+	}
+}
+```
+
+### Claude Desktop with WSL Configuration
+
+For a detailed guide on setting up this server with Claude Desktop in
+WSL, see
+[Getting MCP Server Working with Claude Desktop in WSL](https://scottspence.com/posts/getting-mcp-server-working-with-claude-desktop-in-wsl).
+
+Add this to your Claude Desktop configuration for WSL environments:
+
+```json
+{
+	"mcpServers": {
+		"mcp-memory-libsql": {
+			"command": "wsl.exe",
+			"args": [
+				"bash",
+				"-c",
+				"source ~/.nvm/nvm.sh && LIBSQL_URL=file:/path/to/database.db /home/username/.nvm/versions/node/v20.12.1/bin/npx mcp-memory-libsql"
+			]
+		}
+	}
+}
+```
+
+### Database Configuration
+
+The server supports both local SQLite and remote libSQL databases
+through the LIBSQL_URL environment variable:
+
+For local SQLite databases:
+
+```json
+{
+	"env": {
+		"LIBSQL_URL": "file:/path/to/database.db"
+	}
+}
+```
+
+For remote libSQL databases (e.g., Turso):
+
+```json
+{
+	"env": {
+		"LIBSQL_URL": "libsql://your-database.turso.io",
+		"LIBSQL_AUTH_TOKEN": "your-auth-token"
+	}
+}
+```
+
+Note: When using WSL, ensure the database path uses the Linux
+filesystem format (e.g., `/home/username/...`) rather than Windows
+format.
+
+By default, if no URL is provided, it will use `file:/memory-tool.db`
+in the current directory.
+
+## API
+
+The server implements the standard MCP memory interface with
+additional vector search capabilities:
+
+- Entity Management
+  - Create/Update entities with embeddings
+  - Delete entities
+  - Search entities by similarity
+- Relation Management
+  - Create relations between entities
+  - Delete relations
+  - Query related entities
+
+## Architecture
+
+The server uses a libSQL database with the following schema:
+
+- Entities table: Stores entity information and embeddings
+- Relations table: Stores relationships between entities
+- Vector search capabilities implemented using libSQL's built-in
+  vector operations
+
+## Development
+
+### Publishing
+
+Due to npm 2FA requirements, publishing needs to be done manually:
+
+1. Create a changeset (documents your changes):
+
+```bash
+pnpm changeset
+```
+
+2. Version the package (updates version and CHANGELOG):
+
+```bash
+pnpm changeset version
+```
+
+3. Publish to npm (will prompt for 2FA code):
+
+```bash
+pnpm release
+```
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines
+before submitting pull requests.
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built on the
+  [Model Context Protocol](https://github.com/modelcontextprotocol)
+- Powered by [libSQL](https://github.com/tursodatabase/libsql)

package/dist/config/index.js

@@ -0,0 +1,89 @@
+import { config } from 'dotenv';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { readFileSync } from 'fs';
+// Load environment variables from .env file
+config();
+// Get directory paths
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = join(__dirname, '..', '..');
+/**
+ * Default configuration values
+ */
+const defaultConfig = {
+    server: {
+        name: 'mcp-memory-libsql',
+        version: '0.0.14', // This should be read from package.json
+        transport: 'stdio', // Default to stdio transport
+        sseOptions: {
+            port: 3000,
+            host: 'localhost',
+            cors: true,
+        },
+    },
+    database: {
+        url: 'file:memory.db',
+    },
+    embedding: {
+        model: 'Xenova/bge-small-en-v1.5',
+        dimension: 384,
+        cachePath: join(rootDir, 'models'),
+    },
+    logging: {
+        level: 'info',
+        includeTimestamps: true,
+    },
+};
+/**
+ * Load configuration from environment variables and defaults
+ */
+export function loadConfig() {
+    try {
+        // Read package.json for name and version
+        const packageJson = JSON.parse(readFileSync(join(rootDir, 'package.json'), 'utf8'));
+        // Create configuration with environment variables and defaults
+        const config = {
+            server: {
+                name: packageJson.name || defaultConfig.server.name,
+                version: packageJson.version || defaultConfig.server.version,
+                transport: process.env.TRANSPORT_TYPE || defaultConfig.server.transport,
+                sseOptions: defaultConfig.server.sseOptions,
+            },
+            database: {
+                url: process.env.DATABASE_URL || defaultConfig.database.url,
+                authToken: process.env.DATABASE_AUTH_TOKEN,
+            },
+            embedding: {
+                model: process.env.EMBEDDING_MODEL || defaultConfig.embedding.model,
+                dimension: parseInt(process.env.EMBEDDING_DIMENSION || String(defaultConfig.embedding.dimension), 10),
+                cachePath: process.env.MODEL_CACHE_PATH || defaultConfig.embedding.cachePath,
+            },
+            logging: {
+                level: process.env.LOG_LEVEL || defaultConfig.logging.level,
+                includeTimestamps: process.env.LOG_TIMESTAMPS === 'true' || defaultConfig.logging.includeTimestamps,
+            },
+        };
+        // Override SSE options if provided in environment variables
+        if (config.server.transport === 'sse') {
+            config.server.sseOptions = {
+                port: process.env.SSE_PORT ? parseInt(process.env.SSE_PORT, 10) : defaultConfig.server.sseOptions.port,
+                host: process.env.SSE_HOST || defaultConfig.server.sseOptions.host,
+                cors: process.env.SSE_CORS ? process.env.SSE_CORS === 'true' : defaultConfig.server.sseOptions.cors,
+            };
+        }
+        return config;
+    }
+    catch (error) {
+        console.error('Error loading configuration:', error);
+        return defaultConfig;
+    }
+}
+// Export the configuration
+export const appConfig = loadConfig();
+// Export specific configurations for convenience
+export const serverConfig = appConfig.server;
+export const databaseConfig = appConfig.database;
+export const embeddingConfig = appConfig.embedding;
+export const loggingConfig = appConfig.logging;

package/dist/db/core.js

@@ -0,0 +1,234 @@
+import { createClient } from '@libsql/client';
+import { logger } from '../utils/logger.js';
+import { EMBEDDING_DIMENSION } from '../services/embedding-service.js';
+import { createEntities, getEntity, getRecentEntities, deleteEntity } from '../services/entity-service.js';
+import { searchSimilar, searchEntities } from './index.js';
+import { createRelations, deleteRelation, getRelationsForEntities } from '../services/relation-service.js';
+import { readGraph, searchNodes } from '../services/graph-service.js';
+/**
+ * Core DatabaseManager class that handles database connection and initialization
+ */
+export class DatabaseManager {
+    /**
+     * Private constructor to enforce singleton pattern
+     * @param config - Database configuration
+     */
+    constructor(config) {
+        if (!config.url) {
+            throw new Error('Database URL is required');
+        }
+        this.client = createClient({
+            url: config.url,
+            authToken: config.authToken,
+        });
+    }
+    /**
+     * Gets the singleton instance of DatabaseManager
+     * @param config - Database configuration
+     * @returns DatabaseManager instance
+     */
+    static async getInstance(config) {
+        if (!DatabaseManager.instance) {
+            DatabaseManager.instance = new DatabaseManager(config);
+            await DatabaseManager.instance.initialize();
+        }
+        return DatabaseManager.instance;
+    }
+    /**
+     * Gets the singleton instance of DatabaseManager (snake_case alias for backward compatibility)
+     * @param config - Database configuration
+     * @returns DatabaseManager instance
+     */
+    static async get_instance(config) {
+        return DatabaseManager.getInstance(config);
+    }
+    /**
+     * Gets the database client
+     * @returns Database client
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Gets the database client (snake_case alias for backward compatibility)
+     * @returns Database client
+     */
+    get_client() {
+        return this.client;
+    }
+    /**
+     * Initializes the database schema
+     */
+    async initialize() {
+        try {
+            logger.info(`Initializing database schema with vector dimension: ${EMBEDDING_DIMENSION}`);
+            // Create tables if they don't exist - each as a single statement
+            await this.client.execute({
+                sql: `
+					CREATE TABLE IF NOT EXISTS entities (
+						name TEXT PRIMARY KEY,
+						entity_type TEXT NOT NULL,
+						embedding F32_BLOB(${EMBEDDING_DIMENSION}), -- Using configurable dimension
+						created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+					)
+				`
+            });
+            await this.client.execute({
+                sql: `
+					CREATE TABLE IF NOT EXISTS observations (
+						id INTEGER PRIMARY KEY AUTOINCREMENT,
+						entity_name TEXT NOT NULL,
+						content TEXT NOT NULL,
+						created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+						FOREIGN KEY (entity_name) REFERENCES entities(name)
+					)
+				`
+            });
+            await this.client.execute({
+                sql: `
+					CREATE TABLE IF NOT EXISTS relations (
+						id INTEGER PRIMARY KEY AUTOINCREMENT,
+						source TEXT NOT NULL,
+						target TEXT NOT NULL,
+						relation_type TEXT NOT NULL,
+						created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+						FOREIGN KEY (source) REFERENCES entities(name),
+						FOREIGN KEY (target) REFERENCES entities(name)
+					)
+				`
+            });
+            // Create all indexes in a single batch transaction
+            await this.client.batch([
+                {
+                    sql: 'CREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name)',
+                    args: [],
+                },
+                {
+                    sql: 'CREATE INDEX IF NOT EXISTS idx_observations_entity ON observations(entity_name)',
+                    args: [],
+                },
+                {
+                    sql: 'CREATE INDEX IF NOT EXISTS idx_relations_source ON relations(source)',
+                    args: [],
+                },
+                {
+                    sql: 'CREATE INDEX IF NOT EXISTS idx_relations_target ON relations(target)',
+                    args: [],
+                },
+                {
+                    sql: 'CREATE INDEX IF NOT EXISTS idx_entities_embedding ON entities(libsql_vector_idx(embedding))',
+                    args: [],
+                },
+            ], 'write');
+        }
+        catch (error) {
+            throw new Error(`Database initialization failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Creates or updates entities with observations and optional embeddings
+     * @param entities - Array of entities to create or update
+     */
+    async create_entities(entities) {
+        return createEntities(entities);
+    }
+    /**
+     * Searches for entities by similarity to the provided embedding vector
+     * @param embedding - Vector embedding to search with
+     * @param limit - Maximum number of results to return
+     * @param includeEmbeddings - Whether to include embeddings in the returned entities (default: false)
+     * @returns Array of search results with entities and distance scores
+     */
+    async search_similar(embedding, limit = 5, includeEmbeddings = false) {
+        const client = this.getClient();
+        return searchSimilar(client, embedding, limit, includeEmbeddings);
+    }
+    /**
+     * Gets an entity by name
+     * @param name - Name of the entity to retrieve
+     * @param includeEmbeddings - Whether to include embeddings in the returned entity (default: false)
+     * @returns Entity object with observations and optional embedding
+     */
+    async get_entity(name, includeEmbeddings = false) {
+        return getEntity(name, includeEmbeddings);
+    }
+    /**
+     * Searches for entities by text query in name, type, or observations
+     * @param query - Text query to search for
+     * @param includeEmbeddings - Whether to include embeddings in the returned entities (default: false)
+     * @returns Array of matching entities
+     */
+    async search_entities(query, includeEmbeddings = false) {
+        const client = this.getClient();
+        return searchEntities(client, query, includeEmbeddings);
+    }
+    /**
+     * Gets the most recently created entities
+     * @param limit - Maximum number of entities to return
+     * @param includeEmbeddings - Whether to include embeddings in the returned entities (default: false)
+     * @returns Array of recent entities
+     */
+    async get_recent_entities(limit = 10, includeEmbeddings = false) {
+        return getRecentEntities(limit, includeEmbeddings);
+    }
+    /**
+     * Creates relations between entities
+     * @param relations - Array of relations to create
+     */
+    async create_relations(relations) {
+        return createRelations(relations);
+    }
+    /**
+     * Deletes an entity and all its associated data
+     * @param name - Name of the entity to delete
+     */
+    async delete_entity(name) {
+        return deleteEntity(name);
+    }
+    /**
+     * Deletes a specific relation between entities
+     * @param source - Source entity name
+     * @param target - Target entity name
+     * @param type - Relation type
+     */
+    async delete_relation(source, target, type) {
+        return deleteRelation(source, target, type);
+    }
+    /**
+     * Gets relations for a set of entities
+     * @param entities - Array of entities to get relations for
+     * @returns Array of relations
+     */
+    async get_relations_for_entities(entities) {
+        const entityNames = entities.map(entity => entity.name);
+        return getRelationsForEntities(entityNames);
+    }
+    /**
+     * Reads the recent entities and their relations to form a graph
+     * @param includeEmbeddings - Whether to include embeddings in the returned entities (default: false)
+     * @returns Graph result with entities and relations
+     */
+    async read_graph(includeEmbeddings = false) {
+        return readGraph(10, includeEmbeddings);
+    }
+    /**
+     * Searches for nodes in the graph by text query or vector similarity
+     * @param query - Text query or vector embedding for search
+     * @param includeEmbeddings - Whether to include embeddings in the returned entities (default: false)
+     * @returns Graph result with matching entities and their relations
+     */
+    async search_nodes(query, includeEmbeddings = false) {
+        return searchNodes(query, includeEmbeddings);
+    }
+    /**
+     * Closes the database connection
+     */
+    async close() {
+        try {
+            await this.client.close();
+        }
+        catch (error) {
+            logger.error('Error closing database connection:', error);
+        }
+    }
+}

package/dist/db/index.js

@@ -0,0 +1,45 @@
+// Re-export types
+export * from './types.js';
+// Re-export core database manager for backward compatibility
+export { DatabaseManager } from './core.js';
+// Re-export entity operations from services layer
+export { createEntities, getEntity, getRecentEntities, deleteEntity, } from '../services/entity-service.js';
+// Re-export relation operations from services layer
+export { createRelations, deleteRelation, getRelationsForEntities, } from '../services/relation-service.js';
+// Re-export graph operations from services layer
+export { readGraph, searchNodes, } from '../services/graph-service.js';
+// Re-export vector utilities from services layer
+export { arrayToVectorString, extractVector, cosineSimilarity, euclideanDistance, } from '../services/vector-service.js';
+// Re-export embedding service functions for backward compatibility
+export { EMBEDDING_DIMENSION as DEFAULT_EMBEDDING_DIMENSION, } from '../services/embedding-service.js';
+// Re-export embedding functions
+export const generateEmbedding = async (input, modelName) => {
+    const { embeddingService } = await import('../services/embedding-service.js');
+    return embeddingService.generateEmbedding(input);
+};
+export const generateEmbeddings = async (inputs, modelName) => {
+    const { embeddingService } = await import('../services/embedding-service.js');
+    return embeddingService.generateEmbeddings(inputs);
+};
+// Re-export searchSimilar function for backward compatibility
+export const searchSimilar = async (client, embedding, limit = 5, includeEmbeddings = false) => {
+    // This is a compatibility wrapper that adapts the new service API to the old function signature
+    const { databaseService } = await import('../services/database-service.js');
+    const { searchNodes } = await import('../services/graph-service.js');
+    // Use the searchNodes function with the vector embedding
+    const result = await searchNodes(embedding, includeEmbeddings);
+    // Convert the result to the format expected by the old API
+    return result.entities.map(entity => ({
+        entity,
+        distance: 0, // We don't have distance information in the new API
+    }));
+};
+// Re-export searchEntities function for backward compatibility
+export const searchEntities = async (client, query, includeEmbeddings = false) => {
+    // This is a compatibility wrapper that adapts the new service API to the old function signature
+    const { searchNodes } = await import('../services/graph-service.js');
+    // Use the searchNodes function with the text query
+    const result = await searchNodes(query, includeEmbeddings);
+    // Return just the entities
+    return result.entities;
+};