MDDB Documentation

This directory contains the documentation for MDDB.

GitHub Pages

The documentation is published at: https://mddb.tradik.com/mddb/

Markdown Viewer

All .md files are automatically rendered using md-viewer.html, which uses:

  • marked.js - Markdown parser
  • github-markdown-css - GitHub-style rendering

Usage: md-viewer.html?doc=FILENAME.md

Example: https://mddb.tradik.com/mddb/md-viewer.html?doc=QUICKSTART.md

Welcome to the MDDB documentation! This guide will help you understand, deploy, and use MDDB effectively.

📖 Documentation Index

Documentation Index

Guides

  • Usage Examples - Practical examples and patterns

    • Basic operations
    • Advanced search queries
    • Export and backup
    • Shell scripts
    • Client libraries (Node.js, Python, Go)

  • Architecture Guide - System design and internals

    • High-level architecture
    • Storage layer details
    • Data flow diagrams
    • Design decisions
    • Performance characteristics
    • Scalability considerations

  • Deployment Guide - Production deployment

    • System requirements
    • Systemd service setup
    • Docker deployment
    • Reverse proxy configuration
    • Backup strategies
    • Monitoring and troubleshooting
    • Security hardening
    • Scaling strategies

🚀 Quick Links

For New Users

  1. Start with Quick Start Guide
  2. Try the examples in Usage Examples
  3. Read API Documentation for details

For Developers

  1. Understand the Architecture
  2. Review API Documentation
  3. Check Usage Examples for integration patterns

For DevOps

  1. Follow Deployment Guide
  2. Set up monitoring and backups
  3. Review security recommendations

📚 What is MDDB?

MDDB (Markdown Database) is an AI-native embedded document database for markdown content. Single ~29 MB binary, embedded BoltDB storage, zero external dependencies. Core capabilities at a glance (full list in FEATURES.md and the root README.md):

  • Triple protocol — HTTP/JSON REST, gRPC/Protobuf, GraphQL, all over TCP or Unix Domain Sockets
  • Built-in MCP server — 67 tools, MCP 2025-11-25 compliant, stdio + Streamable HTTP + SSE transports for Claude / Cursor / Windsurf / ChatGPT / Ollama / DeepSeek
  • Vector / semantic search — 7 index algorithms (Flat / HNSW / IVF / PQ / OPQ / SQ / BQ) with per-collection int8/int4 quantization; OpenAI / Ollama / Cohere / Voyage embeddings
  • Full-text search — TF-IDF / BM25 / BM25F / PMISparse, 7 modes (simple / boolean / phrase / wildcard / proximity / range / fuzzy), 18-language stemming, typo tolerance
  • Hybrid search — sparse BM25 + dense vector via alpha blending or Reciprocal Rank Fusion
  • Geosearch — R-tree + geohash radius / bounding-box queries, composable with FTS and vector
  • Memory RAG — conversational memory with session management and semantic recall
  • Multi-format upload — .md, .txt, .html, .pdf, .docx, .odt, .rtf, .tex, .yaml auto-converted to Markdown; URL import; Wikipedia XML dump streaming
  • Authentication — JWT, API keys, per-collection RBAC, per-protocol access modes
  • TLS / mTLS — built-in HTTPS with optional client certificate authentication
  • Replication — leader-follower binlog streaming for read scaling
  • Automation — triggers, crons, webhooks, sentiment analysis, template variables
  • Document TTL with auto-expiry, full revision history, schema validation, aggregations (facets + histograms)
  • Web Admin Panel — React UI for documents, users, search, geo, settings

🎯 Common Use Cases

Content Management

  • Blog posts and articles
  • Documentation systems
  • Knowledge bases
  • Static site generators

Multi-language Content

  • Internationalized websites
  • Multi-region documentation
  • Localized marketing content

Version Control

  • Content approval workflows
  • Change tracking
  • Audit trails
  • Point-in-time recovery

🔧 Key Features

The full feature matrix is maintained in FEATURES.md. Storage internals (buckets, data flow, design decisions) are in ARCHITECTURE.md. Don't duplicate them here.

📊 Performance

Numbers, methodology and benchmarks live in their own document — see BENCHMARK.md or run the bench suite under tools/bench/. This index intentionally does not pin throughput targets that would drift from reality.

🔒 Security

For the security model (the layers a request passes through, trust boundaries, what's deliberately out of scope) see the Security Model section in ARCHITECTURE.md. For practical setup:

Version-by-version changes for any of these layers live in CHANGELOG.md, not here.

🛠️ Development

Building from Source

git clone <repository-url>
cd mddb
make build

Running Tests

make test
make test-coverage

Development Mode

make install-dev-tools
make dev

Code Quality

make fmt # Format code
make lint # Run linter
make tidy # Tidy modules

📦 Installation Methods

Binary Release

Download from releases page and run:

./mddbd

Build from Source

make build
make run

Docker

docker run -p 11023:11023 -v mddb-data:/data mddb:latest

Docker Compose

docker-compose up -d

🤝 Contributing

Contributions are welcome! Please:

  1. Read the Architecture Guide
  2. Follow Go best practices
  3. Add tests for new features
  4. Update documentation
  5. Update CHANGELOG.md

Standards & References

This documentation follows industry standards:

  • RFC 2119 - Key words for use in RFCs to Indicate Requirement Levels

    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in our documentation are to be interpreted as described in RFC 2119.

📝 License

See LICENSE file for details.

🔗 Links

💡 Support

  • Check documentation first
  • Search existing issues
  • Open new issue with details
  • Include version and OS information

🗺️ Roadmap

The roadmap is maintained per release in ROADMAP.md. Past releases live in CHANGELOG.md.

Happy documenting with MDDB! 🚀