AI-native document database with built-in MCP server, file upload (PDF/DOCX/HTML/ODT/RTF/TEX/YAML/Wikipedia XML→Markdown), vector search, RAG pipelines, and 67 MCP tools. Plugs directly into Claude, ChatGPT, Cursor, Windsurf, and any MCP-compatible agent.

MDDB is a document database purpose-built for AI agents and LLM workflows. Upload files (PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT) — they're auto-converted to Markdown and embedded for semantic search. Expose everything to AI agents via 67 built-in MCP tools. Integrates with Docling, Langflow, OpenSearch, SSG, wpexporter, and Airbyte for production pipelines. Single ~29MB binary, zero configuration, BoltDB embedded storage, triple-protocol APIs (HTTP + gRPC + GraphQL).

MDDB gives your AI agents a persistent, searchable knowledge base:

• File Upload - Upload PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT files — auto-converted to Markdown and indexed
• Wikipedia Import - Stream and import MediaWiki XML dumps (.xml.bz2) — wikitext auto-converted to Markdown, namespace filtering, handles multi-GB files
• Built-in MCP Server - 67 tools for Claude Desktop, Cursor, Windsurf, or any MCP client
• Vector Search - Auto-embed documents, semantic similarity with 7 index algorithms (Flat, HNSW, IVF, PQ, OPQ, SQ, BQ) + per-collection quantization (int8/int4) + ARM NEON/SME hardware acceleration + goroutine parallel search
• Geo Search - R-tree and geohash indexes for radius/bounding-box queries, composable with FTS/vector via hybrid-search, optional postcode lookup
• RAG-Ready - Hybrid search (BM25 + vector) for retrieval-augmented generation
• Memory RAG - Conversational memory system: store, recall, and summarize chat sessions with semantic search
• Integrations - Docling, Langflow, OpenSearch, SSG, wpexporter, Airbyte for production pipelines
• Zero-Shot Classification — Classify documents against candidate labels using embeddings, no training data
• Custom AI Tools - Define YAML-based MCP tools for domain-specific workflows
• Full-Text Search - Built-in inverted index with TF-IDF, BM25, BM25F, PMISparse, 8 search modes (simple, boolean, phrase, wildcard, proximity, expression, range, fuzzy), typo tolerance, multi-language stemming (18 languages), synonyms, per-query metadata boost/demote, prefix autocomplete, search-result highlighting with fragments
• Geosearch - R-tree + geohash radius/bbox queries, GeoJSON polygon and multi-polygon containment, postcode lookup, distance-sorted hybrid search combining proximity with keyword/vector relevance
• Async Bulk Ingest - Queue long-running document imports with job tracking, progress polling, and optional webhook callback
• Full Revision History - Every update creates a new revision with complete snapshots
• Multi-Protocol APIs - HTTP/JSON (easy), gRPC (fast), GraphQL (flexible), and WebSocket streaming via mddb-chat for LLM chat pipelines
• Automation - Triggers, crons, webhooks with template variables and sentiment analysis
• Real-Time Events - Server-Sent Events (SSE) for live document change notifications
• MCP Transports - Streamable HTTP (/mcp, 2025-11-25), legacy SSE (/sse), and stdio
• Built-in TLS - Native HTTPS support, connection pooling, pprof profiling
• Zero Configuration - Single ~29MB binary, embedded database, no dependencies

Perfect for: AI agent memory, RAG pipelines, knowledge bases for LLMs, documentation chatbots, semantic search APIs, document processing (PDF/DOCX→Markdown), static site generation, WordPress migration

Start all services with one command:

git clone https://github.com/tradik/mddb.git
cd mddb

# Production mode (all services)
docker compose up -d

# Development mode (with hot reload)
make dev-start

# Development + Ollama for embeddings
make dev-start-with-ollama

Services started:

MDDB has a built-in MCP server — no extra service needed. Add to your MCP config:

{
  "mcpServers": {
    "mddb": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "-v", "mddb-data:/app/data",
        "-e", "MDDB_MCP_STDIO=true",
        "tradik/mddb:latest"
      ]
    }
  }
}

