Vulpea User Guide

This guide covers daily usage of Vulpea - finding notes, creating links, and working with metadata.

Finding Notes

vulpea-find

The primary way to navigate your notes:

M-x vulpea-find

This opens a completion interface showing all your notes. Type to filter, then select a note to open it.

Features:

Searches titles and aliases
Shows tags in the completion display
Creates a new note if you enter a title that doesn’t exist

vulpea-find-backlink

Find notes that link to the current note:

M-x vulpea-find-backlink

This is useful for discovering connections - seeing what other notes reference the one you’re viewing.

Creating Links

vulpea-insert

Insert a link to another note:

M-x vulpea-insert

This opens completion to select a note, then inserts an id: link at point:

See [[id:abc123][Selected Note Title]] for details.

If you type a title that doesn’t exist, Vulpea offers to create a new note.

Creating Notes

From vulpea-find

When you use vulpea-find and type a title that doesn’t exist, Vulpea asks if you want to create it.

Programmatically

For scripts or custom commands:

;; Simple creation
(vulpea-create "My New Note")

;; With tags
(vulpea-create "Project Note"
               nil  ; use default file-name template
               :tags '("project" "work"))

;; With metadata
(vulpea-create "Book Review"
               nil
               :meta '(("author" . "Jane Smith")
                       ("rating" . "4")))

Under Existing Notes

Create heading-level notes inside an existing file using :parent:

;; Add a heading under an existing note
(let ((parent (vulpea-db-get-by-id "parent-id")))
  (vulpea-create "New Section" nil :parent parent))

;; Control insertion order with :after
(vulpea-create "First" nil :parent parent :after nil)      ; first child
(vulpea-create "Last" nil :parent parent :after 'last)     ; last child (default)
(vulpea-create "After X" nil :parent parent :after "x-id") ; after specific sibling

Default Templates

Configure defaults that apply to all new notes:

(setq vulpea-create-default-template
      '(:tags ("inbox")
        :head "#+created: %<[%Y-%m-%d]>"))

Or use a function for dynamic defaults:

