⚡ Hermes Clipper

"Too lazy to file it yourself? I got you." An intelligent, agent-driven web clipping ecosystem that leverages the Hermes Agent to autonomously organize, research, and refine your knowledge directly into your Obsidian vault.

---

🌟 Overview

Hermes Clipper is not just another bookmarking tool. It's a decentralized suite designed to turn the friction of web-clipping into a Contextual Nutrient System for your AI Agent. Instead of hoarding links in a digital graveyard, Hermes Clipper feeds your research directly to your "Second Brain," allowing the Hermes Agent to categorize, cross-link, and synthesize your knowledge in real-time.

Why Hermes Clipper?

• Zero Friction: One-click from your browser, handled by an agent.
• Agent-First: Stop picking folders. Let Hermes decide where it belongs based on your vault's existing context.
• Token Sovereignty 2.0: Deeply optimized for LLM efficiency.
  • Smart Duplicate Detection: Local grep sieve prevents redundant Agent research.
  • Vault Structural Index: Auto-generated folder map eliminates expensive recursive listings.
  • Linguistic Compression: Built-in Caveman Mode support to slash LLM costs by ~75%.
• Local Sovereignty: Your data stays in your vault. Secure bridge with API key protection.

---

📖 Documentation

Explore the technical depth of the Hermes Clipper ecosystem:

• Architecture: Deep-dive into the Bridge Pattern and Agentic Ingestion.
• The Secret Sauce: How we achieve 75%+ token efficiency.
• Benchmark: Empirical tests of Agent speed and accuracy.
• Community & Inspirations: The giants we stand on.
• Migration Guide: Transitioning from Raindrop.io or Readwise.

---

🛠 The Suite

Hermes Clipper is composed of five modular components:

1. 🧠 The Brain (Skill): Optimized procedural logic for Hermes Agent. Now features Head Extraction (~4k chars) for categorization efficiency.
2. 📡 The Bridge (FastAPI): High-performance local gateway. Features secure X-API-Key handling and real-time Vault Index auto-syncing.
3. 🛰️ The Scout (Extension): Manifest V3 extension. Zero-config auto-linking via Native Messaging with async task tracking.
4. 🏡 The Garden (Plugin): Obsidian Ribbon interface for deep synthesis and automated file migration.
5. 🔨 The Hand (CLI): Command-line provisioning wizard, extracting "meat" via Mozilla Readability algorithm.

---

🚀 Getting Started

Prerequisites

• Hermes Agent installed and configured.
• Python 3.8+
• Obsidian

Installation

1. Bootstrap local env:

   git clone https://github.com/frostmute/hermes-clipper.git
   cd hermes-clipper
   ./scripts/bootstrap.sh

   This creates .venv, installs editable, and links hermes-clip into ~/.local/bin/.

2. Run Setup:

   hermes-clip setup

   Note: This generates your API Key, deploys the optimized Skill to Hermes, and builds your Vault Structural Index.

3. Configure Browser Integration:

   hermes-clip setup-browser-host

   Note: This command will interactively prompt for your Extension ID if it's not provided. You can find your Extension ID on chrome://extensions (enable Developer Mode).

4. Start the Bridge:

   hermes-clip serve --daemon

   Note: Use hermes-clip status to verify and hermes-clip stop to shut it down. The bridge now intelligently handles metadata interpolation (title, author, description, etc.) into your notes based on your template.md.

5. Install Browser Extension:

   • Open Chrome/Brave Extensions page (chrome://extensions).
   • Enable "Developer Mode" (top right).
   • Click "Load unpacked" and select the extension/ folder in this repo.
   • Linking: The extension will auto-discover your API Key via Native Messaging. No manual pasting required.

6. Install Obsidian Plugin:

   • Copy obsidian-plugin/ contents to <vault>/.obsidian/plugins/hermes-clipper/.
   • Enable in Obsidian settings and enter your API Key (run hermes-clip config to find it).

---

📖 Usage

Quick Clip

Click the ⚡ Hermes icon in your browser to send the current page to your Clippings/ folder.

Agent Research

Click Agent Research in the extension. Hermes will research the topic, check your vault for context, and file it intelligently.

Synthesis (Obsidian)

Click the 🧠 Brain icon in your Obsidian ribbon. Hermes will:

1. Read the note.
2. Fix formatting & typos.
3. Cross-link to other notes.
4. Move it from Clippings/ to a permanent home (e.g., Research/).

---

🛡 Security

Hermes Clipper uses a local-first bridge with:

• X-API-Key Header: All requests to the bridge require your unique key.
• CORS Restricted: Only listens to your browser extension and Obsidian app.
• Privacy: No cloud storage. No data leaks.

---

🌑 Philosophy: Agent-Growth

Every clip you save expands your Agent's context. By integrating clipping into your inherent workflow, you are building a sharper, more integrated AI that understands your research interests better with every note.

---

☕ Support

If Hermes Clipper has saved you a mountain of tokens or made your vault a better place, consider throwing some dollarbucks my way!

Support on Ko-fi

---

📜 Credits & License

• Caveman Mode: Methodology by Julius Brussee.
• Hermes Agent: The foundational intelligence ecosystem.

Licensed under the MIT License.

---

⚡ Build a better garden. Grunt.