note-fuse

A FUSE (Filesystem in Userspace) filesystem that organizes markdown notes into virtual directories based on frontmatter metadata. Notes are stored as flat files in a raw directory, but appear organized by tags and dates through the mounted filesystem.

How it works

You write notes as markdown files with YAML frontmatter:

---
tags: work, project-a, todo
date: 2025-10-10
title: My project A todos
---

The actual content of the note goes here.

The filesystem presents these notes in a virtual directory structure:

~/my-notes/
├── all/                          # All notes, flat listing
│   ├── my-project-a-todos.md
│   ├── meeting-notes.md
│   └── grocery-list.md
├── tags/
│   ├── work/
│   │   └── my-project-a-todos.md
│   ├── project-a/
│   │   └── my-project-a-todos.md
│   └── todo/
│       ├── my-project-a-todos.md
│       └── grocery-list.md
└── dates/
    └── 2025-10-10/
        └── my-project-a-todos.md

The same underlying file appears in multiple virtual directories simultaneously. Editing a file through any path modifies the same underlying data. When you save a file with updated frontmatter, the virtual directories update automatically.

Raw storage

On disk, files are stored in a raw directory with UUID-prefixed filenames to avoid collisions:

~/notes-raw/
├── a3b1c2d4-..._my-project-a-todos.md
├── f7e8d9c0-..._meeting-notes.md
└── 1a2b3c4d-..._grocery-list.md

This is an implementation detail - you interact with files through the mounted filesystem, not the raw directory.

Requirements

• Linux (FUSE is Linux-specific)
• FUSE 3 (libfuse3-dev or fuse3 package)
• Rust 1.85+

FUSE setup

Install FUSE if not already present:

# Debian/Ubuntu
sudo apt install fuse3 libfuse3-dev

# Arch Linux
sudo pacman -S fuse3

If you need allow_other support, add user_allow_other to /etc/fuse3.conf.

Building

cargo build --release

Usage

# Create mount point and raw storage directories (created automatically if missing)
note-fuse ~/my-notes --raw-notes-dir ~/notes-raw

The filesystem mounts in the foreground and blocks until unmounted. Use Ctrl+C or unmount from another terminal:

fusermount -u ~/my-notes

Tilde expansion (~) is supported in both paths.

Creating notes

Create files in the all/ directory:

nvim ~/my-notes/all/my-note.md

Add frontmatter with tags and a date, save, and the note will appear in the corresponding virtual directories.

Browsing by tag

ls ~/my-notes/tags/
# work/  project-a/  todo/

ls ~/my-notes/tags/work/
# my-project-a-todos.md

cat ~/my-notes/tags/work/my-project-a-todos.md

Browsing by date

ls ~/my-notes/dates/
# 2025-10-10/

ls ~/my-notes/dates/2025-10-10/
# my-project-a-todos.md

Frontmatter format

The filesystem parses a simple YAML-like frontmatter block delimited by ---:

---
tags: tag1, tag2, tag3
date: 2025-01-15
title: Optional title
---

• tags: Comma-separated list of tags. Each tag creates a virtual subdirectory under tags/.
• date: A date string (any format). Creates a virtual subdirectory under dates/.
• title: Currently stored but not used for directory naming.

Files without frontmatter appear only in all/.

Limitations

• Files can only be created and deleted in the all/ directory. Tag and date directories are read-only views.
• The filesystem state lives in memory and is rebuilt from disk on each startup.
• No file watching - external modifications to the raw directory are not detected while the filesystem is mounted.

License

MIT