Metadata-Version: 2.1
Name: rag-memory-plugin
Version: 1.0.0
Summary: Production-grade RAG memory system for Hermes Agent with hybrid TF-IDF + Neural retrieval, auto-capture, and zero-configuration setup
Author: Clawford Orji
License: MIT
Keywords: rag,retrieval,memory,hermes,agent,neural-search,tfidf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click >=8.0
Requires-Dist: numpy >=1.24.0
Requires-Dist: pydantic >=2.0
Requires-Dist: pyyaml >=6.0
Requires-Dist: rich >=13.0
Requires-Dist: scikit-learn >=0.24.0
Requires-Dist: sqlite-vec >=0.1.0
Provides-Extra: all
Requires-Dist: rag-memory-plugin[dev,neural] ; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy >=1.8 ; extra == 'dev'
Requires-Dist: pytest-cov >=4.0 ; extra == 'dev'
Requires-Dist: pytest >=8.0 ; extra == 'dev'
Requires-Dist: ruff >=0.4 ; extra == 'dev'
Provides-Extra: neural
Requires-Dist: sentence-transformers >=2.2.0 ; extra == 'neural'

# RAG Memory Plugin for Hermes Agent

[![PyPI version](https://badge.fury.io/py/rag-memory-plugin.svg)](https://badge.fury.io/py/rag-memory-plugin)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![GitHub](https://img.shields.io/badge/github-favouraka%2Frag--memory--plugin-blue.svg)](https://github.com/favouraka/rag-memory-plugin)

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)
```bash
# Basic (TF-IDF only)
pip install rag-memory-plugin

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

### From GitHub (Latest Development Version)
```bash
# 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:**
```bash
pip install rag-memory-plugin[neural]
```

**From GitHub:**
```bash
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:

```bash
rag-memory migrate-from-legacy
```

### 3. Verify Installation
```bash
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:

```bash
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:

```text
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

```bash
# 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

```python
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`:

```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

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

### Run Tests

```bash
pytest tests/
```

### Type Checking

```bash
mypy src/rag_memory
```

### Linting

```bash
ruff check src/rag_memory
```

## Migration from ~/rag-system

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

```bash
# 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
