a local ai-powered file organizer that understands what your files actually mean, not just what their extensions say.
semantic sorter clusters messy files using embeddings and vision-language models — fully offline and privacy-first.
downloads and desktop folders become chaos fast.
screenshots pile up
whatsapp images have useless names
pdfs sit as untitled
project files get scattered across formats
manual sorting becomes friction you eventually ignore
traditional file sorters rely on extensions or rigid rules. they miss semantic relationships between files.
the result is folders that are technically sorted but still mentally messy.
Lets ignore that.
semantic sorter uses local machine learning to understand file meaning before organizing anything.
instead of rule-based sorting, it performs semantic clustering using embeddings and a vision-language model.
key characteristics:
- fully local. no cloud apis. no data leaves your machine
- semantic understanding of filenames
- vision-language image understanding via blip
- pdf text extraction for stronger grouping
- confidence-based project detection to avoid fake folders
- conservative smart renaming only when names are truly useless
- dry run mode for safe preview
- full undo support with move logs
- model purge utility to reclaim disk space
- collision-safe file moves
goal: fewer dumb folders, more meaningful structure.
high level pipeline:
- files are grouped into broad families (images, documents, cad, code, etc)
- semantic text is built from filename + pdf extraction + vision signals
- sentence-transformers generates embeddings locally
- agglomerative clustering groups related files
- confidence gating decides whether a true project folder should exist
- absurd filenames are intelligently renamed
- files are moved with full undo logging
everything runs locally on your machine.
follow the steps below to get the sorter running.
Install Python(skip this if you have python already installed)
winget install Python.Python.3.12
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
(run the commands homebrew asks you to run)
brew install python
cd /path/to/the/folder/wherescriptis
python -m venv venv
this creates an isolated python environment for the project.
mac or linux:
source venv/bin/activate
windows:
venv\Scripts\activate
after activation you should see (venv) in your terminal.
pip install sentence-transformers scikit-learn numpy pillow pypdf torch transformers
first run may take a few minutes while models download locally so bear with it
preview first (safe):
python Semantic_Sorter.py "/path/to/your/folder" --dry-run
example:
python Semantic_Sorter.py ~/Downloads --dry-run
apply for real:
python Semantic_Sorter.py "/path/to/your/folder"
undo last run:
python Semantic_Sorter.py "/path/to/your/folder" --undo
if you encounter error or the file stops in mid try to move the script or folder at some other directory like documents or movies anywhere you likely wont use this
to remove downloaded model caches:
python Purge_Models.py
to remove models and uninstall python packages:
python Purge_Models.py --full
this project is under active iteration. focus is on handling messy real-world folders reliably and locally.
mit license