# HAG: Hopfield-Augmented Generation

A retrieval-augmented generation system that replaces standard vector similarity search (FAISS top-k) with **iterative Modern Hopfield Network retrieval**.

## Quick Start

```bash
pip install -e ".[dev]"
pytest
```

## Core Idea

Standard RAG retrieves passages once via FAISS similarity. HAG iteratively refines the query in embedding space using Modern Continuous Hopfield Network dynamics:

```
q_{t+1} = M * softmax(beta * M^T * q_t)
```

This enables implicit multi-hop reasoning through energy minimization with convergence guarantees.

## Project Structure

- `hag/hopfield.py` — Core Hopfield retrieval module
- `hag/memory_bank.py` — Passage embedding storage
- `hag/retriever_hopfield.py` — Hopfield-based retriever
- `hag/retriever_faiss.py` — FAISS baseline retriever
- `hag/pipeline.py` — End-to-end RAG/HAG pipeline
- `hag/metrics.py` — Evaluation metrics (EM, F1, retrieval recall)
- `hag/energy.py` — Energy analysis utilities
- `scripts/` — Evaluation and analysis scripts
- `tests/` — Comprehensive test suite

## Running Tests

```bash
pytest tests/ -v
```

All tests run on CPU with synthetic data — no GPU or model downloads required.