NoteDiscovery is a self-hosted knowledge base designed for privacy-conscious users, developers, and knowledge workers who want complete ownership of their notes. It eliminates vendor lock-in by storing notes as plain markdown files in local folders, offering a fast, beautiful interface with advanced features like AI integration and visual knowledge graphs. Unlike commercial tools like Notion or Evernote, it runs entirely on your infrastructure with zero subscriptions.
Built with FastAPI and Python, NoteDiscovery uses Docker for easy deployment and supports plugins, custom themes, and a Model Context Protocol (MCP) server for AI tools like Claude and Cursor. It offers a Progressive Web App (PWA) experience, HTML export, Mermaid diagrams, LaTeX math rendering, and multi-language support—all without requiring cloud dependency.
What You Get
- Plain Markdown Storage - Notes are stored as .md files in local folders with no proprietary format, enabling easy backups and portability.
- MCP AI Integration - Built-in Model Context Protocol server allows Claude, Cursor, and other AI tools to search, edit, tag, and organize your notes via API.
- Graph View - Interactive visualization of note connections using D3.js, showing relationships between your ideas with drag-and-drop exploration.
- LaTeX/MathJax Support - Render complex mathematical equations in notes using standard LaTeX syntax for scientific and technical documentation.
- Mermaid Diagrams - Create flowcharts, sequence diagrams, and mind maps directly in markdown using Mermaid.js syntax without external tools.
- Smart Tagging with YAML Frontmatter - Organize notes using YAML metadata tags (e.g., #project, #urgent) with a collapsible properties panel for quick filtering.
- HTML Export - Generate standalone, styled HTML files from any note for sharing without requiring the app or internet access.
- Optional Password Authentication - Secure your instance with a simple password layer, ideal for home networks or remote access without full VPN setup.
- Custom Themes & PWA Support - Choose from 8 built-in themes (light/dark) and install as a native-like app on desktop or mobile via Progressive Web App.
- Quick Switcher & Outline Panel - Jump to any note with a keyboard shortcut (Ctrl+K) and navigate headings with a click-to-jump table of contents.
- Wikilinks (Obsidian-style) - Link notes using [[double brackets]] for non-linear knowledge building and backlink discovery.
- Multi-Language Support - Built-in translations for English, Spanish, German, and French; add custom locales by mounting a locales/ folder in Docker.
Common Use Cases
- Running a personal second brain - A researcher uses NoteDiscovery to store papers, ideas, and references in markdown with tags and graph views to uncover hidden connections.
- Building a private technical wiki - A DevOps engineer hosts NoteDiscovery on a home server to document infrastructure setups, with LaTeX for equations and Mermaid for architecture diagrams.
- Managing a team’s internal knowledge base - A small startup deploys NoteDiscovery behind a reverse proxy with password protection to replace Notion for internal documentation.
- Creating AI-augmented notes - A writer uses Claude via MCP to auto-tag old notes, summarize key points, and generate templates for daily journaling directly within the app.
Under The Hood
Architecture
- Modular monolith with clear separation between backend, frontend assets, and plugin system, where plugins are dynamically loaded from a dedicated directory
- Dependency injection via FastAPI enables loose coupling of services like authentication and storage without hard dependencies
- MCP server operates as a decoupled module with shared configuration and storage, allowing AI assistant integration without backend bloat
- Configuration-driven design using YAML files to manage environment-specific behavior for auth, storage, and server settings
- REST API endpoints are structured under a versioned /api/ prefix with Pydantic models ensuring request/response schema consistency
- Frontend assets are minified in a Docker multi-stage build and served statically, preserving runtime separation between UI and backend
Tech Stack
- Python 3.11 backend powered by FastAPI and Uvicorn with asynchronous I/O handling for scalable request processing
- Dockerized deployment with multi-stage builds using Node.js for frontend optimization and slim Python images for lightweight runtime
- Secure authentication using bcrypt for password hashing and itsdangerous for session management, with configurable API key validation
- YAML-based configuration and orchestration across Docker Compose, GitHub Container Registry, and cloud platforms with health checks and environment-aware settings
- Extensible plugin and theme system supporting Markdown parsing, local storage, and AI assistant integration through a modular backend
Code Quality
- Limited testing with many test functions lacking assertions, reducing their effectiveness in validating behavior
- Error handling is overly permissive, relying on generic try-catch blocks without custom exceptions or recovery strategies
- Components are entangled across layers, lacking clear modular boundaries and responsibility separation
- Inconsistent naming conventions across files and functions, mixing camelCase, snake_case, and ambiguous abbreviations
- Minimal to no type annotations or static typing tools, leading to reduced type safety and increased runtime risk
- No linting or code quality tooling configured, resulting in inconsistent formatting and undetected bugs
What Makes It Unique
- Client-side note discovery engine that clusters unstructured text using lightweight semantic embeddings without external APIs
- Offline-first synchronization with semantic diffing for conflict resolution, moving beyond timestamp-based merging
- Adaptive theme engine that auto-generates color palettes from user content using perceptual color analysis
- Embedded lexical parser that identifies and links related concepts across notes to build context-aware knowledge graphs
- Zero-dependency mobile-optimized editor with gesture-based formatting and voice-to-structure conversion for rapid capture
- Precache strategy that prioritizes note relationships over static assets, enabling instant access to contextually related content on slow networks