(setq vulpea-create-default-function
      (lambda (title)
        (list :tags (if (string-match-p "TODO" title)
                        '("task")
                      '("note")))))

→ See Configuration for all template options.

Working with Metadata

Metadata lets you attach structured data to notes using description lists:

#+title: Château Margaux 2015

- country :: France
- region :: [[id:bordeaux-id][Bordeaux]]
- price :: 450
- rating :: 95

Reading Metadata

In elisp (for scripts or custom commands):

(let ((note (vulpea-db-get-by-id "wine-id")))
  ;; Get as string (default)
  (vulpea-note-meta-get note "country")  ; => "France"

  ;; Get as number
  (vulpea-note-meta-get note "price" 'number)  ; => 450

  ;; Get linked note
  (vulpea-note-meta-get note "region" 'note))  ; => <vulpea-note>

For multiple values with the same key:

- grape :: Cabernet Sauvignon
- grape :: Merlot
- grape :: Petit Verdot

(vulpea-note-meta-get-list note "grape")
;; => ("Cabernet Sauvignon" "Merlot" "Petit Verdot")

Setting Metadata

In a note buffer:

;; Add or update metadata
(vulpea-buffer-meta-set "status" "reviewed")
(vulpea-buffer-meta-set "rating" "95")

To modify a note programmatically and sync immediately:

(vulpea-utils-with-note-sync note
  (vulpea-buffer-meta-set "status" "done"))
;; Database is now updated

Working with Tags

Viewing Tags

Tags appear in note completion and are accessible via:

(vulpea-note-tags note)  ; => ("project" "work")

Adding Tags Interactively

In a note buffer:

M-x vulpea-buffer-tags-add

Removing Tags

M-x vulpea-buffer-tags-remove

Setting Tags Programmatically

;; In a note buffer
(vulpea-buffer-tags-set '("project" "active"))

Working with Tags by Note

When you have a note (or note ID) and want to modify its tags without visiting the buffer:

;; Get tags for any note
(vulpea-tags note-or-id)

;; Add/remove tags
(vulpea-tags-add note-or-id "new-tag")
(vulpea-tags-remove note-or-id "old-tag")

;; Replace all tags
(vulpea-tags-set note-or-id "only" "these")

Renaming Tags Globally

To rename a tag across all notes:

M-x vulpea-tags-batch-rename

This prompts for the old tag (with completion) and new tag name, then updates all affected notes.

Programmatically:

(vulpea-tags-batch-rename "old-name" "new-name")
;; => count of modified notes

Batch Tag Operations

For operating on multiple notes at once:

;; Add a tag to multiple notes
(vulpea-tags-batch-add notes "archived")

;; Remove a tag from multiple notes
(vulpea-tags-batch-remove notes "active")

Managing Aliases

Aliases are alternative titles for a note, useful when the same concept has multiple names.

In Your Notes

Aliases are stored in the ALIASES property (configurable via vulpea-buffer-alias-property):

:PROPERTIES:
:ID: abc123
:ALIASES: "PKM" "Personal Knowledge Management"
:END:
#+title: Zettelkasten

Now searching for “PKM” in vulpea-find will find this note.

Adding Aliases

M-x vulpea-buffer-alias-add

Or programmatically:

(vulpea-buffer-alias-add "Alternative Name")

Removing Aliases

M-x vulpea-buffer-alias-remove

Configuring Alias Property

By default, aliases are stored in ALIASES. To use ROAM_ALIASES for org-roam compatibility:

(setq vulpea-buffer-alias-property "ROAM_ALIASES")

Renaming Notes

When you change a note’s title, links pointing to it still show the old title. Vulpea provides tools to propagate title changes across your knowledge base.

Quick Workflow

Edit the #+title: line in your note, save
If vulpea-title-change-detection-mode is enabled, you’ll see a notification
Run M-x vulpea-propagate-title-change
Optionally rename the file (y/n)
Update link descriptions: [!] all, [r] review, [s] skip, [q] quit
Review partial matches manually

vulpea-propagate-title-change

The main command for updating references after a title change:

M-x vulpea-propagate-title-change

This command:

Asks for the old title (if not detected automatically)
Shows how many links need updating
Lets you rename the file to match the new title
Updates link descriptions in other notes

For a preview without making changes, use the prefix argument:

C-u M-x vulpea-propagate-title-change

Title Change Detection

Enable automatic detection of title changes:

;; For all org files
(add-hook 'org-mode-hook #'vulpea-title-change-detection-mode)

Now when you save a note with a changed title, you’ll see:

Title changed from "Old Name" to "New Name". Run M-x vulpea-propagate-title-change to update references.

How Links Are Categorized

When you run vulpea-propagate-title-change, links are split into:

Exact matches: Link description exactly equals the old title or alias (case-insensitive). These can be auto-updated.
Partial matches: Link description contains the old title but has additional text (e.g., “See Old Title for details”). These are shown for manual review.
Custom descriptions: Link descriptions that don’t match are left alone (you chose them deliberately).

Renaming the File

If you also want to rename the file to match the new title:

Rename file "old_title.org" → "new_title.org"? (y or n)

The new filename uses the title slug (lowercase with underscores). The database is updated automatically.

You can also rename files programmatically:

(vulpea-rename-file note "New Title")

→ See API Reference for detailed function documentation.

Synchronization

Automatic Sync

With vulpea-db-autosync-mode enabled, Vulpea automatically:

Detects when you save org files
Detects external changes (git pull, sync tools) if fswatch is installed
Updates the database in the background

You don’t need to do anything - it just works.

Manual Sync

If you need to force a sync:

Command	What it does
`M-x vulpea-db-sync-update-file`	Update current file
`M-x vulpea-db-sync-full-scan`	Scan all directories
`C-u M-x vulpea-db-sync-full-scan`	Force re-index everything

Checking Sync Status

;; Count notes in database
(vulpea-db-count-notes)

;; Check if autosync is running
vulpea-db-autosync-mode

Encrypted Files

Vulpea can track age-encrypted (.org.age) and GPG-encrypted (.org.gpg) org files. See Configuration → Extra File Extensions for setup.

Once configured, encrypted files work like regular org files:

vulpea-find includes them in search results
Links, tags, and metadata are queryable
Changes are detected automatically by the sync system

Note: Encrypted files are parsed more slowly (via find-file) than regular .org files. For large collections, keep the number of encrypted files manageable.

Tips and Workflows

Zettelkasten-Style Notes

Create atomic notes with vulpea-find (type new title to create)
Link related notes with vulpea-insert
Explore connections with vulpea-find-backlink
Use tags for broad categories, metadata for specific attributes

Project Notes

:PROPERTIES:
:ID: project-123
:END:
#+title: Website Redesign
#+filetags: :project:active:

- status :: in-progress
- deadline :: 2025-01-15
- client :: [[id:client-456][Acme Corp]]

* Tasks
* Notes
* Resources

Query all active projects:

(vulpea-db-query-by-tags-every '("project" "active"))

Quick Capture Integration

Integrate with org-capture for quick note creation:

(setq org-capture-templates
      '(("n" "Note" plain
         (file (lambda ()
                 (vulpea-note-path
                  (vulpea-create "Quick Note"))))
         "%?")))

Next Steps

Configuration - All options and performance tuning
API Reference - Building custom tools

Uh oh!

FilesExpand file tree

user-guide.org

Latest commit

History