That's it — your AI agent now has full access to your knowledge base with 67 built-in tools (add, search, vector search, classify, and more).

→ Full MCP setup guide | → MCP server config | → Custom MCP tools

# MDDB Server only
docker run -d --name mddb \
  -p 11023:11023 -p 11024:11024 -p 9000:9000 \
  -v mddb-data:/data \
  tradik/mddb:latest

# Web Panel (connect to existing server)
docker run -d --name mddb-panel \
  -p 3000:3000 \
  -e VITE_MDDB_SERVER=host.docker.internal:11023 \
  tradik/mddb:panel

# MCP stdio mode (for Claude Desktop, Windsurf, etc.)
docker run -i --rm --network host \
  -v mddb-data:/app/data \
  -e MDDB_MCP_STDIO=true \
  tradik/mddb:latest

# Test it
curl http://localhost:11023/health

Docker Hub: https://hub.docker.com/r/tradik/mddb

Linux (Debian/Ubuntu):

wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-linux-amd64.deb
sudo dpkg -i mddbd-latest-linux-amd64.deb
sudo systemctl start mddbd

macOS (Apple Silicon):

wget https://github.com/tradik/mddb/releases/latest/download/mddbd-latest-darwin-arm64.tar.gz
tar xzf mddbd-latest-darwin-arm64.tar.gz
sudo mv mddbd-latest-darwin-arm64/mddbd /usr/local/bin/
mddbd

CLI Client:

# Linux
wget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-linux-amd64.deb
sudo dpkg -i mddb-cli-latest-linux-amd64.deb

# Usage
mddb-cli stats
mddb-cli add blog hello en_US -f post.md
mddb-cli search blog -f "tags=tutorial"
mddb-cli fts blog --query="getting started" --algorithm=bm25

Other platforms: See Installation Guide

git clone https://github.com/tradik/mddb.git
cd mddb
make build
./services/mddbd/mddbd

MDDB is a Go monorepo with multiple modules (services/mddbd, services/mddb-cli, tools/bench). A go.work file at the repo root enables Go workspace mode for local development:

• Cross-module refactoring — renaming a symbol in services/mddbd immediately updates references in services/mddb-cli via gopls.
• Unified build — go build ./services/mddbd/... ./services/mddb-cli/... ./tools/bench/... from the repo root.
• IDE "goto definition" works across module boundaries without opening each module separately.

CI runs in module-isolation mode (GOWORK=off in .github/workflows/test.yml and release.yml) so each module builds and tests independently. This catches missing require entries that workspace mode would transparently resolve from sibling modules.

To use the same mode locally for debugging:

GOWORK=off go build ./...   # from inside services/mddbd

Regenerating protos (buf generate) and Docker builds are unaffected by go.work — they operate on individual modules.

MDDB ships as a monorepo with multiple packages:

Zero-dependency HTTP clients - copy a single file into your project:

PHP:

require_once 'mddb.php';
$db = mddb::connect('localhost:11023', 'write');
$db->collection('blog')->add('hello', 'en_US', ['author' => ['John']], '# Hello');
$results = $db->collection('blog')->vectorSearch('cancel subscription', 5, 0.7);

Python:

from mddb import MDDB
db = MDDB.connect('localhost:11023', 'write').collection('blog')
db.add('hello', 'en_US', {'author': ['John']}, '# Hello')
results = db.vector_search('cancel subscription', top_k=5)

High-performance clients generated from Protocol Buffers:

Proto definitions at proto/mddb.proto - generate clients for any language supported by protobuf.

