KektorDB

<a href="DOCUMENTATION.md">📚 Documentation</a> • <a href="CONTRIBUTING.md">🤝 Contributing</a> • <a href="docs/guides/zero_code_rag.md">🤖 RAG Open WebUI Guide</a>

English | Italiano

[!TIP] Docker Support: Prefer containers? A Dockerfile is included in the root for building your own images.

KektorDB is an embeddable, in-memory Vector + Graph database written in pure Go.

It fuses a robust HNSW Engine with a lightweight Semantic Graph, allowing you to combine vector similarity with explicit relationships (like parent, next, mentions) without the complexity and overhead of a full-blown Graph Database.

Built with the philosophy of SQLite: Serverless option, zero dependencies, and easy to manage.

Why KektorDB?

KektorDB simplifies the stack by unifying the Database, the Search Engine, and the AI Middleware into a single, dependency-free binary.

Database First: A robust, persistent (AOF+Snapshot) vector store with hybrid search (BM25 + Vector) and metadata filtering.
Embeddable Architecture: Designed to run alongside your application process (like SQLite) or as a lightweight microservice, removing network overhead.
Lightweight Graph Layer: Unlike flat vector stores, KektorDB understands connections. It provides a streamlined graph engine optimized for N-Hop traversal and Context Retrieval, bridging the gap between similarity and structure.

Use Cases

KektorDB is not designed to replace distributed clusters handling billions of vectors. Instead, it shines in specific, high-value scenarios:

1. Embedded Search for Go Applications

Ideal for developers building monoliths or microservices who need semantic search without the operational overhead of managing a distributed cluster.

Scenario: Implementing "Related Products" or "Semantic Search" in a Go backend.
Solution: import "github.com/sanonone/kektordb/pkg/engine" to run the DB in-process.
Benefit: Zero deployment complexity. The DB scales with your app.

2. Local RAG & Knowledge Base

Perfect for desktop applications, local AI agents, or private documentation search where data privacy is paramount.

Scenario: You need to index sensitive PDF/Markdown/Docx files and chat with them using local LLMs (Ollama).
Solution: Point KektorDB to your folder. It handles the full ingestion pipeline (OCR, chunking, linking).
Benefit: Setup time drops from days to minutes. No data leaves your machine.

3. AI Gateway & Semantic Cache

Acts as a smart proxy to optimize costs and latency for LLM applications.

Scenario: You are building a Chatbot using OpenAI/Anthropic APIs.
Solution: Use KektorDB as a middleware. It caches responses semantically (saving API costs) and acts as a firewall to block malicious prompts before they reach the LLM.
Benefit: Immediate performance boost and cost reduction with zero code changes in your client.

Zero-Code RAG (Open WebUI Integration)

KektorDB can function as a smart middleware between your Chat UI and your LLM. It intercepts requests, performs retrieval, and injects context automatically.

Architecture: Open WebUI -> KektorDB Proxy (9092) -> Ollama / LocalAI (11434)

How to set it up:

Configure vectorizers.yaml to point to your documents and enable Entity Extraction.
Configure proxy.yaml to point to your Local LLM (Ollama) or OpenAI.

Run KektorDB with the proxy enabled:

./kektordb -vectorizers-config='vectorizers.yaml' -enable-proxy -proxy-config='proxy.yaml'

Configure Open WebUI:
- Base URL: http://localhost:9092/v1
- API Key: kektor (or any string).
Chat: Just ask questions about your documents. KektorDB handles the rest.

👉 Read the Full Guide: Building a Fast RAG System with Open WebUI

✨ Core Features

Performance & Engineering

