moonlight-lupin/agent-skills/library-rag

Library RAG

Semantic search over ~/.hermes/library/ using Nemotron-3-Embed-1B embeddings (via NVIDIA NIM) stored in sqlite-vec. Enables meaning-based retrieval across any text corpus — books, documents, reference works — in any language.

Architecture

NVIDIA NIM API (nemotron-3-embed-1b, 2048-dim)
        │
        ▼
~/.hermes/library/rag_index.db (sqlite-vec)
  ├── chunks table      — text + metadata (source, book, chapter, section)
  ├── vec_chunks table  — L2-normalized vector embeddings
  └── indexed_files     — SHA-256 hash tracking for incremental updates
 
MCP Server (mcp_server.py)
  ├── search(query, top_k, source_type)  — semantic search, auto-available
  ├── stats()                             — index statistics
  └── add_book(file_path, ...)            — EPUB/PDF → md → index in one call

Onboarding workflow (run this the first time a user sets up the skill)

When a user wants to start using Library RAG, walk them through this sequence. Use AskUserQuestion for the decisions marked ASK — don't assume paths or silently create directories outside the home folder.

Step 1 — Check prerequisites

python3 --version                                   # need 3.9+
python3 -c "import sqlite_vec; print('sqlite-vec ok')" 2>&1
test -n "$NVIDIA_API_KEY" && echo "key in env" || grep -qs NVIDIA_API_KEY ~/.hermes/.env && echo "key in .env" || echo "NO API KEY"

• If sqlite-vec import fails → run pip install -r requirements.txt (add

--break-system-packages on externally-managed Python). See README "Installation".

• If NO API KEY → help the user create a free NVIDIA NIM key at

<https://build.nvidia.com/nvidia/nemotron-3-embed-1b>, then store it: echo 'NVIDIA_API_KEY=nvapi-...' >> ~/.hermes/.env. (Legacy OpenRouter keys still work: if only OPENROUTER_API_KEY is set, load_api_key() auto-switches to the bge-m3 OpenRouter endpoint.)

Step 2 — Define directories (ASK)

Three locations drive everything. Confirm them with the user and export the env vars (persist in their shell profile). Defaults in parentheses:

Recommended layout (keep raw/text out of LIBRARY_ROOT — see pitfall below):

$BOOKS_DIR/                        staging — NOT indexed
  raw/        original EPUBs/PDFs
  text/       extracted plain text
