HMLR (Hierarchical Memory Lookup & Routing) provides a state-aware, long-term memory architecture for AI agents, addressing limitations of brute-force context windows and vector-only RAG. It guarantees verified multi-hop, temporal, and cross-topic reasoning, even with mini-class LLMs, achieving perfect faithfulness and recall on adversarial benchmarks. This enables robust AI agents requiring reliable, complex long-term memory and policy enforcement.

How It Works

HMLR replaces fragile RAG with a structured, state-aware memory system. Its core approach involves hierarchical memory, state-awareness, and a routing mechanism to resolve conflicting facts, enforce persistent constraints, and perform true multi-hop reasoning. This architecture allows HMLR to achieve perfect faithfulness and recall using only mini-tier LLMs (e.g., GPT-4.1-mini), validating the thesis that superior architecture can outperform larger models with poorly structured context. Key components include a ChunkEngine, Scribe Agent for user profiles, FactScrubber, LatticeCrawler for retrieval, Governor for routing, and ContextHydrator for prompt assembly.

Quick Start & Requirements

• Prerequisites: Python 3.10+, OpenAI API key (GPT-4.1-mini), optional LangSmith API key.
• Installation: Clone the repository, pip install -r requirements.txt, configure .env with API keys.
• Running: Execute python main.py for the interactive console.
• Testing: Navigate to the tests directory and run pytest commands (e.g., pytest ragas_test_8_multi_hop.py).
• Docs/Verification: LangSmith records for benchmark proof: https://smith.langchain.com/public/4b3ee453-a530-49c1-abbf-8b85561e6beb/d.

Highlighted Details

• Achieves perfect (1.00) Faithfulness and Context Recall across adversarial multi-hop, temporal-conflict, and cross-topic invariance benchmarks using only a mini-tier model (gpt-4.1-mini).
• Verified via RAGAS, including passing "The Hydra of Nine Heads" benchmark (0% historical pass rate) using pure contextual memory without RAG retrieval.
• Prioritizes Recall Safety, Temporal Correctness, and State Coherence over token minimization, resulting in Context Precision scores from 0.27–0.88 by retrieving entire memory "Bridge Blocks."
• Empirically validates the core thesis: "Correct architecture can outperform large models fed with poorly structured context."

Maintenance & Community

No specific details regarding contributors, sponsorships, or community channels (Discord/Slack) were found in the provided README excerpt.

Licensing & Compatibility

The license type is not explicitly stated in the provided README excerpt.

Limitations & Caveats

Context Precision scores are intentionally lower (0.27–0.88) to prioritize comprehensive memory retrieval (entire Bridge Blocks) over strict token minimization, ensuring Recall Safety, Temporal Correctness, and State Coherence. The project claims to be the first publicly documented, open-source memory architecture demonstrating these guarantees under formal RAGAS evaluation with mini-class models, acknowledging that proprietary systems might possess similar capabilities. Operation requires an OpenAI API key, implying potential costs and dependency on external services.