HyperTag helps humans intuitively express how they think about their files using tags and machine learning. Represent how you think using tags. Find what you look for using semantic search for your text documents (yes, even PDF's) and images. Instead of introducing proprietary file formats like other existing file organization tools, HyperTag just smoothly layers on top of your existing files without any fuss.
Objective Function: Minimize time between a thought and access to all relevant files.
Accompanying blog post: https://blog.neotree.uber.space/posts/hypertag-file-organization-made-for-humans
Table of Contents
Available on PyPI
$ pip install hypertag (supports both CPU only & CUDA accelerated execution!)
Join the HyperTag matrix chat room to stay up to date on the latest developments or to ask for help.
HyperTag offers a slick CLI but more importantly it creates a directory called HyperTagFS which is a file system based representation of your files and tags using symbolic links and directories.
Directory Import: Import your existing directory hierarchies using $ hypertag import path/to/directory. HyperTag converts it automatically into a tag hierarchy using metatagging.
Semantic Text & Image Search (Experimental): Search for images (jpg, png) and text documents (yes, even PDF's) content with a simple text query. Text search is powered by the awesome Sentence Transformers library. Text to image search is powered by OpenAI's CLIP model. Currently only English queries are supported.
HyperTag Daemon (Experimental): Monitors HyperTagFS and directories added to the auto import list for user changes (see section "Start HyperTag Daemon" below). Also spawns the DaemonService which speeds up semantic search significantly (warning: daemon process is a RAM hog with ~2GB usage).
Fuzzy Matching Queries: HyperTag uses fuzzy matching to minimize friction in the unlikely case of a typo.
File Type Groups: HyperTag automatically creates folders containing common files (e.g. Images: jpg, png, etc., Documents: txt, pdf, etc., Source Code: py, js, etc.), which can be found in HyperTagFS.
HyperTag Graph: Quickly get an overview of your HyperTag Graph! HyperTag visualizes the metatag graph on every change and saves it at HyperTagFS/hypertag-graph.pdf.
Import files with tags inferred from the existing directory hierarchy.
$ hypertag import path/to/directory
$ hypertag add path/to/file https://github.com/SeanPedersen/HyperTag
Manually tag files. Shortcut: $ hypertag t
$ hypertag tag humans/*.txt with human "Homo Sapiens"
Add a value to a file's tag:
$ hypertag tag sean.txt with name="Sean Pedersen"
Manually remove tag/s from file/s.
$ hypertag untag humans/*.txt with human "Homo Sapiens"
Metatag tag/s to create tag hierarchies. Shortcut: $ hypertag tt
$ hypertag metatag human with animal
Merge all associations (files & tags) of tag A into tag B.
$ hypertag merge human into "Homo Sapiens"
Print file names of the resulting set matching the query. Queries are composed of tags (with values) and operands. Tags are fuzzy matched for convenience. Nesting is currently not supported, queries are evaluated from left to right.
Shortcut: $ hypertag q
Query with a value using a wildcard: $ hypertag query name="Sean*"
Print paths: $ hypertag query human --path
Print fuzzy matched tag: $ hypertag query man --verbose
Disable fuzzy matching: $ hypertag query human --fuzzy=0
Default operand is AND (intersection):
$ hypertag query human name="Sean*" is equivalent to $ hypertag query human and name="Sean*"
OR (union):
$ hypertag query human or "Homo Sapiens"
MINUS (difference):
$ hypertag query human minus "Homo Sapiens"
Only indexed files can be searched.
$ hypertag index
To parse even unparseable PDF's, install tesseract: # pacman -S tesseract tesseract-data-eng
Index only image files: $ hypertag index --image
Index only text files: $ hypertag index --text
A custom search algorithm combining semantic with token matching search.
Print text file names sorted by matching score.
Performance benefits greatly from running the HyperTag daemon.
Shortcut: $ hypertag s
$ hypertag search "your important text query" --path --score --top_k=10
Print image file names sorted by matching score.
Performance benefits greatly from running the HyperTag daemon.
Shortcut: $ hypertag si
Text to image:
$ hypertag search_image "your image content description" --path --score --top_k=10
Image to image:
$ hypertag search_image "path/to/image.jpg" --path --score --top_k=10
Start daemon process with triple functionality:
HyperTagFS directory for user changes
Search Images or Search Texts: Interprets name as semantic search query (add top_k=42 to limit result size) and automatically populates it with results$ hypertag daemon
$ hypertag tags filename1 filename2
$ hypertag metatags tag1 tag2
$ hypertag show
Print names:
$ hypertag show files
Print paths:
$ hypertag show files --path
Visualize the metatag graph hierarchy (saved at HyperTagFS root).
$ hypertag graph
Specify layout algorithm (default: fruchterman_reingold):
$ hypertag graph --layout=kamada_kawai
Generate file system based representation of your files and tags using symbolic links and directories.
$ hypertag mount
Directories added to the auto import list will be monitored by the daemon for new files or changes.
$ hypertag add_auto_import_dir path/to/directory
Default is the user's home directory.
$ hypertag set_hypertagfs_dir path/to/directory
pyproject.toml)~/.config/hypertag/hypertag.db)~/.config/hypertag/web_pages for websites, others in ~/.config/hypertag/downloads$ git clone https://github.com/SeanPedersen/HyperTag.git$ cd HyperTag/$ poetry install$ poetry shell$ pytest -v$ black hypertag/$ flake8$ mypy **/*.py$ bandit --exclude tests/ -r .$ python -m hypertagWhat is the point of HyperTag's existence?
HyperTag offers many unique features such as the import, semantic search, graphing and fuzzy matching functions that make it very convenient to use. All while HyperTag's code base staying relatively tiny at <2000 LOC compared to similar projects like TMSU (>10,000 LOC in Go) and SuperTag (>25,000 LOC in Rust), making it easy to hack on.
FAQs
File organization made for humans
We found that hypertag demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.