Home
Softono
vulpea

vulpea

Open source Emacs Lisp
GitHub
364
Stars
20
Forks
10
Issues
11
Watchers
1 week
Last Commit
Note Taking

About vulpea

Database layer for org-mode notes with async indexing, rich queries, backlink discovery, and external change detection. Scales to 100k+ notes.

Platforms

Web Self-hosted

Languages

Emacs Lisp

Links

Source Code
d
Published by
d12frosted
Visit View Profile

README.md

View on GitHub

+OPTIONS: toc:nil

  • Vulpea

+begin_html

Banner

MELPA Release CI

Sponsor

#+end_html

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.

** Why Vulpea?

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

*** Use Cases

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. [[https://github.com/d12frosted/vino][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.

** Design Philosophy

Vulpea is designed as a foundation, not an application. Where tools like [[https://github.com/org-roam/org-roam][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 [[file:docs/comparison.org][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 [[https://d12frosted.io/posts/2025-11-28-vulpea-v2-breaking-up-with-org-roam][Vulpea v2: a story of breaking up with org-roam]].

** Key Features

  • 🚀 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

** Quick Start

+begin_src emacs-lisp

;; 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

+end_src

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

→ [[file:docs/getting-started.org][Full Getting Started Guide]]

** Installation

Available on [[https://melpa.org/#/vulpea][MELPA]]:

+begin_src emacs-lisp

;; 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)

+end_src

Or clone manually:

+begin_src bash

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

+end_src

+begin_src emacs-lisp

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

+end_src

*** Dependencies

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

*** Optional (Strongly Recommended)

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

| Tool | Purpose | Impact | Install | |-----------+------------------------------------+---------------------------------------------------------+----------------------------------------------------------------------| | =fd= | Fast directory scanning | 15× faster than =find=, critical for polling mode | =brew install fd= / =apt install fd-find= / =pacman -S fd= | | =fswatch= | Reliable external change detection | Instant detection of git/Dropbox/external changes | =brew install fswatch= / =apt install fswatch= / =pacman -S fswatch= |

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.

** Documentation

| Document | Description | |----------+-------------| | [[file:docs/getting-started.org][Getting Started]] | Installation, first steps, basic concepts | | [[file:docs/user-guide.org][User Guide]] | Daily usage, interactive commands, working with notes | | [[file:docs/configuration.org][Configuration]] | All options explained, performance tuning | | [[file:docs/api-reference.org][API Reference]] | Programmatic usage, query functions, data structures | | [[file:docs/journal.org][Journal Module]] | Daily notes with widgets and calendar integration | | [[file:docs/plugin-guide.org][Plugin Guide]] | Writing custom extractors for domain-specific data | | [[file:docs/troubleshooting.org][Troubleshooting]] | Common issues and solutions | | [[file:docs/comparison.org][Comparison]] | How vulpea compares to org-roam and org-node |

** Ecosystem

Companion packages that extend Vulpea:

** Real-World Usage

** What's New in v2

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

→ [[file:docs/migration.org][Migration Guide from v1]]

** Contributing

Contributions welcome! See [[file:docs/architecture.org][Architecture]] for design decisions.

Areas where help is needed:

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

** License

GPLv3

  • Support

If you enjoy this project, you can support its development via [[https://github.com/sponsors/d12frosted][GitHub Sponsors]] or [[https://www.patreon.com/d12frosted][Patreon]].