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:
- Connects to
~/rag-system/rag_data.db - Exports all documents with embeddings
- Imports to
~/.hermes/plugins/rag-memory/rag_core.db - Verifies data integrity
License
MIT
Contributing
Contributions welcome! Please read CONTRIBUTING.md for details.
Support
Metadata
Release files for rag-memory-plugin 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rag_memory_plugin-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for rag_memory_plugin-1.0.0-py3-none-any.whl |
Release files / rag_memory_plugin-1.0.0-py3-none-any.whl
| Download URL | rag_memory_plugin-1.0.0-py3-none-any.whl |
|---|---|
| Size | 48.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ebbbce054892eca8155c75f911b1b7538d319e7ca417f093e236e13d14eb37f
|
|
BLAKE2b-256 checksum How to use checksums |
abca98b87b4f11402c5589b3b9a672ffc71b7c3cbe5c581c8235f56fcb73786c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for rag-memory-plugin 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.