[GitHub](https://github.com/PR0M3TH3AN/Marlin) # Marlin: Your Personal Digital Librarian, Supercharged! Got a sprawling mess of digital files—documents, notes, photos, code—scattered across your computer? Finding *that one file* can feel like a wild goose chase. **Marlin** is your hyper-efficient, privacy-first digital librarian, living on your machine to organize and retrieve anything, instantly. --- ### How It Works (The Magic Under the Hood) 1. **Scans, Doesn’t Move:** Point Marlin to your folders (`marlin init` in a directory, then `marlin scan <other_dirs>`). It builds a fast SQLite index (~/.local/share/marlin/index.db) with file locations and basics (size, modification date), leaving your file structure untouched. [Marlin/src/main.rs, Marlin/src/scan.rs] 2. **Add Superpowers (Metadata):** Here’s where Marlin shines. You can: - **Tag Freely:** Use hierarchical tags like `project/alpha/draft` or simple ones like `invoice`. [Marlin/marlin_demo.md] - **Set Custom Attributes:** Add `status=complete`, `client=AcmeCorp`, or `reviewed=yes`. [Marlin/marlin_demo.md] - **Create Links:** Connect files, e.g., `marlin link add --type references report.pdf data.csv`. [Marlin/marlin_demo.md] - **Build Collections:** Group files into “playlists” with `marlin coll create vacation_2025`. [Marlin/marlin_demo.md] - **Save Smart Views:** Create dynamic folders, e.g., `marlin view save urgent "tag:urgent OR TODO"`. [Marlin/marlin_demo.md] 3. **Find Anything, Instantly:** Search with `marlin search tag:project/alpha AND attr:status=pending` or `marlin search TODO`, using Full-Text Search (FTS5) on paths, tags, and attributes (file content indexing planned for Q3 2025). Run commands on results, like opening all found PDFs. [Marlin/src/main.rs, Marlin/marlin_demo.md] 4. **Safe and Sound:** Marlin backs up its index before every command (except `init`) and supports manual snapshots, protecting your organization. [Marlin/src/main.rs, Marlin/README.md] --- ### What Makes Marlin Unique? 1. **Your Data, Your Machine:** Marlin is 100% local—no cloud, no telemetry, no third-party access. Future sync is optional and user-controlled. [Marlin/README.md] 2. **Beyond Filenames:** Hierarchical tags, custom attributes, and typed links create a rich, interconnected web of *meaning*, surpassing basic folders or tags. [Marlin/README.md, Marlin/vision.md] 3. **Powerful Yet Approachable:** Built in Rust for speed and SQLite for reliability, it’s lightweight. The CLI is clear, with `marlin demo` (coming soon) as an on-ramp. [Marlin/Cargo.toml, Marlin/db/mod.rs] 4. **Resilient and Transparent:** Versioned database migrations ensure your index evolves without breaking. Its open-source vibe (Rust, detailed docs) means no hidden magic. [Marlin/db/migrations/] 5. **Future-Proof Vision:** Plans for content indexing, NLP search, GUI plugins (e.g., Dolphin sidebar), and team sync (Q2 2026) make it a long-term bet. [Marlin/vision.md, Marlin/roadmap.md] --- ### Usage Examples **For Individuals:** - **Researcher/Student:** - Tag: `paper.pdf` with `neuroscience/memory/2024`, `methods/fmri`. - Attributes: `status=read`, `rating=5stars`. - Search: `marlin search tag:neuroscience/memory AND attr:rating=5stars`. - Link: `marlin link add --type cites review.docx paper.pdf`. - **Creative Professional:** - Collection: `marlin coll create client_x_campaign` for all assets. - Tag: `logo_draft_v3.ai` with `client_x/logo/draft`. - Attributes: `feedback=pending`, `version=3`. - View: `marlin view save feedback "tag:client_x AND attr:feedback=pending"`. - **Software Developer:** - Tag: `auth_service.rs` with `project_phoenix/backend/rust`. - Attributes: `user_controller.java` with `needs_refactor=true`. - Search: `marlin search TODO` across files. - Link: `marlin link add --type implements design.md code.rs`. - **Home Organizer:** - Tag: `home_insurance_2024.pdf` with `finances/insurance/home`. - Attributes: `warranty_fridge.pdf` with `purchase_date=2023-05-10`. - Search: `marlin search tag:warranty AND tv`. **For Others (Current & Future):** - **Small Teams (Q2 2026 Sync):** Share consistent tags/attributes on a local server, e.g., find `status=approved_by_legal` files. - **AI Agents:** Query Marlin’s index for precise files (e.g., `tag:project_x AND attr:status=complete`) to generate reports or answer questions. - **PKM Enthusiasts:** Build a “second brain” with linked notes and rich metadata for deep, contextual searches. --- Marlin empowers anyone to tame their digital chaos, organize files meaningfully, and find what they need fast—all while keeping data private. Its scriptable CLI suits power users, and clear docs (plus a future GUI) aim to welcome all. Try `marlin demo` (soon!) to dive in! 🚀