mcp-memory-libsql-go

A Go implementation of the MCP Memory Server using libSQL for persistent storage with vector search capabilities.

Overview

This project started as a 1:1 feature port of the TypeScript mcp-memory-libsql project to Go. However, this project has since evolved to included much-needed improvements upon the original codebase.

mcp-memory-libsql-go provides a high-performance, persistent memory server for the Model Context Protocol (MCP) using libSQL (a fork of SQLite by Turso) for robust data storage, including vector search capabilities.

The go implemenation has a few advantages:

• 2x performance

• 40% less memory footprint

• single binary with no runtime dependencies

• tursodb/go-libsql driver

• multi-project support

And more!

Features

• Persistent Storage: Uses libSQL for reliable data persistence

• Vector Search: Built-in cosine similarity search using libSQL's vector capabilities

• Hybrid Search: Leverages Semantic & Vector search using a postgres-inspired algorithm

• MCP Integration: Fully compatible with the Model Context Protocol, stdio & sse transports

• Knowledge Graph: Store entities, observations, and relations

• Multiple Database Support: Works with local files and remote libSQL servers

• Multi-Project Support: Optionally, run in a mode that manages separate databases for multiple projects.

• Metrics (optional): No-op by default; enable Prometheus exporter with METRICS_PROMETHEUS=true

Installation

To install the mcp-memory-libsql-go binary to a standard location on your system, use the following command:

This will compile the binary and install it in a standard directory (e.g., ~/.local/bin on Linux or /usr/local/bin on macOS), which should be in your system's PATH.

Quick Start

Local (stdio) – single database

Remote libSQL (stdio)

SSE transport (HTTP)

Docker & Docker Compose (0→1 guide)

This section shows exactly how to get the server running in Docker, with or without docker-compose, and how to enable embeddings and hybrid search.

Prerequisites

• Docker (v20+) and Docker Compose (v2)

• Open ports: 8080 (SSE) and 9090 (metrics/health)

• Disk space for a mounted data volume

1) Build the image

This builds mcp-memory-libsql-go:local and injects version metadata.

2) Create a data directory

3) Choose an embeddings provider (optional but recommended)

Set EMBEDDINGS_PROVIDER and provider-specific variables. For new databases, set EMBEDDING_DIMS to the desired embedding dimensionality. For existing databases, the server automatically detects the current DB dimensionality and adapts provider output vectors to match it (see “Embedding Dimensions” below). Common mappings are listed later in this README.

You can create a .env file for Compose or export env vars directly. Example .env for OpenAI:

Pre-built GHCR image (quick-start)

We publish pre-built images to the GitHub Container Registry (GHCR) so you can get started without building locally.

1. Authenticate (if pulling a private image or using rate-limited endpoints - most of you can skip this step):

2. Pull the latest pre-built image:

3. Run the container (example SSE mode):

4. Use with Docker Compose

Edit the docker-compose.yml to use the GHCR image (replace the build: section or set image:):

Then start:

5. Where to find tags

Visit the project Releases or the GitHub Packages /ghcr page for this repository to find available tags and changelogs.

4) Run with docker-compose (recommended)

The repo includes a docker-compose.yml with profiles:

• single (default): single database at /data/libsql.db

• multi: multi-project mode at /data/projects/<name>/libsql.db

• ollama: optional Ollama sidecar

• localai: optional LocalAI sidecar (OpenAI-compatible)

Start single DB SSE server:

MODE

The Compose setup exposes a single memory service that switches behavior via the MODE environment variable. Set MODE to one of:

• single — single-database mode (default)

• multi — multi-project mode (uses PROJECTS_DIR)

• voyageai — multi-project mode with VoyageAI provider-specific envs

Example one-liners:

OpenAI quick start (using .env above):

Ollama quick start (sidecar):

LocalAI quick start (sidecar):

Multi-project mode:

When Multi-Project Mode is enabled:

• All tool calls MUST include projectArgs.projectName.

• Per-project auth: include projectArgs.authToken. On first use, the token is persisted at <ProjectsDir>/<projectName>/.auth_token (0600). Subsequent calls must present the same token.

• Calls without projectName or with invalid tokens are rejected. You can relax this by setting MULTI_PROJECT_AUTH_REQUIRED=false (see below). You can also enable automatic token initialization with MULTI_PROJECT_AUTO_INIT_TOKEN=true and optionally provide MULTI_PROJECT_DEFAULT_TOKEN.

Health and metrics:

Stop and clean up:

5) Alternative: plain docker run

Remote libSQL (optional)

Point to a remote libSQL instance:

