Vector Knowledge Base

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

[](https://www.python.org) [](https://fastapi.tiangolo.com) [](https://qdrant.tech) [](LICENSE)

[Features](#features) • [Quick Start](#quick-start) • [Usage](#usage) • [Architecture](#architecture) • [API Reference](#api-reference) • [Configuration](#configuration) • [MCP Integration](#mcp-integration-ai-agents) • [Troubleshooting](#troubleshooting) • [Full Technical Writeup](Docs/VectorKnowledgeBaseTechnicalReport.pdf)

---

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

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

1. Start all services with Docker Compose

``bash docker-compose up -d ``

1. 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

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

1. Run the backend natively

macOS/Linux: ``bash ./scripts/start-backend-native.sh ``

Windows: ``batch 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

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

1. Start Qdrant with Docker

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

1. Set up Python environment

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

1. Start the backend server

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

1. Start the frontend server

``bash cd frontend python -m http.server 8001 ``

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

1. 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

1. Add metadata (course name, document type, tags)
2. Click Upload
3. 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)

1. 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

1. 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)

1. 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
• Qdrant - High-performance vector database (Dockerized)
• SentenceTransformers - State-of-the-art embeddings
• SQLite - Lightweight metadata storage

Frontend:

• Vanilla JavaScript (ES6+ modules)
• Modular CSS architecture (7 organized stylesheets)
• Three.js for 3D embedding visualization
• Fetch API for backend communication

Extractor Architecture:

The application uses a factory pattern for modular file processing:

• ExtractorFactory - Routes files to appropriate extractors based on file extension
• BaseExtractor - Interface that all extractors implement with extract(file_path) → str method

Specialized Extractors:

• PDFExtractor - Uses pypdf for PDF text extraction
• DocxExtractor - Uses docx2txt for Word document parsing
• PptxExtractor - Uses python-pptx for PowerPoint presentations
• XlsxExtractor - Uses openpyxl for Excel spreadsheets with multi-sheet support
• CsvExtractor - Uses pandas for CSV file processing with configurable delimiters
• ImageExtractor - Uses pytesseract + PIL for OCR on images (.jpg, .jpeg, .png, .webp)
• TextExtractor - Handles plain text and Markdown files (.txt, .md)
• CodeExtractor - AST-aware parsing for Python code with function/class extraction
• CsExtractor - Dedicated C# file parsing with namespace and method detection

CSS Architecture

The frontend uses:

• base.css - CSS variables, reset, body, container
• animations.css - Keyframe animations and transitions
• components.css - Buttons, cards, forms, tables
• layout.css - Page-specific layouts
• filesystem.css - File manager UI
• batch-upload.css - Batch upload queue card and status indicators
• modals.css - Modal overlays and notifications

API Reference

Core Endpoints

Upload Document

POST /upload
Content-Type: multipart/form-data

Parameters:
- file: File (required)
- category: string (required)
- tags: string[] (optional)
- relative_path: string (optional) - Folder path for batch uploads (e.g., "projects/homework")

Response: {
  "filename": "doc.pdf",
  "chunks_count": 42,
  "document_id": "uuid"
}

Search

POST /search
Content-Type: application/json

Body: {
  "query": "What is semantic search?",
  "extension": ".pdf",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "limit": 10,
  "cluster_filter": "0"  // Optional: filter by cluster ID
}

Response: {
  "results": [
    {
      "text": "chunk content",
      "score": 0.89,
      "metadata": {
        "cluster": 0,
        ...
      }
    }
  ]
}

List Documents

GET /documents

Response: [
  {
    "filename": "doc.pdf",
    "category": "CS101",
    "upload_date": 1705320000.0
  }
]

Delete Document

DELETE /documents/{filename}

Response: {
  "message": "Document deleted successfully"
}

Folder Management

• GET /folders - List all folders
• POST /folders - Create folder
• PUT /folders/{id} - Update folder
• DELETE /folders/{id} - Delete empty folder
• POST /files/move - Move file to folder
• GET /files/unsorted - List unsorted files
• GET /files/in_folders - Get file-to-folder mappings
• GET /files/content/{filename} - Retrieve file content for viewing

Clustering

POST /api/cluster

Response: {
  "message": "Clustering complete",
  "total_documents": 150,
  "clusters": 5
}
# Automatically clusters all documents in the database
# Automatically determines optimal number of clusters using HDBSCAN density-based algorithm

GET /api/clusters

Response: {
  "clusters": [0, 1, 2, 3, 4]
}
# Returns list of all cluster IDs currently assigned to documents

3D Visualization

GET /api/embeddings/3d

Response: {
  "coords": [[x, y, z], ...],  // PCA-reduced 3D coordinates
  "point_ids": ["uuid1", ...],
  "metadata": [{"filename": "doc.pdf", ...}, ...]
}
# Returns 3D coordinates for all document chunks (cached for performance)

POST /api/embeddings/3d/query
Content-Type: application/json

Body: {
  "query": "machine learning",
  "k": 5  // Number of nearest neighbors
}

Response: {
  "query_coords": [x, y, z],
  "neighbors": [{"id": "uuid", "coords": [x, y, z], "score": 0.89}, ...]
}
# Transforms a search query to 3D space and finds nearest neighbors

Batch Upload

POST /upload-batch
Content-Type: multipart/form-data

Parameters:
- files: File[] (required) - Multiple files to upload
- category: string (required)
- tags: string[] (optional)
- relative_path: string (optional) - Shared folder path for all files

Resp

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [i3T4AN](https://github.com/i3T4AN)
- **Source:** [i3T4AN/Vector-Knowledge-Base](https://github.com/i3T4AN/Vector-Knowledge-Base)
- **License:** MIT

Install and usage instructions live in the source repository linked above.