{"id":51492059,"url":"https://github.com/evermind-ai/hypermem","last_synced_at":"2026-07-07T12:02:08.239Z","repository":{"id":362151701,"uuid":"1256900649","full_name":"EverMind-AI/HyperMem","owner":"EverMind-AI","description":"A hypergraph-based hierarchical memory architecture that captures high-order associations through hyperedges. Organizes memory into topic, event, and fact layers for coarse-to-fine long-term conversation retrieval.","archived":false,"fork":false,"pushed_at":"2026-06-02T21:26:14.000Z","size":121,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T23:15:29.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EverMind-AI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T07:22:33.000Z","updated_at":"2026-06-02T21:26:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/EverMind-AI/HyperMem","commit_stats":null,"previous_names":["evermind-ai/hypermem"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/EverMind-AI/HyperMem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FHyperMem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FHyperMem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FHyperMem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FHyperMem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EverMind-AI","download_url":"https://codeload.github.com/EverMind-AI/HyperMem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FHyperMem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35226918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-07T12:02:04.857Z","updated_at":"2026-07-07T12:02:08.233Z","avatar_url":"https://github.com/EverMind-AI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperMem: Hypergraph Memory for Long-Term Conversations\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/paper-ACL%202026-b31b1b.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.12+-blue.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nOfficial implementation of our ACL 2026 paper **HyperMem: Hypergraph Memory for Long-Term Conversations**.\n\nLong-term memory for conversational agents requires modelling *high-order associations*, i.e., joint dependencies among multiple related episodes and facts, which pairwise relations in existing RAG and graph-based memory systems cannot capture. HyperMem addresses this by structuring memory as a three-level hypergraph (**topics → episodes → facts**) connected through weighted hyperedges, and retrieving information via a coarse-to-fine top-down traversal.\n\nOn the LoCoMo benchmark, HyperMem reaches **92.73% LLM-as-a-judge accuracy**, outperforming the strongest RAG baseline (HyperGraphRAG, 86.49%) by **+6.24%** and the strongest memory system (MemOS, 75.80%) by **+16.93%**.\n\n---\n\n## Method\n\n\u003cp align=\"center\"\u003e\u003cem\u003eThree-level hypergraph with hyperedges linking nodes of the same level.\u003c/em\u003e\u003c/p\u003e\n\nGiven a dialogue stream $X = \\{x_t\\}_{t=1}^T$, HyperMem constructs a memory hypergraph\n\n$$\\mathcal{H} = (\\mathcal{V}^T \\cup \\mathcal{V}^E \\cup \\mathcal{V}^F,\\; \\mathcal{E}^E \\cup \\mathcal{E}^F),$$\n\nwhere $\\mathcal{V}^T, \\mathcal{V}^E, \\mathcal{V}^F$ denote topic, episode and fact nodes respectively. Episode hyperedges $\\mathcal{E}^E$ connect episode nodes under the same topic with weights $w^E \\in [0,1]$; fact hyperedges $\\mathcal{E}^F$ connect fact nodes belonging to the same episode with weights $w^F \\in [0,1]$.\n\n| Level | Node       | Semantics                                                     |\n|:-----:|:-----------|:--------------------------------------------------------------|\n| L3    | **Topic**  | Long-horizon theme grouping topically related episodes        |\n| L2    | **Episode**| Temporally contiguous dialogue segment describing one event   |\n| L1    | **Fact**   | Atomic queryable knowledge unit extracted from an episode     |\n\n### Hypergraph Construction\n\n1. **Episode Detection**: an LLM-driven streaming boundary detector partitions the raw dialogue into semantically complete *episodes*, each summarised and timestamped.\n2. **Topic Aggregation**: streaming topic matching against historical topics lazily groups related episodes under shared *topics*; new topics are created when no sufficient match exists.\n3. **Fact Extraction**: atomic *facts* are extracted from each episode (potential queries, keywords, summary), then bound to facts in the same episode via a weighted hyperedge.\n\n### Hypergraph Embedding Propagation\n\nNode embeddings are refined by aggregating information from incident hyperedges. A hyperedge embedding is computed as an attention-weighted sum of its member nodes,\n\n$$\\mathbf{h}_e = \\sum_{v \\in V(e)} \\alpha_{e,v} \\mathbf{h}_v,\\quad \\alpha_{e,v} = \\frac{\\exp(w_{e,v})}{\\sum_{u \\in V(e)} \\exp(w_{e,u})},$$\n\nand each node is updated as $\\mathbf{h}'_v = \\mathbf{h}_v + \\lambda \\cdot \\mathrm{Agg}_{e \\in \\mathcal{N}(v)}(\\mathbf{h}_e)$ with $\\lambda = 0.5$.\n\n### Coarse-to-Fine Retrieval\n\nFor a query $q$, retrieval proceeds top-down:\n\n* **Stage 1, Topic Retrieval**: BM25 and dense rankings are fused by Reciprocal Rank Fusion,\n\n  $$\\mathrm{RRF}(d) = \\sum_{m=1}^{M} \\frac{1}{k + \\mathrm{rank}_m(d)},$$\n\n  and the top-$k^T$ topics are kept after optional reranking.\n* **Stage 2, Episode Retrieval**: episodes in the topic subgraph are scored and the top-$k^E$ are retained.\n* **Stage 3, Fact Retrieval**: facts linked to the retained episodes are scored and the top-$k^F$ are used as evidence.\n\nThe final answer is generated by an LLM conditioned on the retrieved episodes (with their summaries) and facts.\n\n---\n\n## Installation\n\nHyperMem is tested with Python 3.12 and CUDA 12.1.\n\n```bash\ngit clone https://github.com/\u003corg\u003e/HyperMem.git\ncd HyperMem\n\nconda create -n hypermem python=3.12 -y\nconda activate hypermem\npip install -r requirements.txt\n```\n\n### Environment variables\n\nCreate a `.env` file at the repository root:\n\n```bash\n# LLM backend (OpenAI-compatible; we use OpenRouter in the paper)\nOPENROUTER_API_KEY=sk-...\n\n# Local model endpoints\nEMBEDDING_BASE_URL=http://localhost:11810/v1/embeddings\nRERANKER_BASE_URL=http://localhost:12810\n```\n\n### Local model services\n\nHyperMem uses **Qwen3-Embedding-4B** for semantic encoding and **Qwen3-Reranker-4B** for reranking. Both are served via vLLM:\n\n```bash\nbash scripts/serve_embedding.sh   # GPUs 0-3, port 11810\nbash scripts/serve_reranker.sh    # GPUs 4-7, port 12810\n```\n\n---\n\n## Reproducing the paper\n\nThe full LoCoMo evaluation pipeline is launched with a single command:\n\n```bash\nbash scripts/run_eval.sh\n```\n\nThe script sequentially runs six stages; all artefacts are written under `results/\u003cexperiment_name\u003e/`.\n\n| Stage | Script                              | Purpose                                         |\n|:-----:|:------------------------------------|:------------------------------------------------|\n| 1     | `stage1_memory_extraction.py`       | Episode detection from raw dialogues            |\n| 2     | `stage2_hypergraph_extraction.py`   | Topic aggregation + fact extraction + hypergraph construction |\n| 3     | `stage3_hypergraph_index.py`        | BM25 and dense indices over the hypergraph      |\n| 4     | `stage4_hypergraph_retrieval.py`    | Top-down hierarchical retrieval                 |\n| 5     | `stage5_response.py`                | LLM answer generation from retrieved evidence   |\n| 6     | `stage6_eval.py`                    | LLM-as-judge evaluation (3 rounds, averaged)    |\n\nIndividual stages can be run via:\n\n```bash\npython hypermem/main/eval.py --stages 4 5 6\n```\n\n### Configuration\n\nAll hyper-parameters live in [`hypermem/config.py`](hypermem/config.py) and can be overridden through environment variables:\n\n```bash\nexport HYPERMEM_EXPERIMENT_NAME=\"HyperMem-v3\"\nexport HYPERMEM_USE_RERANKER=false\nexport HYPERMEM_INITIAL_CANDIDATES=100       # pre-fusion candidate pool\nexport HYPERMEM_TOPIC_TOP_K=15               # k^T\nexport HYPERMEM_EPISODE_TOP_K=25             # k^E\nexport HYPERMEM_FACT_TOP_K=30                # k^F\n```\n\nThis setting uses $\\lambda = 0.5$, $(k^T, k^E, k^F) = (15, 25, 30)$, BM25 + dense retrieval with RRF ($k = 60$), and sum aggregation for hyperedge embedding propagation.\n\n---\n\n## Results\n\n### LoCoMo benchmark\n\nAccuracy is reported as the LLM-as-judge score (GPT-4o-mini), averaged over 3 evaluation rounds.\n\n| Method              | Single-hop | Multi-hop | Temporal | Open Domain | **Overall** |\n|:--------------------|:----------:|:---------:|:--------:|:-----------:|:-----------:|\n| GraphRAG            |   79.55    |   54.96   |  50.16   |    58.33    |    67.60    |\n| LightRAG            |   86.68    |   84.04   |  60.75   |    71.88    |    79.87    |\n| HippoRAG 2          |   86.44    |   75.89   |  78.50   |    66.67    |    81.62    |\n| HyperGraphRAG       |   90.61    |   80.85   |  85.36   |    70.83    |    86.49    |\n| OpenAI              |   63.79    |   42.92   |  21.71   |    63.22    |    52.90    |\n| LangMem             |   62.23    |   47.92   |  23.43   |    72.20    |    58.10    |\n| Zep                 |   61.70    |   41.35   |  49.31   |    76.60    |    65.99    |\n| A-Mem               |   39.79    |   18.85   |  49.91   |    54.05    |    48.38    |\n| Mem0                |   67.13    |   51.15   |  55.51   |    72.93    |    66.88    |\n| Mem0$^g$            |   65.71    |   47.19   |  58.13   |    75.71    |    68.44    |\n| MIRIX               |   85.11    |   83.70   |  88.39   |    65.62    |    85.38    |\n| Memobase            |   73.12    |   64.65   |  81.20   |    53.12    |    72.01    |\n| MemU                |   66.34    |   63.12   |  27.10   |    50.56    |    56.55    |\n| MemOS               |   81.09    |   67.49   |  75.18   |    55.90    |    75.80    |\n| **HyperMem (Ours)** | **96.08**  | **93.62** |**89.72** |    70.83    |  **92.73**  |\n\n---\n\n## Project Structure\n\n```\nHyperMem/\n├── hypermem/\n│   ├── config.py                 # Experiment configuration\n│   ├── types.py                  # Episode / Topic / Fact data classes\n│   ├── structure.py              # Hypergraph nodes and hyperedges\n│   ├── extractors/               # LLM-driven extraction modules\n│   │   ├── episode_extractor.py\n│   │   ├── topic_extractor.py\n│   │   ├── fact_extractor.py\n│   │   └── hypergraph_extractor.py\n│   ├── llm/                      # OpenAI-compatible LLM / embedding / reranker clients\n│   ├── prompts/                  # Prompt templates (episode / topic / fact / answer)\n│   ├── utils/                    # Utility functions\n│   └── main/                     # Six-stage pipeline entry points\n├── scripts/\n│   ├── run_eval.sh               # End-to-end evaluation driver\n│   ├── serve_embedding.sh        # Qwen3-Embedding-4B server\n│   └── serve_reranker.sh         # Qwen3-Reranker-4B server\n├── data/                         # LoCoMo-10 and auxiliary benchmarks\n├── results/                      # Per-experiment artefacts\n├── requirements.txt\n└── README.md\n```\n\nEach experiment directory under `results/` contains the extracted `episodes/`, `topics/`, `facts/`, the built `hypergraphs/`, `bm25_index/`, `vectors/`, along with `search_results.json`, `retrieval_logs.json`, `responses.json`, and the final `judged.json`.\n\n---\n\n## Citation\n\nIf HyperMem is useful in your research, please cite our paper:\n\n```bibtex\n@inproceedings{yue2026hypermem,\n  title     = {HyperMem: Hypergraph Memory for Long-Term Conversations},\n  author    = {Yue, Juwei and Hu, Chuanrui and Sheng, Jiawei and Zhou, Zuyi and Zhang, Wenyuan and Liu, Tingwen and Guo, Li and Deng, Yafeng},\n  booktitle = {Proceedings of the 64th Annual Meeting of the Association for Computational Linguistics (ACL)},\n  year      = {2026}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevermind-ai%2Fhypermem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevermind-ai%2Fhypermem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevermind-ai%2Fhypermem/lists"}