mcp memory libsql

Local 2025-08-31 23:31:26 0
databases @spences10/mcp-memory-libsql

A high-performance MCP server utilizing libSQL for persistent memory and vector search capabilities, enabling efficient entity management and semantic knowledge storage.

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.

Glama badge

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:

{
    "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.

Add this to your Claude Desktop configuration for WSL environments:

{
    "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:

{
    "env": {
        "LIBSQL_URL": "file:/path/to/database.db"
    }
}

For remote libSQL databases (e.g., Turso):

{
    "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):
pnpm changeset
  1. Version the package (updates version and CHANGELOG):
pnpm changeset version
  1. Publish to npm (will prompt for 2FA code):
pnpm release

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

License

MIT License - see the LICENSE file for details.

Acknowledgments

[
  {
    "description": "Create new entities with observations and optional embeddings",
    "inputSchema": {
      "properties": {
        "entities": {
          "items": {
            "properties": {
              "embedding": {
                "description": "Optional vector embedding for similarity search",
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              "entityType": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "observations": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "name",
              "entityType",
              "observations"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "entities"
      ],
      "type": "object"
    },
    "name": "create_entities"
  },
  {
    "description": "Search for entities and their relations using text or vector similarity",
    "inputSchema": {
      "properties": {
        "query": {
          "oneOf": [
            {
              "description": "Text search query",
              "type": "string"
            },
            {
              "description": "Vector for similarity search",
              "items": {
                "type": "number"
              },
              "type": "array"
            }
          ]
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "name": "search_nodes"
  },
  {
    "description": "Get recent entities and their relations",
    "inputSchema": {
      "properties": {},
      "required": [],
      "type": "object"
    },
    "name": "read_graph"
  },
  {
    "description": "Create relations between entities",
    "inputSchema": {
      "properties": {
        "relations": {
          "items": {
            "properties": {
              "source": {
                "type": "string"
              },
              "target": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            },
            "required": [
              "source",
              "target",
              "type"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "relations"
      ],
      "type": "object"
    },
    "name": "create_relations"
  },
  {
    "description": "Delete an entity and all its associated data (observations and relations)",
    "inputSchema": {
      "properties": {
        "name": {
          "description": "Name of the entity to delete",
          "type": "string"
        }
      },
      "required": [
        "name"
      ],
      "type": "object"
    },
    "name": "delete_entity"
  },
  {
    "description": "Delete a specific relation between entities",
    "inputSchema": {
      "properties": {
        "source": {
          "description": "Source entity name",
          "type": "string"
        },
        "target": {
          "description": "Target entity name",
          "type": "string"
        },
        "type": {
          "description": "Type of relation",
          "type": "string"
        }
      },
      "required": [
        "source",
        "target",
        "type"
      ],
      "type": "object"
    },
    "name": "delete_relation"
  }
]