portable-rag-per-skill

Portable RAG: Per-Skill Standalone Index

The default library-rag setup uses a shared DB at ~/.hermes/library/rag_index.db with an MCP server registered in config.yaml. This is good for a permanent library but creates two problems for skills that should be self-contained:

1. Not portable — moving the skill to another machine breaks the DB path
2. MCP dependency — requires config.yaml registration, not self-contained

The Portable Pattern

Instead of the shared DB + MCP approach, create a standalone RAG index inside the skill's own references/ directory:

Key Differences from Library RAG

Aspect	Library RAG	Portable RAG
DB location	~/.hermes/library/rag_index.db	<skill>/references/rag_index.db
Path resolution	Hardcoded LIBRARY_ROOT	Path(__file__).resolve().parent.parent
DB override	None	--db flag or env var
API key	.env only	NVIDIA_API_KEY env var OR .env (OpenRouter key as fallback)
MCP server	Yes (config.yaml dependency)	No — import rag_query.search() directly
Chunker	Source-specific	Domain-specific (headings, sections, etc.)
Portable	No	Yes — zip the folder, drop on another machine, done

Implementation: Path Resolution

# All paths resolve from the script's own location — no hardcoded paths
SKILL_DIR = Path(__file__).resolve().parent.parent
REFERENCES_DIR = Path(os.environ.get('SKILL_REFERENCES_DIR', SKILL_DIR / 'references'))
DB_PATH = Path(os.environ.get('SKILL_RAG_DB', REFERENCES_DIR / 'rag_index.db'))
ENV_PATH = os.environ.get('HERMES_ENV', os.path.expanduser('~/.hermes/.env'))

Implementation: API Key Loading

def load_api_key():
    # Prefer NVIDIA NIM key; fall back to legacy OpenRouter key
    for env_var in ('NVIDIA_API_KEY', 'OPENROUTER_API_KEY'):
        key = os.environ.get(env_var)
        if key:
            return key
    env_path = Path(ENV_PATH)
    if env_path.exists():
        for line in env_path.read_text().splitlines():
            if line.startswith('#') or '=' not in line:
                continue
            name, _, value = line.partition('=')
            if name.strip() in ('NVIDIA_API_KEY', 'OPENROUTER_API_KEY'):
                return value.strip().strip('"').strip("'")
    raise ValueError(f"No NVIDIA_API_KEY (or OPENROUTER_API_KEY) found in env or {ENV_PATH}")