• ✅ MCP Server - 67 built-in tools via Model Context Protocol 2025-11-25 (stdio + Streamable HTTP + SSE) with tool annotations, prompts, completion, and structured output
• ✅ File Upload - Upload PDF, DOCX, HTML, ODT, RTF, TEX, YAML, TXT — auto-converted to Markdown (single and batch, configurable size limit)
• ✅ Wikipedia Import - Stream MediaWiki XML dumps (.xml.bz2) with wikitext→Markdown conversion, namespace filtering, batch processing
• ✅ Vector Search - Semantic similarity with auto-embeddings (OpenAI, Ollama, Cohere, Voyage), ARM NEON/SME SIMD acceleration
• ✅ Full-Text Search - Built-in inverted index with TF-IDF, BM25, BM25F, PMISparse scoring, 7 search modes (simple, boolean, phrase, wildcard, proximity, range, fuzzy), typo tolerance, metadata pre-filtering, multi-language stemming and stop words (18 languages)
• ✅ Hybrid Search - Sparse (BM25) + dense (vector) fusion with alpha blending or RRF
• ✅ Aggregations - Metadata facets (value counts) and date histograms with optional pre-filtering
• ✅ Inline Facets on Search (v2.9.14+) - Pass facetBy to /v1/fts or /v1/hybrid-search and get per-key value counts alongside results — no separate aggregate call
• ✅ Curation Rules (v2.9.14+) - Pin or hide documents for specific queries via /v1/curation (CRUD). Inspired by Typesense; applied in FTS + Hybrid pipelines
• ✅ Zero-Shot Classification - Classify documents against candidate labels using embedding similarity
• ✅ Custom MCP Tools - Define YAML-based AI tools for domain-specific workflows
• ✅ RAG Pipeline - Built-in support for retrieval-augmented generation workflows
• ✅ Integrations - Docling, Langflow, OpenSearch, SSG, wpexporter, Airbyte (guide)

• ✅ Document Management - Full CRUD with metadata and collections
• ✅ Revision History - Complete version control with snapshots, per-collection retention cap (maxRevisions, v2.9.14+) trimmed synchronously on every write
• ✅ Metadata Search - Fast indexed queries with multi-value tags
• ✅ Collection Checksum - Lightweight CRC32 checksum per collection for cache invalidation
• ✅ Partial Document Update - Update metadata and/or content independently
• ✅ Document TTL - Time-to-live with automatic cleanup
• ✅ Temporal Tracking - Document event history (create/update/access), hot-docs leaderboard, activity histograms (env MDDB_TEMPORAL=true)
• ✅ Spell Correction - SymSpell-based FTS spell suggestions, text cleanup, per-collection custom dictionaries (env MDDB_SPELL=true)
• ✅ Automation - Triggers, crons, webhooks with template variables, sentiment analysis, execution logs
• ✅ Multi-language - Same key, multiple languages
• ✅ Schema Validation - JSON Schema validation per collection
• ✅ Per-Collection Storage Backends - Choose BoltDB (default), in-memory (ephemeral), or S3/MinIO per collection

• ✅ HTTP/JSON REST - Easy debugging, extensive docs
• ✅ gRPC/Protobuf - 16x faster, 70% smaller payload
• ✅ GraphQL - Flexible queries, schema introspection, Playground
• ✅ CLI Client - Full-featured command-line with GraphQL support
• ✅ Web Panel - React UI with REST/GraphQL toggle