HNSW Engine: Custom implementation optimized for high-concurrency reading.
Hybrid Search: Combines Vector Similarity + BM25 (Keyword) + Metadata Filtering.
Memory Efficiency: Supports Int8 Quantization (75% RAM savings) with zero-shot auto-training and Float16.
Maintenance & Optimization:
- Vacuum: A background process that cleans up deleted nodes to reclaim memory and repair graph connections.
- Refine: An ongoing optimization that re-evaluates graph connections to improve search quality (recall) over time.
AI Gateway & Middleware: Acts as a smart proxy for OpenAI/Ollama compatible clients. Features Semantic Caching to serve instant responses for recurring queries and a Semantic Firewall to block malicious prompts based on vector similarity or explicit deny lists.
Lazy AOF Writer: Optimized write performance with batched flushing (10-100x throughput improvement) while maintaining durability.
Vision Support: Process images and PDFs with OCR capabilities using Vision LLM integration.
Persistence: Hybrid AOF + Snapshot ensures durability.
Observability: Prometheus metrics (/metrics), structured logging, and Go pprof profiling endpoints.
Dual Mode: Run as a standalone REST Server or as a Go Library.

Agentic RAG Pipeline

Query Rewriting (CQR): Automatically rewrites user questions based on chat history (e.g., "How to install it?" -> "How to install KektorDB?"). Solves short-term memory issues.
Grounded HyDe: Generates hypothetical answers to improve recall on vague queries, using real data fragments to ground the hallucination.
Safety Net: Automatically falls back to standard vector search if the advanced pipeline fails to find relevant context.

Semantic Graph Engine

Automated Entity Extraction: Uses a local LLM to identify concepts (People, Projects, Tech) during ingestion and links related documents together ("Connecting the dots").
Weighted & Property Graphs: Supports "Rich Edges" with attributes (weights, arbitrary properties) to enable complex recommendation and ranking algorithms.
Temporal Graph (Time Travel): Every relationship is versioned with CreatedAt and DeletedAt timestamps. Soft delete support allows querying the graph status at any point in the past.
Memory Decay & Reinforcement: Short and long-term memory is unified. Nodes decay in relevance over time if not accessed, but are reinforced via retrieving/reinforcing APIs, optimizing Context/RAG to auto-clean noise. Includes support for pinned nodes that bypass decay.
Bi-directional Navigation: Automatic management of incoming edges to enable O(1) retrieval of "who points to node X", powering efficient graph traversal.
Graph Entities: Support for nodes without vectors (pure metadata nodes) to represent abstract entities like "Users" or "Categories" within the same graph structure.
Graph Traversal: Search traverses any relationship type (like prev, next, parent, mentions) to provide a holistic context window.
Graph Filtering: Combine vector search with graph topology filters (e.g. "search only children of Doc X"), powered by Roaring Bitmaps.
Path Finding (FindPath): Discover shortest paths between any two nodes using bidirectional BFS. Supports time travel queries to find paths that existed at a specific point in history.
Node Search: Perform pure metadata filtering without vector similarity (useful for finding nodes by property).

<img src="docs/images/kektordb-graph-entities.png" alt="Knowledge Graph Visualization" width="700"> Visualizing semantic connections between documents via extracted entities.

Model Context Protocol (MCP) Support

KektorDB now functions as an MCP Memory Server. This allows LLMs (like Claude via Claude Desktop) to use KektorDB as a long-term memory store directly.

Tools included: save_memory, recall_memory, create_entity, connect_entities, scoped_recall, and explore_connections.
How to run:
```
./kektordb --mcp
```
Integration: Add KektorDB to your MCP client configuration using the --mcp flag.

Embedded Dashboard

Available at http://localhost:9091/ui/.

Graph Explorer: Visualize your knowledge graph with a force-directed layout.
Search Debugger: Test your queries and see exactly why a document was retrieved.

Installation

As a Server (Docker)

docker run -p 9091:9091 -p 9092:9092 -v $(pwd)/data:/data sanonone/kektordb:latest

As a Server (Binary)

Download the pre-compiled binary from the Releases page.

# Linux/macOS
./kektordb

# With custom options
./kektordb -http-addr :9091 -save "30 500" -log-level debug

Command-line flags:

-http-addr: HTTP server address (default: `:9

Kektordb

Install / Use

README