$LIBRARY_ROOT/                     indexed — scanned recursively
  rag_index.db
  <source_type>/                   top-level dir name becomes the "source type"
    markdown/<slug>/chapters/*.md  the structured files that get embedded

Pitfall — avoid double-indexing: discover_files() indexes every .md and

.txt under LIBRARY_ROOT. If both the extracted .txt and the converted .md of the

same book live under LIBRARY_ROOT, the content is embedded twice. Keep only one

representation (prefer the structured .md) under LIBRARY_ROOT; keep raw + text staging

in BOOKS_DIR outside it.

Create the chosen dirs:

mkdir -p "$LIBRARY_ROOT" "$BOOKS_DIR/raw" "$BOOKS_DIR/text"

Step 3 — Add the first content & build the index

• EPUB/PDF via MCP (if the server is configured): call add_book(...) — it converts and

indexes in one step.

• Manual: drop source files in $BOOKS_DIR/raw, convert to structured markdown under

$LIBRARY_ROOT/<source_type>/ (see convert_epub_library.py and references/epub-conversion.md), then:

python3 scripts/rag_index.py --dry-run     # preview chunk counts, no API cost
python3 scripts/rag_index.py               # incremental build
python3 scripts/rag_query.py --stats       # confirm chunks landed
python3 scripts/rag_query.py "a test query"

Step 4 — Automated scanning/conversion/indexing (ASK)

Ask the user whether they want new files indexed automatically or manually:

• Manual (default, recommended to start): they run python3 scripts/rag_index.py

after adding files. Incremental + SHA-256 tracking means re-runs are cheap and only touch new/changed files. No setup needed.

• Automated (cron): schedule a periodic incremental index. Only offer this once Step 3

works end-to-end. Example — index nightly at 02:00 and log output:

``bash # crontab -e (adjust the repo path and env vars) 0 2 * * * NVIDIA_API_KEY=nvapi-... LIBRARY_ROOT=$HOME/.hermes/library \ /usr/bin/python3 $HOME/library-rag/scripts/rag_index.py >> $HOME/.hermes/rag_index.log 2>&1 ``

If they also want EPUBs auto-converted before indexing, chain a conversion step ahead of rag_index.py in the same cron line (or a small wrapper script). On macOS, launchd / a launchd plist is the more reliable equivalent of cron.

Cron cautions to mention:

• Cron has a minimal environment — set NVIDIA_API_KEY, LIBRARY_ROOT, and use an

absolute python3 path (or activate the venv inside a wrapper script).

• Never overlap two --rebuild runs on the same DB (see Pitfalls). A nightly incremental

run is safe; a full --rebuild should stay manual.

• NIM embeddings are free on the NVIDIA free trial tier; the log still shows token usage.

After onboarding, summarize for the user: the three paths chosen, where the DB lives, and whether indexing is manual or scheduled.

MCP Tools (auto-available in every conversation)

Once configured in config.yaml, these tools are available as mcp_library_rag_search, mcp_library_rag_stats, mcp_library_rag_add_book.

Config

# ~/.hermes/config.yaml
mcp_servers:
  library_rag:
    command: "python3"
    args: ["~/.hermes/skills/research/library-rag/scripts/mcp_server.py"]
    timeout: 60

Restart the gateway after adding.

search

mcp_library_rag_search(query="your search query", top_k=10)
mcp_library_rag_search(query="search terms", source_type="my-source-type")

Returns JSON array of results with similarity, source_type, book, chapter, section_title, text.

stats

mcp_library_rag_stats()
→ {"total_chunks": 78000, "files_indexed": 1383, "by_source": {...}}

add_book

mcp_library_rag_add_book(
    file_path="/path/to/book.epub",   # or /path/to/doc.pdf
    book_slug="my-new-book",
    author="Author Name",
    title="Book Title",
    year="2024"
)

Converts EPUB → chapters or PDF → pages, then indexes them. One-call workflow for adding new books to the library.

Scripts (for batch operations)

rag_index.py — Indexer

# Index all new/changed files (incremental — SHA-256 hash tracking)
python3 scripts/rag_index.py
 
# Full rebuild (drop everything, re-index from scratch)
python3 scripts/rag_index.py --rebuild
 
# Dry run (show what would be indexed, no API calls)
python3 scripts/rag_index.py --dry-run
 
# Index only one source type
python3 scripts/rag_index.py --source my-source-type
 
# Prune DB rows for files deleted/moved out of the library, then shrink the file
python3 scripts/rag_index.py --prune-missing --vacuum

When to use:

• After adding new files to the library → run incremental (default)
• After changing chunking strategy → run --rebuild
• To estimate cost/time → run --dry-run first
• After deleting/moving files out of the library → run --prune-missing

(removes orphaned chunks + vectors so the DB doesn't keep dead rows; safe alongside incremental indexing — only files absent from disk are retired)

• After a --rebuild or a large --prune-missing → run --vacuum to shrink

the DB file (SQLite reuses freed pages but doesn't shrink the file otherwise)

rag_query.py — CLI Query

python3 scripts/rag_query.py "your search query"
python3 scripts/rag_query.py "search terms" --top-k 5
python3 scripts/rag_query.py "query" --source my-source-type --verbose
python3 scripts/rag_query.py --stats

Can also be imported:

from rag_query import search
results = search("query text", top_k=10)

Conversion Tools

EPUB → Markdown (scripts/convert_epub_library.py)

Extracts text from EPUB files and splits into per-chapter Markdown with YAML frontmatter. Runnable as a CLI or importable as convert_epub() — the same implementation backs the MCP add_book tool, so there is one conversion code path.

python3 scripts/convert_epub_library.py \
    --epub book.epub --slug my-book --title "Book Title" --author "Author" --year 2024 \
    --md-root ~/.hermes/library/books/markdown   # under LIBRARY_ROOT so it gets indexed

Raw EPUB + extracted text stage under $BOOKS_DIR (outside LIBRARY_ROOT); only the structured markdown is written to --md-root, so the raw text is never double-indexed.

Chapter detection tries several styles (CHAPTER 12 / CHAPTER One / PART IV / 12. Title / bare 12\nTitle), picking the first that confidently applies, and guards against date/page-number false positives. Before trusting a conversion, eyeball convert_epub_library.audit_chapter_markers(text) — every entry should be a real chapter, not a date or page number.

Key pitfalls (see references/epub-conversion.md for full details):

1. Multiple TOC ghosts: Large EPUBs produce multiple table-of-contents blocks. Skip all when finding chapter headings in body text.
2. CHAPTER N vs N. Title: EPUBs use different heading patterns in TOC vs body. Match the BODY pattern.
3. Title + subtitle leak into YAML: Use only the main title for the title: field.
4. Slug truncation: Truncate slugs to 60 chars (preserving the chNN- prefix).
5. Page-number blocks: Some EPUBs extract huge blocks of standalone page numbers. Detect and exclude.
6. Post-processing pass: Always verify every .md file has valid YAML frontmatter.

PDF → Markdown (scripts/convert_pdf_library.py)

Extracts text and tables with pdfplumber. Each page → a ## Page N section (so the markdown chunker yields per-page citations); tables → **[Table N]** blocks. CLI or convert_pdf(); it also backs add_book for .pdf inputs.

python3 scripts/convert_pdf_library.py \
    --pdf doc.pdf --slug my-doc --title "Doc" --author "Author" --year 2024 \
    --md-root ~/.hermes/library/books/markdown

The table block is display-only: clean_for_embedding strips **[Table N]** and rows ending in <br> from the embedding input (the page's narrative text already carries the table content linearly), so tables stay searchable without being embedded twice.

Built-in chunkers (rag_index.py)

For domain-specific formats (PDFs, XML, JSON), write a custom chunker and register it in discover_files(). See references/chunking-strategies.md for patterns.

Adding new books to the library

Quick path (EPUB/PDF via MCP)

Use mcp_library_rag_add_book — it dispatches on extension and handles EPUB/PDF → md → index in one call.

Manual path

1. Convert to structured Markdown with the converter CLI for the format. Both stage

the raw file + extracted text under $BOOKS_DIR (outside LIBRARY_ROOT, so they're not indexed) and write markdown to --md-root: