Joplin Note Categorization Plugin

An on-device AI plugin for Joplin that semantically clusters notes, suggests tags and notebook structures, and detects stale/archivable notes.

Note

This plugin is under active development as part of GSoC 2026. The embedding pipeline, clustering (K-Means, K-Medoids, HDBSCAN), and an interactive UI panel are implemented. Settings customization and staleness analysis are upcoming features.

---

What the Project is About

When note collections grow, manually organizing them into notebooks and tags becomes tedious. This plugin aims to automate organization in a local-first and privacy-preserving way by:

1. Semantic Embeddings: Computing dense vector representations of notes on-device.
2. Clustering & Classification: Grouping similar notes together and extracting keywords for automatic tags or notebook structures.
3. Staleness Analysis: Identifying notes that haven't been edited or linked to recently for archiving.

---

How It Works (Current Pipeline)

The plugin implements a background-threaded embedding pipeline:

• Token-Based Chunking: The plugin reads notes using the Joplin Data API and splits long notes into chunks of 200 tokens using the js-tiktoken tokenizer (cl100k_base vocabulary).
• On-Device Embedding Generation: A Web Worker uses @huggingface/transformers to run the Xenova/all-MiniLM-L6-v2 model. No data ever leaves your machine.
• Hybrid Device Execution:
  • Windows & macOS: Automatically detects WebGPU support (navigator.gpu) and executes the model in fp16 precision (at ~43ms per note).
  • Linux (Fallback): Defaults to running on the CPU using WebAssembly (q8 quantized precision, running ~2x faster than the standard fp32 CPU baseline).

Current Features

• Embedding Pipeline: On-device embedding generation with WebGPU acceleration and WASM fallback
• Native AI Integration: Automatically uses Joplin's built-in AI Search embeddings when available
• Multi-Strategy Clustering: Compare K-Means, K-Medoids, and HDBSCAN results side-by-side
• Interactive Panel: Drag-and-drop notes between clusters, rename clusters, add custom categories
• Apply Categorization: Organize notes into notebooks and/or tags based on clustering results
• Undo Support: Revert any applied categorization with full change tracking
• Empty Notebook Cleanup: Remove empty notebooks left after reorganization

---

How to Run & Build

Prerequisites

• Node.js (v16 or higher)
• Joplin (for manual plugin installation)

Installation

Clone the repository and install the development dependencies:

npm install

Building the Plugin

To compile the source code, pack the Web Worker, and bundle the ONNX runtime WASM assets locally:

npm run dist

This script does the following:

1. Compiles TypeScript source files under src/ via Webpack.
2. Compiles the Web Worker (src/worker/embedWorker.ts) targeting browser-compatible environments.
3. Runs tools/copyAssets.js to copy local onnxruntime-web WASM files into dist/onnx-dist/ so Electron can load them offline without triggering Content Security Policy (CSP) violations.
4. Packages everything into a .jpl archive in the publish/ directory.

Testing the Pipeline

1. Open Joplin.
2. Go to Settings -> Plugins -> Manage Plugins -> Install from File and select the .jpl package generated in publish/.
3. Restart Joplin.
4. Open the categorization panel from View -> AI Categorise: Toggle Panel (or click the brain icon on the note toolbar).
5. Click Analyse Notes to run the full pipeline: notes are embedded, clustered, and results are displayed in the panel.