RAG Memory Plugin for Hermes Agent

Production-grade Retrieval-Augmented Generation memory system with hybrid TF-IDF + Neural search, automatic context injection, and zero-configuration setup.

Features

• 🔍 Hybrid Search: TF-IDF + Neural retrieval with sqlite-vec and sentence-transformers
• 🪝 Auto-Capture: Hooks inject relevant context before LLM calls, capture responses after
• 🏷️ Namespace Isolation: Separate memory spaces for conversations, files, projects
• ⚡ Performance: Query caching, connection pooling, lazy loading
• 🔧 Zero-Config: Works out of the box, graceful fallback when models unavailable
• 📦 Pip Installable: Standard Python package with entry points
• 🚀 Fast: <2ms search time, 40-60% cache hit rate

Installation

From PyPI (Recommended)

# Basic (TF-IDF only)
pip install rag-memory-plugin

# Full (with Neural Search)
pip install rag-memory-plugin[neural]

From GitHub (Latest Development Version)

# Install directly from GitHub
pip install git+https://github.com/favouraka/rag-memory-plugin.git[neural]

# Or clone and install in editable mode
git clone https://github.com/favouraka/rag-memory-plugin.git
cd rag-memory-plugin
pip install -e ".[neural]"

Quick Start

1. Install Plugin

From PyPI:

pip install rag-memory-plugin[neural]

From GitHub:

pip install git+https://github.com/favouraka/rag-memory-plugin.git[neural]

2. Migrate Existing Data (Optional)

If you have a legacy ~/rag-system installation:

rag-memory migrate-from-legacy

3. Verify Installation

rag-memory doctor

Output:

✓ Database: /home/user/.hermes/plugins/rag-memory/rag_memory.db
✓ Documents: 168
✓ Embeddings: 168
✓ Mode: hybrid

4. Restart Hermes

The plugin auto-discovers via entry points. Just restart Hermes:

hermes

You should see in the banner:

Plugins (1): ✓ rag-memory v1.0.0 (4 tools, 4 hooks)

Usage

Via Hermes Tools

The plugin registers 4 tools that Hermes can use:

rag_search: Search memory by semantic similarity
rag_add_document: Add document to memory
rag_stats: Show database statistics
rag_flush: Flush write buffers

Example in Hermes:

You: What did we work on yesterday?
Hermes: [Uses rag_search tool] Let me check... [Retrieves relevant context]

Via Command Line

# Search memory
rag-memory search "AI agent"

# Health check
rag-memory doctor

# Export data
rag-memory export backup.json

# Import data
rag-memory import-data backup.json

As a Python Library

from rag_memory import RAGCore

# Initialize
rag = RAGCore()
rag.initialize()

# Add document
rag.add_document(
    content="Hermes is an AI agent",
    namespace="test",
    metadata={"source": "user"}
)

# Search
results = rag.search(
    "AI agent",
    namespace="test",
    limit=5
)

for result in results:
    print(f"{result['score']:.2f}: {result['content'][:100]}")

Configuration

Plugin configuration in Hermes ~/.hermes/config.yaml:

plugins:
  rag_memory:
    enabled: true
    mode: hybrid              # tfidf | neural | hybrid
    auto_capture: true        # Enable hooks
    cache_enabled: true       # Query caching
    cache_ttl: 300           # Cache lifetime (seconds)
    max_results: 10          # Max search results

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Hermes Agent                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │ RAG Memory Plugin                                  │  │
│  │                                                     │  │
│  │  ┌─────────────┐    ┌─────────────┐              │  │
│  │  │  Tools      │    │   Hooks     │              │  │
│  │  │ - rag_search│    │ - pre_llm   │              │  │
│  │  │ - rag_add   │    │ - post_llm  │              │  │
│  │  │ - rag_stats │    │ - session   │              │  │
│  │  └──────┬──────┘    └──────┬──────┘              │  │
│  │         │                    │                     │  │
│  │  ┌──────▼────────────────────▼──────┐            │  │
│  │  │         RAGCore                   │            │  │
│  │  │  ┌────────────────────────────┐  │            │  │
│  │  │  │ TF-IDF Index (sqlite-vec) │  │            │  │
│  │  │  └────────────────────────────┘  │            │  │
│  │  │  ┌────────────────────────────┐  │            │  │
│  │  │  │ Neural Embeddings          │  │            │  │
│  │  │  │ (sentence-transformers)    │  │            │  │
│  │  │  └────────────────────────────┘  │            │  │
│  │  │  ┌────────────────────────────┐  │            │  │
│  │  │  │ Query Cache (LRU)          │  │            │  │
│  │  │  └────────────────────────────┘  │            │  │
│  │  └─────────────────────────────────┘  │            │  │
│  └─────────────────────────────────────────┘            │
└─────────────────────────────────────────────────────────┘

Performance

Operation	Time	Notes
TF-IDF search	<10ms	No model required
Neural search	60-100ms	sentence-transformers
Cached search	<1ms	40-60% hit rate
Add document	20-50ms	With embedding generation

Development

Setup Development Environment

git clone https://github.com/yourname/rag-memory-plugin.git
cd rag-memory-plugin
pip install -e ".[dev]"

Run Tests

pytest tests/

Type Checking

mypy src/rag_memory

Linting

ruff check src/rag_memory

Migration from ~/rag-system

If you have a legacy ~/rag-system installation:

# Automatic migration
rag-memory migrate-from-legacy

# Or manual export/import
rag-memory export backup.json
rag-memory import-data backup.json

The migration script:

1. Connects to ~/rag-system/rag_data.db
2. Exports all documents with embeddings
3. Imports to ~/.hermes/plugins/rag-memory/rag_core.db
4. Verifies data integrity

License

MIT

Contributing

Contributions welcome! Please read CONTRIBUTING.md for details.

Support

• GitHub Issues: https://github.com/yourname/rag-memory-plugin/issues
• Docs: https://github.com/yourname/rag-memory-plugin/wiki