Structured Memory Intelligence for Reliable Long-Horizon Reasoning addresses the challenge of improving large language model (LLM) reasoning capabilities over extended memory contexts. It provides a reproducible framework, the Holographic Memory System (HMS), designed for researchers and engineers studying LLM memory and long-term reasoning. HMS enhances LLM performance by organizing retrieved memories into a structured, answer-time evidence format, enabling more reliable and grounded responses in complex, multi-session scenarios.

How It Works

HMS operates by wrapping an existing OpenAI client, automatically managing memory recall and context injection. Before each LLM call, it retrieves relevant memories, structures them into an evidence ledger that explicitly encodes temporal, source, and state information, and then feeds this organized context to the LLM. This approach moves beyond simple fact retrieval, aiming to improve the LLM's ability to connect disparate pieces of information across sessions, manage evolving states, and handle temporal nuances accurately.

Quick Start & Requirements

To run the demo, execute bash scripts/run_memory_demo.sh. For full benchmark reproduction, copy .env.example to .env and configure it with your PostgreSQL database URL, OpenAI API keys (or compatible service URLs/models), and the LongMemEval dataset path. Key prerequisites include a PostgreSQL database with the pgvector extension, Python, and an OpenAI API key or equivalent. The setup involves configuring multiple LLM roles (retain, recall, answer, judge, embeddings) within the .env file.

Highlighted Details

• Reproducible Evaluation Pipeline: Follows a complete Text -> Dataset -> Retain -> Recall -> Organize -> Answer -> Judge workflow for rigorous evaluation.
• Two Pipeline Modes: Offers a ledger pipeline for structured evidence organization and a self_evolution pipeline that adds an answer-time controller to address diagnosed failure patterns.
• Interactive Demos: Includes docs/memory_pipeline_demo.html for visualizing the memory pipeline and docs/benchmark_case_replay.html for an auto-playing replay of a single multi-session case.
• Seamless Integration: Provides a wrap_openai Python function for straightforward integration with the standard openai client, supporting both responses.create and chat.completions.create calls.

Maintenance & Community

This repository is developed by the ShadowWeave Team. Specific details regarding active contributors, community channels (like Discord or Slack), or a public roadmap are not provided in the README.

Licensing & Compatibility

The license for this project is not specified in the provided README content. This omission requires further investigation for compatibility, especially for commercial use or integration into closed-source projects.

Limitations & Caveats

The system requires a configured PostgreSQL database with pgvector and relies heavily on OpenAI API keys or compatible endpoints for LLM interactions. The setup process involves detailed configuration in a .env file, and the absence of a stated license presents a significant adoption blocker.