Vector Knowledge Base

A personal semantic search engine for your documents and knowledge base

Zenodo: https://zenodo.org/records/18831091

DOI: https://doi.org/10.5281/zenodo.18831090

Features • Quick Start • Usage • Architecture • API Reference • Configuration • MCP Integration • Troubleshooting • Full Technical Writeup

---

Vector Knowledge Base is a vector database application that transforms your documents into a searchable knowledge base using semantic search. Upload PDFs, Word documents, PowerPoint, Excel, images (with OCR), and code files, then search using natural language to find exactly what you need.

Features

• Semantic Search - Find documents by meaning, not just keywords
• Auto-Clustering - Automatically organize documents into semantic clusters using HDBSCAN (density-based clustering)
• Semantic Cluster Naming - Clusters are automatically named using TF-IDF keyword extraction (e.g., "Shakespeare & Drama", "Python & Programming")
• Cluster-Based Filtering - Filter search results by document clusters for more focused searches
• Batch Upload & Folder Preservation - Drag and drop entire folders to upload, automatically preserving folder structure in your knowledge base
• 3D Embedding Visualization - Interactive 3D visualization of your document embeddings using Three.js
• Multi-Format Support - PDF, DOCX, PPTX, XLSX, CSV, images (OCR), TXT, Markdown, and code files (Python, JavaScript, C#, etc.)
• Intelligent Chunking - AST-aware parsing for code, sentence-boundary awareness for prose
• Folder Organization - Drag-and-drop file management with custom folder hierarchy
• File Viewer - Double-click any file to preview it directly in the browser
• Multi-Page Navigation - Dedicated pages for search, documents, and file management
• Data Management - Export all data as ZIP or reset the entire database with one click
• Modern UI - Clean, responsive interface with dark mode and modular CSS architecture
• Vector Embeddings - Powered by SentenceTransformers (all-mpnet-base-v2, 768-dimensional embeddings)
• High-Performance Search - Qdrant vector database for sub-50ms search queries
• O(1) Document Listing - JSON-based document registry for instant document listing at any scale
• AI Agent Integration (MCP) - Connect Claude Desktop or other AI agents to search, create, and manage documents via Model Context Protocol

Clean, modern dark-mode interface with semantic search and filtering options

Quick Start

Prerequisites

• Docker and Docker Compose (recommended)
• OR Python 3.11+ and Docker (for Performance Mode or Manual Installation)

Option 1: Docker Deployment (Recommended)

The easiest way to run the entire application:

1. Clone the repository

   git clone https://github.com/i3T4AN/Vector-Knowledge-Base.git
   cd Vector-Knowledge-Base
   

2. Start all services with Docker Compose

   docker-compose up -d
   

3. Open your browser

   Navigate to http://localhost:8001/index.html

That's it! Docker Compose will automatically:

• Start Qdrant vector database
• Build and start the backend API
• Start the frontend server with Nginx

[!TIP] On first run, the embedding model (~400MB) will be downloaded automatically. This may take a few minutes.

Managing the application:

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Rebuild after code changes
docker-compose up -d --build

Option 2: Performance Mode (GPU Acceleration)

For significantly faster embedding generation, run the backend natively with GPU support:

| Mode | Embedding Speed | Best For | |------|----------------|----------| | Docker (CPU) | ~18s per batch | Cross-platform compatibility | | Native (Apple M1/M2/M3) | ~3s per batch (6x faster) | Mac with Apple Silicon | | Native (NVIDIA CUDA) | ~1s per batch (18x faster) | Windows/Linux with NVIDIA GPU |

Setup:

1. Start Qdrant and Frontend in Docker

   docker-compose -f docker-compose.native.yml up -d
   # Or simply:
   docker-compose up -d qdrant frontend
   

2. Run the backend natively

   macOS/Linux:

   ./scripts/start-backend-native.sh
   

   Windows:

   scripts\start-backend-native.bat
   

The script will:

• Create a virtual environment
• Install dependencies
• Auto-detect your GPU (MPS for Apple Silicon, CUDA for NVIDIA)
• Start the backend with GPU acceleration

[!NOTE] GPU acceleration requires PyTorch with MPS support (macOS 12.3+) or CUDA toolkit (Windows/Linux with NVIDIA).

Deployment Options Summary:

| Mode | Command | GPU | Speed | Use Case | |------|---------|-----|-------|----------| | Full Docker | docker-compose up -d | ❌ | ~18s/batch | Production, cross-platform | | Native (Mac/Linux) | ./scripts/start-backend-native.sh | ✅ | ~1-3s/batch | Development, large uploads | | Native (Windows) | scripts\start-backend-native.bat | ✅ | ~1-3s/batch | Development, large uploads |

Option 3: Manual Installation (Not Recommended)

For development or if you prefer not to use Docker for the backend:

1. Clone the repository

   git clone https://github.com/i3T4AN/Vector-Knowledge-Base.git
   cd Vector-Knowledge-Base
   

2. Start Qdrant with Docker

   docker run -d -p 6333:6333 -v ./qdrant_storage:/qdrant/storage:z qdrant/qdrant
   

3. Set up Python environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   python -m pip install -r requirements.txt
   

4. Start the backend server

   cd backend
   python -m uvicorn main:app --reload --port 8000 --host 0.0.0.0
   

5. Start the frontend server

   cd frontend
   python -m http.server 8001
   

   [!NOTE] On Mac, use python3 instead of python if the command is not found.

6. Open your browser

   Navigate to http://localhost:8001/index.html

[!TIP] On first run, the embedding model (~400MB) will be downloaded automatically. This may take a few minutes.

Usage

Uploading Documents

1. Navigate to the My Documents page (documents.html)
2. Drag and drop files or click to browse
   • Batch Upload: Drop entire folders to upload multiple files at once
   • Folder Preservation: Folder structure is automatically maintained in the "Files" tab
3. Add metadata (course name, document type, tags)
4. Click Upload
5. Monitor progress in the Queue card for batch uploads

The backend will:

• Extract text from your files
• Split content into intelligent chunks
• Generate vector embeddings
• Store in Qdrant for fast retrieval
• Organize files in folders matching your source structure

Upload interface with drag-and-drop support, batch queue, and document management

Searching

1. Navigate to the Search page (index.html)
2. Enter your query in natural language
3. Optionally filter by:
   • Cluster - Filter results by document cluster (requires clustering first)
   • Date range - Filter by upload date
   • Result limit - Number of results to display (5, 10, or 20)
4. Click Search to see ranked results with similarity scores

Semantic search results showing similarity scores and relevant text snippets

Auto-Clustering Documents

1. Navigate to the Search page (index.html)
2. Upload several documents first (clustering works best with 5+ documents)
3. Click Auto-Cluster Documents
4. The system will:
   • Automatically determine the optimal number of clusters using HDBSCAN
   • Group similar documents together using density-based clustering
   • Generate semantic names for each cluster (e.g., "Python & Programming")
   • Update document metadata with cluster assignments and names
5. Use the Cluster filter to search within specific document groups (shown as "ID: Cluster Name")

Interactive 3D embedding space showing document clusters and search results with cluster information

Organizing Files

Use the Files page (files.html) to:

• Create custom folders
• Drag files between folders
• View unsorted files in the sidebar
• Navigate with breadcrumb navigation
• Double-click any file to open it in the built-in file viewer

File management interface with folder hierarchy and drag-and-drop organization

Data Management

In the My Documents tab, you can:

• Export Data - Download all uploaded files as a ZIP archive for backup
• Delete Data - Reset the entire database (requires confirmation)
  • Clears all vector embeddings from Qdrant
  • Removes all folder organization
  • Deletes all uploaded files
  • This action is irreversible

3D Visualization

1. Navigate to the Search page (index.html)
2. Click Show 3D Embedding Space to reveal the interactive visualization
3. Explore your document corpus in 3D space
4. Enter a search query to see:
   • Your query point highlighted in gold
   • Top matching documents connected with colored lines
   • Line colors indicating similarity (green = high, red = low)
5. Hover over points to see document details

Architecture

System Overview

┌─────────────┐
│   Frontend  │  Multi-Page Application
│  (Port 8001)│  index.html, documents.html, files.html
└──────┬──────┘
       │ HTTP
       ▼
┌─────────────┐     ┌─────────────┐
│   Backend   │ ←── │  MCP Server │  AI Agent Integration
│  (Port 8000)│     │  (/mcp)     │  (Claude Desktop, etc.)
└──────┬──────┘     └─────────────┘
       │
   ┌───┴────┬────────────┐
   ▼        ▼            ▼
┌──────┐ ┌──────┐ ┌──────────┐
│SQLite│ │Qdrant│ │Sentence  │
│(Meta)│ │(Vec) │ │Transform │
└──────┘ └──────┘ └──────────┘
         Port 6333

Document Processing Pipeline

┌──────────┐    ┌───────────┐    ┌─────────┐    ┌──────────┐    ┌────────┐
│  Upload  │ -> │ Extractor │ -> │ Chunker │ -> │ Embedder │ -> │ Qdrant │
│  (File)  │    │  (Text)   │    │ (Chunks)│    │(Vectors) │    │ (Store)│
└──────────┘    └───────────┘    └─────────┘    └──────────┘    └────────┘

How Chunks Relate to Documents:

• Each uploaded file is processed by the appropriate Extractor to extract raw text
• The Chunker splits the text into smaller pieces (default: 500 tokens with 50-token overlap)
• Each chunk is converted to a 768-dimensional vector by the Embedder (SentenceTransformers)
• Chunks are stored in Qdrant with metadata linking them back to the original document
• A single document may produce 10-100+ chunks depending on its length
• Search queries match against individual chunks, but results show which document they came from

Frontend Architecture

Multi-Page Application (MPA):

• index.html - Search interface with 3D visualization
• documents.html - Document upload and management
• files.html - File organization with drag-and-drop

Pages communicate with the backend API and share a modular CSS architecture.

Tech Stack

Backend:

• FastAPI - Modern async web framework
• Qd