• ✅ Authentication - JWT tokens and API keys
• ✅ Authorization - Collection-level RBAC (Read/Write/Admin)
• ✅ Per-Protocol Access Modes - MDDB_MCP_MODE=read (MCP read-only), MDDB_API_MODE, MDDB_GRPC_MODE, MDDB_HTTP3_MODE
• ✅ MCP Tool Control - MDDB_MCP_BUILTIN_TOOLS=false to expose only custom YAML tools
• ✅ User Management - Multi-user with admin roles
• ✅ Group Permissions - Organize users into groups
• ✅ TLS / HTTPS - MDDB_TLS_ENABLED=true, MDDB_TLS_CERT, MDDB_TLS_KEY — user-supplied PEM cert + key, TLS 1.2 minimum
• ✅ Mutual TLS (mTLS) - MDDB_TLS_CLIENT_CA points to a PEM bundle of trusted client CAs; MDDB_TLS_CLIENT_AUTH=require (default) or request. Rejects unauthenticated clients when require
• ✅ Unix Domain Socket transport - MDDB_HTTP_ADDR=unix:/tmp/mddb-http.sock and MDDB_GRPC_ADDR=unix:/tmp/mddb-grpc.sock — zero-network local transport with 0600 filesystem perms. Clients in Python (MDDB.connect('unix:/tmp/mddb-http.sock')), PHP (mddb::connect('unix:/tmp/mddb-http.sock')), Node/Python gRPC (unix:/tmp/mddb-grpc.sock channel target)
• ✅ Audit log (ISO 27001 / SOC 2) — MDDB_AUDIT_ENABLED=true persists structured JSON events (auth attempts, writes, deletes) to a dedicated BoltDB bucket. Admin-only GET /v1/audit query with actor / action / result / time-window filters. Retention configurable via MDDB_AUDIT_RETENTION_DAYS (default 90)
• ✅ Incident webhook events — subscribe on /v1/webhooks to security.auth_failure_burst, security.rate_limit_exceeded, ops.replication_lag_high, ops.panic_recovered, ops.disk_usage_high. Panic-recovery middleware turns handler crashes into structured 500 + event instead of process kill
• ✅ At-rest encryption (opt-in per collection) — AES-256-GCM on document values. Enable globally with MDDB_ENCRYPTION_KEY (32 B base64) and flip CollectionConfig.encrypted=true per collection. Legacy plaintext stays readable after flip. FTS / vector indexes remain plaintext (queryable). Losing the key is terminal — store in HSM + escrow
• ✅ Encryption key rotation (2.9.16) — V2 ciphertext format prefixes the keyID byte so the encryptor can hold a primary plus any number of read-only previous keys. Rotate by setting a fresh MDDB_ENCRYPTION_KEY + MDDB_ENCRYPTION_KEY_ID and listing every superseded key in MDDB_ENCRYPTION_KEYS_PREVIOUS (JSON [{"id":1,"key":"..."}]). Old documents stay readable; the admin endpoint POST /v1/encryption/rotate (or panel "Encryption" → "Start rotation") rewrites every encrypted entry under the new primary in the background. V1 (2.9.15) ciphertexts continue to decrypt — non-breaking
• ✅ Audit log export to SIEM / syslog (2.9.16) — MDDB_AUDIT_EXPORT_WEBHOOK_URL mirrors every audit event as JSON to a SIEM (Splunk HEC, Datadog Logs, ELK) with custom auth headers from MDDB_AUDIT_EXPORT_WEBHOOK_HEADER. MDDB_AUDIT_EXPORT_SYSLOG_ADDR=host:port (or tcp://host:port) sends RFC 5424 framed messages to a syslog collector. Both can run together. Per-sink delivered/failed/dropped counters at GET /v1/audit/exporters and in the Security panel
• ✅ HTTP + gRPC rate limiting — MDDB_RATE_LIMIT_ENABLED=true enforces a single sliding-window budget across both transports (per-IP by default, MDDB_RATE_LIMIT_BY=user keys on authenticated username). Emits X-RateLimit-* headers + 429 Retry-After on HTTP; ResourceExhausted on gRPC. Health / metrics endpoints are always exempt
• ✅ Production hardening switch — MDDB_PRODUCTION=true fails startup unless every compliance guardrail is satisfied (auth on, JWT secret ≥32 bytes, TLS on, CORS explicit, audit + rate limit enabled). Unset = silent warning; no breaking change for existing deployments. → Details

→ Full compliance map, threat model, operational checklist

• ✅ Leader-Follower Replication - Binlog streaming for read scaling
• ✅ Automatic Catch-up - Followers pull missing transactions
• ✅ Zero-Downtime Snapshots - Full sync for new followers
• ✅ Cluster Monitoring - Web panel with health and lag metrics

→ See all features | → Compare with alternatives | → Performance benchmarks

MDDB supports leader-follower replication allowing you to scale read operations horizontally.

graph LR
    C[Clients] -->|Writes/Reads| L[Leader]
    C -->|Reads| F1[Follower 1]
    C -->|Reads| F2[Follower 2]
    L -->|gRPC StreamBinlog| F1
    L -->|gRPC StreamBinlog| F2

• Leader: Handles writes, maintains changes in a binary log, and streams them via gRPC.
• Followers: Read-only, pulls transactions, reconnects automatically.

→ Read Full Replication Guide

Modern React-based UI for managing documents, users, and search with REST/GraphQL API toggle.

Features: Browse collections, view/edit documents, vector search, user management, API mode switching (REST ↔ GraphQL), live markdown preview.

→ Panel documentation

# Upload a PDF — auto-converted to Markdown
curl -X POST http://localhost:11023/v1/upload \
  -F "file=@report.pdf" \
  -F "collection=docs" \
  -F "lang=en_US"

# Upload with custom key and metadata
curl -X POST http://localhost:11023/v1/upload \
  -F "file=@manual.docx" \
  -F "collection=docs" \
  -F "key=user-manual" \
  -F "lang=en_US" \
  -F 'meta={"category":["documentation"]}'

# Batch upload multiple files
curl -X POST http://localhost:11023/v1/upload \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.html" \
  -F "files[]=@doc3.txt" \
  -F "collection=docs" \
  -F "lang=en_US"

# Add a document
curl -X POST http://localhost:11023/v1/add \
  -H 'Content-Type: application/json' \
  -d '{
    "collection": "blog",
    "key": "hello-world",
    "lang": "en_US",
    "meta": {"author": ["John"], "tags": ["tutorial"]},
    "contentMd": "# Hello World\n\nWelcome to MDDB!"
  }'

