CrateMind is a local TypeScript/Node.js-based vibe sorter and audio router that leverages
Gemini LLM to automatically categorize and sort your music files.
It runs directly in your terminal using a beautiful React-based TUI (powered by Ink 4
& Zustand), making it the perfect tool for DJs and music collectors to curate their
libraries with zero manual friction.
A built-in RAG (Retrieval-Augmented Generation) memory layer accumulates every past
routing decision and injects few-shot examples into each new Gemini prompt — so the more
tracks you sort, the smarter and more consistent the vibe classification becomes.
CrateMind operates on a user-first, semi-automatic principle: the system suggests,
the user decides. Every action touching your collection requires explicit confirmation.
Gemini API Spend & Token Optimization
During the initial design phase, the system performed raw, un-cached Gemini API calls for
every scanned track, resulting in significant token consumption and higher API request
overhead during heavy catalog ingestions.
To eliminate redundant overhead, we implemented a multi-layered optimization strategy:
SHA-256 Context-Aware Cache: Offlines LLM responses using deterministic hashing
of track features, neighbor references, and YouTube contexts.
Session-Based Fallback Matching: Reuses recent classification hits by matching
metadata (Artist/Title) within a 24-hour window, bypassing slight floating-point changes
in vector similarities.
Engine DJ Tier 1 Backup Match: Directly resolves folders using local SQLite
references in Denon DJ's m.db, bypassing LLM processing entirely for
previously sorted tracks.
YouTube Scout Cache: Caches YouTube scraping results to prevent duplicate network
calls and conserve tokens on neighboring tracks in similar mixes.
Following these optimizations, active sorting runs achieved a 90–95% reduction in
daily token consumption and API request costs, demonstrating that even highly advanced,
LLM-based categorization can run at production scale with minimal resources.
* ACTIVE LISTENER|Listening ./Incoming [SIMULATOR] [🤖 GEMINI ANALYZING...]
[YT_SEARCH] Searching YouTube context for Stephan Bodzin - Strand...
[YT_HIT] Found in YouTube mix: "Melodic Sunset 2026 | Deep Progressive Mix" — playlist saved to memory
[LLM_REASONING] Hypnotic melodic synth lead, deep hardware textures. Borderline atmospheric. Enriched with YouTube playlist companion tracks: Ben Böhmer - Beyond Beliefs, Lane 8 - Keep On.
[NEEDS_MANUAL] Daily request limit exceeded. Prompting user override...
PLAYINGStephan Bodzin – Strand.flac
BPM124|KEY4A|DURATION0:16/ 3:00
[
]
Use [P] to Pause/Resume | [←]/[→] to seek 10s, Shift for 30s
[Space] Pause/Resume Listener
|[L] Reset Limits
|[V] Index DB Vibes
|[C] Simulate Chaos
|[T] Sync Telegram
|[S] Sync to Collection
|[Q] Exit Sorter
Technical Architecture:
TrackWatcher: Chokidar file watcher & sequential queue manager (p-queue).
Spawns the processing pipeline for incoming audio files. Integrates with the Telegram
download state to intelligently buffer files, waiting for a full configured
BATCH_SIZE before starting analysis, while ignoring single leftover tracks
on boot scan.
TrackProcessor: Core linear pipeline orchestrator handling metadata extraction,
RAG checks, YouTube scouting, LLM classification, and user interaction/routing.
NetworkScoutService: YouTube playlist context finder with in-memory playlist
cache ("playlist memory effect") to discover neighboring tracks in live mixes and warm
the cache.
ID3Service: Metadata tag extraction using music-metadata, and safe tag writing
(BPM and Key) for MP3/FLAC files via FFmpeg stream copying. Features a local
file_metadata_cache table in cratemind.db to speed up
subsequent bootstrap folder crawls.
AubioService: Offline audio analysis service. Runs `aubio tempo` to estimate BPM
and `keyfinder-cli` to detect musical keys on macOS when files lack ID3 metadata.
EngineDBService: Strictly read-only connection to Engine DJ's SQLite database
(m.db) to retrieve playlists, folder paths, BPM, and keys. Uses
process-lifetime caching for high-performance library lookups.
RAGService: Few-shot memory layer — persists routing history to the
rag_examples table in cratemind.db and builds context strings
for LLM prompts.
CacheService: Handles persistent offline SHA-256 caching and API statistics
inside SQLite tables (llm_cache, api_stats) in
cratemind.db.
LLMService: Gemini API integration with structured Zod schema validation, local
cache lookup, and limit checks (simulated in Mock Mode).
EmbeddingService: Local vector database integration. Generates embeddings using
gemini-embedding-2 and runs cosine similarity searches, applying a similarity threshold
of 0.80 to filter out noisy, low-quality matches.
TelegramService: Telegram client integration using GramJS. Allows connecting to
custom chats/channels via userbot session keys to scrape, filter, and download audio
tracks sequentially into the Incoming folder for analysis.
UIService: Custom Ink 4 components bound to a Zustand state store.
Key Features:
Automatic detection of new tracks in ./Incoming.
Telegram Bulk Downloader: Sync and download music from defined Telegram channels
using GramJS userbot credentials. Features built-in duplicate detection checking local
Incoming files, Sorted folders, and the Engine DJ DB before downloading. Integrates with
file watcher buffering to wait for a full BATCH_SIZE chunk of tracks before
starting analysis, optimizing Gemini API limits. Supports a dedicated interactive **Download-Only Mode** (prompted upon starting sync) to fetch tracks into the Incoming directory without spawning any LLM or analysis tasks. Includes automatic mix protection to skip long DJ sets/podcasts based on duration limits.
Live Stats Header: Single-line status bar showing real-time
Incoming count (updated instantly via chokidar events), plus global
lifetime stats from rag_examples: Sorted total, AI hits, Manual fixes,
and AI accuracy rate calculated over actually classified tracks
(auto ÷ (auto + manual)).
LLM-driven vibe categorization into 21 custom atmospheric folders.
RAG memory: Builds context from past sortings — classifies by atmosphere, not
just artist name. Instant RAG auto-routing is strictly restricted to user-approved
manual entries (source: 'manual') or files physically present in the
collection (source: 'scan'/'engine-dj'), ensuring automatic LLM
classifications from previous runs that were never confirmed do not bypass re-analysis
if they return to the Incoming folder. Features **unlimited RAG database capacity** to
retain all confirmed track vibes forever without rotation or eviction.
Personal Prompt Adaptation (Self-Reflective RAG): Dynamically learns from your
manual overrides, generating inline system instruction corrections to align Gemini's
routing with your precise music taste over time.
Local Caching & Limits: SHA-256 context-aware cache to prevent redundant LLM
latency/charges, paired with daily request limits to avoid API overspending. Optimized
with:
Session-Based Fallback: Automatically falls back to matching by artist/title
within the last 24 hours if the strict context hash misses due to float precision
variance in vector similarity scores or YouTube scout fluctuations. The hit is then
automatically cloned under the new context hash.
Confidence-Aware Interception: Cache hits with low confidence (< 0.99) are
intercepted and redirected to the manual override TUI, preventing automatic
misrouting of unconfirmed tracks.
Sequential Chunking: Large batches of incoming files are split into small
groups of 5 tracks and processed sequentially. This prevents API exhaustion (429)
and limits the impact of errors to isolated chunks.
Engine DJ Integration (Strictly Read-Only): Integrates with Denon DJ's SQLite
database (m.db). Features:
Tier 1 Backup Match: Instantly matches incoming tracks against
m.db playlist associations or directory folder names, auto-routing them
directly without calling the Gemini API.
Pre-Extraction Check: Looks up metadata (BPM, Key) in the database via
filename or parsed names *before* running expensive ID3 extraction or offline
tempo/key analysis.
Smart Filename Fallback: Automatically parses the artist and title from the
track filename if they are missing or empty in the database column fields, enabling
clean consensus matching and avoiding "Unknown Artist" fallbacks.
Offline Audio Analysis (macOS): Automatically estimates tempo (BPM) and detects
musical keys (Camelot format) using local CLI tools (aubio and
keyfinder-cli) when metadata tags are missing or corrupt. Newly estimated
or database-matched BPM and key values are automatically written back into the source
track's metadata (ID3v2 for MP3, Vorbis Comments for FLAC) using FFmpeg before routing.
Bypassed completely if cached in the local database or if already matched inside Engine
DJ DB.
User-first: Bootstrap scan, collection change, and memory clear all require
explicit [Y/n] confirmation.
Beautiful multi-select checkbox TUI for low-confidence Manual Overrides, with skipped
(unmarked) tracks automatically routed to a dedicated Sorted/skipped folder
to keep the incoming queue clean.
Native OS audio preview via ffplay with precise seeking support.
Mock Mode: Complete sandboxed offline simulation (via .env toggle)
to test base SQLite DB, file watchers, Gemini classifications, and physical routing
without real dependencies.
Force Manual Mode: A configurable toggle (via .env) that allows all
background vector consensus, YouTube scouting, and Gemini classification pipelines to
run fully, but forces every single track into the Manual Override TUI with
recommendations pre-selected so you can review and approve every routing.
Automatic Log Rotation: Prevents unbounded log growth by automatically rotating
and archiving cratemind.log to cratemind.old.log when it
exceeds 5MB.
Future Integration Ideas:
Model Context Protocol (MCP) Server: Expose CrateMind's RAG memory and
vibe-routing logic as an MCP server. This allows IDE agents (like Claude or Antigravity)
to query your library's organization rules, analyze track metadata, and suggest
playlists directly inside your coding/chat environments.
Antigravity SDK (AGY CLI) Integration: Integrate CrateMind with the AGY CLI to
orchestrate autonomous multi-agent music curations. For example, let one subagent scour
streaming platforms or charts for new releases, while CrateMind acts as the local
routing agent to seamlessly classify them into your physical crates.
Streaming Playlists Import (Apple Music / Spotify): Monitor and import tracklists
directly from Apple Music and Spotify playlist URLs. The system can scrape track names
and artist details from the web pages, download high-quality audio files using
yt-dlp directly into the Incoming folder, and run the RAG-vibe
classification pipeline.
Beatport Purchase Integration: Automatically search Beatport for identified tracks
to retrieve purchase links, and write them directly into the audio files' ID3 tags (e.g. inside Comments or custom URL frames) for quick reference when building live DJ libraries.