If you later change EMBEDDING_DIMS, it will not alter an existing DB’s schema. The server will continue to adopt the DB’s actual size. To change sizes, create a new DB or migrate*.

Example (Go) SSE client

Multi-project mode

Configure embedding dimensions

Usage

Prompts

This server registers MCP prompts to guide knowledge graph operations:

• quick_start: Quick guidance for using tools (search, read, edit)

• search_nodes_guidance(query, limit?, offset?): Compose effective searches with pagination

• kg_init_new_repo(repoSlug, areas?, includeIssues?): Initialize an optimal KG for a new repository

• kg_update_graph(targetNames, replaceObservations?, mergeObservations?, newRelations?, removeRelations?): Update entities/relations idempotently

• kg_sync_github(tasks, canonicalUrls?): Ensure exactly one canonical GitHub: observation per Task:*

• kg_read_best_practices(query, limit?, offset?, expand?, direction?): Best-practices layered graph reading

Notes:

• Prompts return structured descriptions of recommended tool sequences.

• Follow the recommended order to maintain idempotency and avoid duplicates.

• Text search gracefully falls back to LIKE when FTS5 is unavailable; vector search falls back when vector_top_k is missing.

• Query language highlights for search_nodes (text):

  • FTS first, LIKE fallback; tokenizer includes : - _ @ . /.

  • Prefix: append * to a token (e.g., Task:*). Recommended token length ≥ 2.

  • Field qualifiers (FTS only): entity_name: and content: (e.g., entity_name:"Repo:"* OR content:"P0").

  • Phrases: "exact phrase". Boolean OR supported (space implies AND).

  • Special: Task:* is treated as a prefix on the literal Task: token across both entity name and content.

  • On FTS parse errors (e.g., exotic syntax), the server auto-downgrades to LIKE and normalizes * → %.

  • Ranking: when FTS is active, results are ranked by BM25 if the function is available; otherwise ordered by e.name. BM25 can be disabled or tuned via environment (see below).

Examples:

Using Prompts with MCP Clients

What prompts are

• Prompts are named, parameterized templates you can fetch from the server. They return guidance (and example JSON plans) describing which tools to call and with what arguments.

• Prompts do not execute actions themselves. Your client still calls tools like create_entities, search_nodes, etc., using the plan returned by the prompt.

Workflow

• List prompts: ListPrompts

• Retrieve a prompt: GetPrompt(name, arguments)

• Parse the returned description for the JSON tool plan and follow it to execute tool calls (via CallTool).

Minimal Go example

Tip: Render the prompt description as Markdown to view Mermaid diagrams and copy the embedded JSON plan.

Command-line Flags

• -libsql-url: Database URL (default: file:./libsql.db). Overrides the LIBSQL_URL environment variable.

• -auth-token: Authentication token for remote databases. Overrides the LIBSQL_AUTH_TOKEN environment variable.

• -projects-dir: Base directory for projects. Enables multi-project mode. If this is set, -libsql-url is ignored.

• -transport: Transport to use: stdio (default) or sse.

• -addr: Address to listen on when using SSE transport (default :8080).

• -sse-endpoint: SSE endpoint path when using SSE transport (default /sse).

Environment Variables

• LIBSQL_URL: Database URL (default: file:./libsql.db)

  • Local file: file:./path/to/db.sqlite

  • Remote libSQL: libsql://your-db.turso.io

• LIBSQL_AUTH_TOKEN: Authentication token for remote databases

• EMBEDDING_DIMS: Embedding dimension for new databases (default: 4). Existing DBs are auto-detected and take precedence at runtime.

• EMBEDDINGS_ADAPT_MODE: How to adapt provider vectors to the DB size: pad_or_truncate (default) | pad | truncate.

• PROJECTS_DIR: Base directory for multi-project mode (can also be set via flag -projects-dir).

• MULTI_PROJECT_AUTH_REQUIRED: Set to false/0 to disable per-project auth enforcement (default: required).

• MULTI_PROJECT_AUTO_INIT_TOKEN: Set to true/1 to auto-create a token file on first access when none exists; the first call will fail with an instruction to retry with the token.

• MULTI_PROJECT_DEFAULT_TOKEN: Optional token value used when auto-initializing; if omitted, a random token is generated.

• DB_MAX_OPEN_CONNS: Max open DB connections (optional)

• DB_MAX_IDLE_CONNS: Max idle DB connections (optional)

• DB_CONN_MAX_IDLE_SEC: Connection max idle time in seconds (optional)

• DB_CONN_MAX_LIFETIME_SEC: Connection max lifetime in seconds (optional)

