A database layer for your org-mode notes. Vulpea indexes your notes and provides fast queries for tags, links, metadata, and full-text search - all without blocking your workflow.

Org-mode is powerful, but working with hundreds or thousands of notes becomes difficult. Finding notes, discovering connections, and querying your knowledge base requires tooling beyond what org-mode provides.

Vulpea solves this by maintaining a database of your notes that stays in sync with your files. You get:

• Fast note finding - Search by title, tags, or content across thousands of notes
• Connection discovery - Find what links to what, explore backlinks
• Rich queries - Filter notes by tags, metadata, links, or custom predicates
• Non-blocking sync - Database updates happen in the background, never interrupts your typing
• External change detection - Works with git, Dropbox, Syncthing - files changed outside Emacs are detected automatically

Personal knowledge management - Use M-x vulpea-find to navigate your notes, M-x vulpea-insert to create links between ideas. Vulpea handles Zettelkasten-style workflows where connections matter.

Building applications - Vulpea provides a foundation for note-based apps. Vino uses Vulpea to manage wine collections with ratings, producers, and regions. The included journal module provides daily notes with widgets.

Large collections - Designed to scale. The async architecture and optimized queries handle 100k+ notes without degrading performance.

Vulpea is designed as a foundation, not an application. Where tools like org-roam aim to replicate Roam Research in Emacs (and do it very well), Vulpea provides a stable API layer for building your own note-based workflows and applications.

Key differences:

• Schema as implementation detail - Vulpea’s database structure is internal. The public API is functions and data structures, not SQL tables. This allows the backend to evolve without breaking user code.
• Library-first - Vulpea exposes clean abstractions like vulpea-note that don’t leak internals. Build applications on top without coupling to implementation details.
• Coexistence - Vulpea and org-roam can run side-by-side; they use separate databases and don’t interfere.

For a detailed comparison with org-roam and org-node, see Comparison with Other Libraries.

Vulpea originally started as a layer over org-roam, but v2 is a complete rewrite with its own database and indexing. For the full history and design rationale, see Vulpea v2: a story of breaking up with org-roam.

• 🚀 Async-first - File watchers + background processing, no save hooks blocking you
• 📊 Optimized queries - Hybrid database schema for fast reads
• 🔌 Extensible - Plugin system for custom extractors and tables
• 🏷️ Rich metadata - Type-aware metadata with automatic coercion
• ⚡ Scales - Tested with 100k+ notes

;; 1. Configure (defaults to org-directory, so often not needed)
;; (setq vulpea-db-sync-directories '("~/org/"))

;; 2. Build database (first time only)
(vulpea-db-sync-full-scan)

;; 3. Enable auto-sync
(vulpea-db-autosync-mode +1)

;; 4. Start using
;; M-x vulpea-find    - find and open notes
;; M-x vulpea-insert  - insert link to a note

Note: Vulpea only indexes notes with ID properties. Use M-x org-id-get-create to add IDs to your notes.

→ Full Getting Started Guide

Available on MELPA:

;; Using package.el (after adding MELPA to package-archives)
(package-install 'vulpea)

;; Using use-package
(use-package vulpea)

;; Using straight.el
(straight-use-package 'vulpea)

;; Using elpaca
(elpaca vulpea)

Or clone manually:

git clone https://github.com/d12frosted/vulpea

(add-to-list 'load-path "/path/to/vulpea")
(require 'vulpea)

• Emacs 27.2+
• org-mode 9.4.4+
• emacsql 4.3.0+ (with emacsql-sqlite-builtin)
• s 1.12+
• dash 2.19+

For best performance, especially with large collections, install these external tools:

Without fswatch, Vulpea falls back to polling (periodic directory scanning). Without fd, polling uses find which is significantly slower. With both tools installed, external changes are detected instantly with near-zero overhead.

Companion packages that extend Vulpea:

• vulpea-ui - Sidebar infrastructure and widget framework. Provides a per-frame sidebar with outline, backlinks, forward links, and stats widgets. Easy API for creating custom widgets.
• vulpea-journal - Daily journaling with calendar integration. Creates one note per day with sidebar widgets for navigation, calendar view, and “on this day” from previous years.
• consult-vulpea - Consult integration for Vulpea. Provides consult-vulpea-find and consult-vulpea-insert with live preview and consult’s narrowing features.

• vino - Wine cellar management with rich metadata
• d12frosted/environment - Personal configuration (13k+ notes)

v2 is a complete rewrite:

• No org-roam dependency - Standalone library with custom database
• Async-first - Non-blocking updates via file watchers
• Plugin system - Custom extractors with schema versioning
• Performance - Optimized for 100k+ notes

→ Migration Guide from v1

Contributions welcome! See Architecture for design decisions.

Areas where help is needed:

• Performance testing with large collections
• Platform testing (Windows, Linux, macOS)
• Plugin examples
• Documentation improvements

GPLv3

If you enjoy this project, you can support its development via GitHub Sponsors or Patreon.