# Get document
curl -X POST http://localhost:11023/v1/get \
  -H 'Content-Type: application/json' \
  -d '{"collection": "blog", "key": "hello-world", "lang": "en_US"}'

# Search by metadata
curl -X POST http://localhost:11023/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"collection": "blog", "filterMeta": {"tags": ["tutorial"]}, "limit": 10}'

# Documents auto-embedded in background
# Search by meaning, not keywords
curl -X POST http://localhost:11023/v1/vector-search \
  -H 'Content-Type: application/json' \
  -d '{
    "collection": "kb",
    "query": "how do I cancel my subscription?",
    "topK": 5,
    "threshold": 0.7,
    "includeContent": true
  }'

Combine keyword (BM25/BM25F) and semantic (vector) search in a single query. Two merge strategies:

• Alpha Blending: combined = (1-a) * BM25_score + a * vector_score -- configurable weight
• RRF (Reciprocal Rank Fusion): rank-based fusion that is robust to different score distributions

curl -X POST http://localhost:11023/v1/hybrid-search \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "docs",
    "query": "machine learning",
    "topK": 10,
    "strategy": "alpha",
    "alpha": 0.5
  }'

FTS supports simple, boolean, phrase, wildcard, proximity, range, and fuzzy modes with auto-detection:

# Simple search with metadata pre-filtering
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "getting started",
    "limit": 10,
    "algorithm": "bm25",
    "filterMeta": {"category": ["tutorial"]}
  }'

# Boolean search (AND, OR, NOT, +required, -excluded)
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "rust AND performance NOT garbage",
    "mode": "boolean"
  }'

# Phrase search (exact sequence)
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "\"machine learning\"",
    "mode": "phrase"
  }'

# Proximity search (terms within N words)
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "\"database performance\"~5",
    "mode": "proximity",
    "distance": 5
  }'

# Enable GraphQL
docker run -e MDDB_GRAPHQL_ENABLED=true -p 11023:11023 tradik/mddb

# Query
curl -X POST http://localhost:11023/graphql \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ document(collection: \"blog\", key: \"hello-world\", lang: \"en\") { contentMd meta } }"
  }'

# Interactive Playground
open http://localhost:11023/playground

# Install CLI
wget https://github.com/tradik/mddb/releases/latest/download/mddb-cli-latest-linux-amd64.deb
sudo dpkg -i mddb-cli-latest-linux-amd64.deb

