Smart folders and search
Five folders sit above your own, and nothing was ever filed into them. Each one is a live query drawn as a row in the tree.
| Smart folder | What it holds | Needs a scan |
|---|---|---|
| Unused media | Files no post, page, gallery, featured image or pasted URL points at | Yes |
| Missing alt text | Images whose _wp_attachment_image_alt is absent or empty | No |
| Large files | Files over 1 MB by default | Yes |
| Unattached | Files with no parent post | No |
| This month | Uploaded in the current month | No |
"1,400 images have no alt text" and "2 GB of this library is unused" are the two numbers most worth knowing about a media library, and no parent-child folder table can answer either.
The scan #
Unused media and Large files need one pass over the library. The scan reads every post once and records, per attachment, whether anything genuinely references it:
- images embedded in post content
- URLs pasted into content
- featured images
- gallery blocks and gallery shortcodes
It runs in chunks — 200 posts at a time by default, filterable with
vergeml_scan_chunk — and reports progress. Results are written to attachment meta
(_vergeml_unused, _vergeml_used_in, _vergeml_filesize), so the smart folders
are ordinary meta queries afterwards rather than a live crawl.
_vergeml_used_in is also what powers the Used in column, and what lets the AI
layer find the page an image actually appears on when that image has no parent post.
Re-run the scan after a big content change. It is idempotent.
Tuning it #
| Filter | Default | Purpose |
|---|---|---|
vergeml_scan_chunk | 200 | Posts read per chunk |
vergeml_large_file_bytes | MB_IN_BYTES | The threshold for Large files |
vergeml_smart_folders | the five above | Add or remove smart folders |
vergeml_smart_query_args | per key | The WP_Query args a smart folder resolves to |
vergeml_smart_count_branches | array() | Extra SQL branches for the reference counter |
vergeml_smart_count_exclude | '' | SQL to exclude from the reference count |
Signatures are in Hooks and constants.
The folder group built from descriptions #
Once the AI layer has looked at your library, the tree grows a second group of folders that nothing was filed into either — drawn from the index rather than from anything you did:
Photos · Screenshots · Documents · Diagrams · Logos · Illustrations · People in the picture · Text in the picture
Empty ones are hidden, and the group states how much of your library it is drawn from, so it never implies coverage it does not have.
This group is a member of filters_to_show (the ai entry) rather than a setting
of its own. Switch it off there.
Search #
The plugin widens core's attachment search past title, caption and description. Which columns are searched is a setting — Settings → Library settings → Search — and the choices are:
- filenames
- titles
- captions
- descriptions
plus the uploader and every term a file is filed under.
Two behaviour settings sit beside it: a minimum number of letters before search fires (default 2), and whether search runs as you type or on Enter.
Technically this filters posts_search, posts_join and posts_distinct on
attachment queries and replaces core's search clause — which is what makes the
columns switchable, and which is worth knowing if you are debugging a conflict with
another plugin that touches attachment queries.
Search by meaning #
If the AI layer is on, a second search sits beside the ordinary one, not over it. Type "seaside" and it finds a beach; type "dog" and it finds a golden retriever.
Your phrase is embedded by the service and compared against every described file in
the local index. A compact projection of each vector keeps a 20,000-image search
under half a second, and the search has a time budget (2 seconds by default,
vergeml_meaning_budget_ms) after which it returns what it has rather than
stalling the screen.
More like this one is free and instant, with no AI call at the moment you ask: it compares descriptions your library already holds.
Both are covered in Descriptions and alt text and Sorting a library.
Written from version 3.15.0 of the plugin. Last updated 2026-10-02. All documentation · Legal · Support