• METRICS_PROMETHEUS: If set (e.g., true), expose Prometheus metrics

• METRICS_PORT: Metrics HTTP port (default 9090) exposing /metrics and /healthz

• EMBEDDINGS_PROVIDER: Optional embeddings source. Supported values and aliases:

  • openai

  • ollama

  • gemini | google | google-gemini | google_genai

  • vertexai | vertex | google-vertex

  • localai | llamacpp | llama.cpp

  • voyageai | voyage | voyage-ai The server still accepts client-supplied embeddings if unset.

• Hybrid Search (optional):

  • HYBRID_SEARCH (true/1 to enable)

  • HYBRID_TEXT_WEIGHT (default 0.4)

  • HYBRID_VECTOR_WEIGHT (default 0.6)

  • HYBRID_RRF_K (default 60)

  • Text ranking (BM25 for FTS):

    • BM25_ENABLE (default true). Set to false or 0 to disable BM25 ordering.

    • BM25_K1 (optional) — saturation parameter. Example 1.2.

    • BM25_B (optional) — length normalization parameter. Example 0.75.

    • If BM25_K1 and BM25_B are both set, the server uses bm25(table,k1,b); otherwise it uses bm25(table).

• OpenAI: OPENAI_API_KEY, OPENAI_EMBEDDINGS_MODEL (default text-embedding-3-small).

• Ollama: OLLAMA_HOST, OLLAMA_EMBEDDINGS_MODEL (default nomic-embed-text, dims 768). Example OLLAMA_HOST=http://localhost:11434.

• Google Gemini (Generative Language API): GOOGLE_API_KEY, GEMINI_EMBEDDINGS_MODEL (default text-embedding-004, dims 768).

• Google Vertex AI: VERTEX_EMBEDDINGS_ENDPOINT, VERTEX_ACCESS_TOKEN (Bearer token). Endpoint format: https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/google/models/{model}:predict.