# Use CLI
mddb-cli add blog hello en_US -f post.md -m "author=John,tags=tutorial"
mddb-cli get blog hello en_US
mddb-cli search blog -f "tags=tutorial"
mddb-cli fts blog --query="getting started"
mddb-cli stats

→ More examples | → Use case examples | → Client libraries

🌐 Official Website - Complete documentation, downloads, examples

• Quick Start Guide - 5-minute setup
• Installation Guide - All platforms (Linux, macOS, FreeBSD, Windows)
• Use Cases - Real-world examples

• HTTP/JSON API - Complete REST API reference
• gRPC API - High-performance protocol guide
• GraphQL API - Flexible query language
• OpenAPI/Swagger - Machine-readable spec
• Swagger UI - Interactive API docs

• Vector Search - Semantic search setup (OpenAI, Cohere, Voyage, Ollama)
• RAG Pipeline - Complete RAG implementation guide
• Search Algorithms - TF-IDF, BM25, BM25F, PMISparse, Flat, HNSW, IVF, PQ, SQ, BQ
• Vector Quantization - Per-collection int8/int4 scalar quantization (4-8x compression)
• Server-Sent Events - Real-time document change notifications with auth and rate limiting
• Full-Text Search - Built-in inverted index with multi-language support
• Zero-Shot Classification - Classify documents against labels using embeddings
• PMISparse - Two-phase BM25 + PPMI query expansion (invented by Tradik Limited)
• Webhooks - Event-driven integration
• Automations - Triggers, crons, webhooks, sentiment, template variables
• Temporal Tracking - Document event history, hot-docs leaderboard, activity histograms
• Spell Correction - SymSpell FTS spell suggestions, text cleanup, custom dictionaries
• Authentication - JWT & API keys, RBAC
• Web Panel - Admin UI guide
• LLM Connections - MCP for Claude, ChatGPT, Ollama, DeepSeek
• Integrations - Docling, Langflow, OpenSearch, SSG, wpexporter, Airbyte
• Bulk Import - Load markdown folders

• Docker Guide - Container deployment
• Deployment - Production setup
• Telemetry - Prometheus metrics, Grafana
• Health Checks - Docker & Kubernetes
• Performance - Benchmarks & tuning
• Architecture - System design

• Client Libraries - PHP, Python, Go, Node.js
• Custom MCP Tools - YAML-defined AI tools
• Examples - Code samples
• Contributing - Development guide
• Changelog - Version history

┌─────────────────────────────────────────────────────┐
│     AI Agents (Claude, ChatGPT, Cursor, Windsurf)   │
│     ↕ MCP (stdio / HTTP :9000)                      │
├─────────────────────────────────────────────────────┤
│         Other Clients                               │
├──────────┬──────────┬──────────┬────────────────────┤
│HTTP/JSON │gRPC/Proto│ GraphQL  │ HTTP/3             │
│  :11023  │  :11024  │ /graphql │ :11443             │
├──────────┴──────────┴──────────┴────────────────────┤
│           MDDB Server (Go)                          │
│  • File Upload (PDF/DOCX/HTML/TXT → Markdown)       │
│  • Auto-Embeddings (OpenAI, Ollama, Cohere, Voyage) │
│  • Vector + Full-Text + Hybrid Search               │
│  • Zero-Shot Classification                         │
│  • Automation (triggers, crons, webhooks)            │
│  • JWT Auth + RBAC                                  │
├─────────────────────────────────────────────────────┤
│      BoltDB (Embedded ACID Storage)                 │
│  • B+Tree index • Single-file • MVCC transactions   │
└─────────────────────────────────────────────────────┘

→ Detailed architecture

→ Full roadmap

Contributions welcome! See CONTRIBUTING.md for guidelines.

Security issues: See SECURITY.md

BSD 3-Clause License - see LICENSE

• GitHub - Source code
• Docker Hub - Container images
• Releases - Download binaries
• Documentation - Full docs
• LLM Connections - Claude, ChatGPT, Ollama, DeepSeek, Manus, Bielik.ai
• Issues - Bug reports