Initial implementation of HAG (Hopfield-Augmented Generation)HEADmaster

Core Hopfield retrieval module with energy-based convergence guarantees,
memory bank, FAISS baseline retriever, evaluation metrics, and end-to-end
pipeline. All 45 tests passing on CPU with synthetic data.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

1 files changed, 23 insertions, 0 deletions

diff --git a/TBD.md b/TBD.md
new file mode 100644
index 0000000..93b2771
--- /dev/null
+++ b/TBD.md
@@ -0,0 +1,23 @@
+# TBD — GPU Ready 后待完成
+
+## 1. Encoder 加 GPU 支持
+- `hag/encoder.py` 的 `Encoder` 类加 `device` 参数
+- `_load_model()` 时 `.to(device)`，推理时 tensor 搬到 GPU
+- batch encode 结果 `.cpu()` 回传
+
+## 2. 数据准备脚本
+- 新建 `scripts/prepare_hotpotqa.py`
+- 从 HuggingFace 下载 HotpotQA，提取所有 context passages
+- 去重，存成 memory bank 可消费的格式（JSONL 或直接构建 memory_bank.pt）
+- 同时导出 questions + gold answers + gold passage indices 供评测用
+
+## 3. 对比评测脚本
+- 新建 `scripts/run_comparison.py`
+- 同一个 memory bank，分别跑 FAISS 和 Hopfield retriever
+- 同一个 LLM 生成答案
+- 输出对比表格：EM / F1 / Retrieval Recall@k
+- 支持不同 beta、max_iter 的 sweep
+
+## 4. run_eval.py 补 FAISS 路径
+- 当前 `run_eval.py` 只接 memory_bank，FAISS 模式需要额外从 memory_bank 构建 FAISS 索引
+- 加上自动转换逻辑