• LocalAI / llama.cpp (OpenAI-compatible): LOCALAI_BASE_URL (default http://localhost:8080/v1), LOCALAI_EMBEDDINGS_MODEL (default text-embedding-ada-002, dims 1536), optional LOCALAI_API_KEY.

• VoyageAI: VOYAGEAI_API_KEY (or VOYAGE_API_KEY), VOYAGEAI_EMBEDDINGS_MODEL (default voyage-3-lite). Optional VOYAGEAI_EMBEDDINGS_DIMS to explicitly set expected output length if you need to override.

Hybrid Search

Hybrid Search fuses text results (FTS5 when available, otherwise LIKE) with vector similarity using an RRF-style scoring function:

• Score = HYBRID_TEXT_WEIGHT * (1/(k + text_rank)) + HYBRID_VECTOR_WEIGHT * (1/(k + vector_rank))

• Defaults: text=0.4, vector=0.6, k=60

• Requires an embeddings provider to generate a vector for the text query. If unavailable or dims mismatch, hybrid degrades to text-only.

• If FTS5 is not available, the server falls back to LIKE transparently.

• When FTS is active, the text-side rank uses BM25 (if available) for higher-quality ordering; otherwise it uses name ordering.

Enable and tune:

Common model → EMBEDDING_DIMS mapping

![IMPORTANT] Verify your exact model’s dimensionality with a quick API call (examples below) and set EMBEDDING_DIMS accordingly before creating a new DB.

Provider quick verification (curl / Go)

These calls help you confirm the embedding vector length (dimension) for your chosen model.

OpenAI

Ollama (v0.2.6+ embeds endpoint)

Notes:

• The entrypoint no longer calls ollama run for the embedding model; Ollama will lazily load on first /api/embed call.

• You can tune the client timeout via OLLAMA_HTTP_TIMEOUT (e.g. 30s, 60s, or integer seconds like 90).

Gemini (Generative Language API)

Vertex AI (using gcloud for access token)

LocalAI (OpenAI-compatible) VoyageAI (Go SDK)

Running the Server

Single Database Mode

Multi-Project Mode

When running in multi-project mode, the server will create a subdirectory for each project within the specified projects directory. Each subdirectory will contain a libsql.db file.

Tools Provided

The server provides the following MCP tools:

• create_entities: Create new entities with observations and optional embeddings

• search_nodes: Search for entities and their relations using text or vector similarity

• read_graph: Get recent entities and their relations

• create_relations: Create relations between entities

• delete_entity: Delete an entity and all its associated data

• delete_relation: Delete a specific relation between entities

• add_observations: Append observations to an existing entity

• open_nodes: Retrieve entities by names with optional relations

• delete_entities: Delete multiple entities by name (bulk)

• delete_observations: Delete observations by id/content or all for an entity

• delete_relations: Delete multiple relations (bulk)

• update_entities: Update entity metadata/embedding and manage observations (merge/replace)

• update_relations: Update relation tuples

• health_check: Return server info and configuration

• neighbors: 1-hop neighbors for given entities (direction out|in|both)

• walk: bounded-depth graph walk from seeds (direction/limit)

• shortest_path: shortest path between two entities

Tool Summary

Metrics

• Set METRICS_PROMETHEUS=true to expose /metrics and /healthz on METRICS_PORT (default 9090).

• DB hot paths and tool handlers are instrumented with counters and latency histograms.

• Additional gauges and counters:

  • db_pool_gauges{state="in_use|idle"} observed periodically and on health_check

  • stmt_cache_events_total{op="prepare",result="hit|miss"} from the prepared statement cache

Recommended Prometheus histogram buckets (example):

• If metrics are disabled, a no-op implementation is used.

We keep this table and examples up to date as the project evolves. If anything is missing or incorrect, please open an issue or PR.

Planned/Upcoming tools:

– (none for now) –

Using Tools in Multi-Project Mode

When in multi-project mode, all tools accept an optional project context under projectArgs.projectName. If not provided, the server uses the "default" project.

Example

Example

Example

Pagination parameters:

• limit (optional): maximum number of results (default 5 for search_nodes, 10 for read_graph)

• offset (optional): number of results to skip (for paging)

Example

Example

Example

Example

Example

Example

Example

Example

Vector search input: The server accepts vector queries as JSON arrays (e.g., [0.1, 0.2, 0.3, 0.4]). Numeric strings like "0.1" are also accepted. The default embedding dimension is 4 (configurable via EMBEDDING_DIMS).

Embedding Dimensions

The embedding column is F32_BLOB(N), fixed per database. On startup, the server detects the DB’s N and sets runtime behavior accordingly, adapting provider outputs via padding/truncation. Changing EMBEDDING_DIMS does not modify an existing DB; to change N, create a new DB (or migrate). Use the health_check tool to view the active EmbeddingDims.

Transports: stdio and SSE

This server supports both stdio transport (default) and SSE transport. Use -transport sse -addr :8080 -sse-endpoint /sse to run an SSE endpoint. Clients must use an SSE-capable MCP client (e.g., go-sdk SSEClientTransport) to connect.

Development

Prerequisites

• Go 1.24 or later

• libSQL CGO dependencies (automatically handled by go-libsql)

Building

Testing

Client Integration

This server supports both stdio and SSE transports and can run as:

• a raw binary (local stdio or SSE)

• a single Docker container (stdio or SSE)

• a Docker Compose stack (SSE, with multi-project mode and optional embeddings)

Below are reference integrations for Cursor/Cline and other MCP-ready clients.

Cursor / Cline (MCP) via stdio (single DB)

Cursor / Cline (MCP) via stdio (multi-project)

Replace /path/to/some/dir/.memory/memory-bank with your desired base directory. The server will create /path/to/.../<projectName>/libsql.db per project.

Cursor / Cline (MCP) via SSE (Docker Compose, recommended for embeddings)

Run the Compose stack in multi-project mode with Ollama embeddings (hybrid search, pooling, metrics):

Cursor/Cline SSE config:

Other usage patterns

• Raw binary (stdio):

  ./mcp-memory-libsql-go -libsql-url file:./libsql.db

• Raw binary (SSE):

  ./mcp-memory-libsql-go -transport sse -addr :8080 -sse-endpoint /sse # SSE URL: http://localhost:8080/sse

• Docker run (SSE):

  docker run --rm -p 8080:8080 -p 9090:9090 \ -e METRICS_PROMETHEUS=true -e METRICS_PORT=":9090" \ -e EMBEDDING_DIMS=768 \ -v $(pwd)/data:/data \ mcp-memory-libsql-go:local -transport sse -addr :8080 -sse-endpoint /sse

• Docker Compose (single DB):

  docker compose --profile single up --build -d # SSE URL: http://localhost:8080/sse, Metrics: http://localhost:9090/healthz

• Docker Compose (multi-project, Ollama, hybrid):

  make prod # SSE URL: http://localhost:8081/sse, Metrics: http://localhost:9091/healthz

Architecture

The project follows a clean, modular architecture:

• main.go: Application entry point

• internal/apptype/: Core data structures and MCP type definitions

• internal/database/: Database client and logic using libSQL

• internal/server/: MCP server implementation

• internal/embeddings/: Embeddings Providers implementations

License

MIT