A reproducible long-term memory QA framework that structures retrieved evidence into a ledger before answer generation to improve multi-session reasoning.

Stars

430

7-day growth

No data

Forks

45

Open issues

2

License

MIT

Last updated

2026-07-28

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

It introduces a novel evidence-organization step (ledger) between retrieval and generation, and provides a one-command automatic memory wrapper for OpenAI clients, with visual demos and benchmark case replay.

Who it is for

  • Researchers studying long-term memory for LLMs
  • Developers integrating persistent memory into applications
  • AI engineers evaluating structured reasoning pipelines

Use cases

  • Building chatbots with persistent multi-session user memory
  • Conducting reproducible experiments on memory-augmented reasoning
  • Evaluating question answering over the LongMemEval benchmark
  • Adding automatic memory retain/recall to existing OpenAI-compatible applications

Strengths

  • Clear end-to-end pipeline: Retain → Recall → Organize → Answer → Judge
  • One-command automatic memory integration via wrap_openai() for both Responses and Chat Completions APIs
  • Visual demos (memory pipeline and benchmark case replay) that illustrate evidence organization
  • Two pipeline modes (ledger and self-evolution) for comparative study of structured evidence

Considerations

  • Requires PostgreSQL with pgvector extension
  • Depends on an OpenAI-compatible API for both LLM and embeddings
  • Not a standalone memory system; designed as a research framework with setup overhead
  • Peer-reviewed paper is not yet published (arXiv 'coming soon')

README quick start

Structured Memory Intelligence for Reliable Long-Horizon Reasoning

ShadowWeave Team

  

English · 中文


Overview

The Holographic Memory System (HMS) is a structured long-term memory layer for AI applications. It retains conversations and documents, extracts durable facts, links related entities and events, and recalls relevant context for later model calls.

HMS is designed for applications that need memory across sessions without placing an entire conversation history into every prompt.

One-Command Automatic Memory

HMS can wrap an existing OpenAI client so each model call automatically:

user input -> recall relevant memories -> inject context -> call the LLM
           -> retain the completed user/assistant exchange

Configure the model Base URL, API key, and model in .env, then run:

bash scripts/run_memory_demo.sh

The script starts PostgreSQL and HMS locally, waits for the memory API, installs the local SDK adapter in an isolated environment, and runs a two-turn demo. The first turn stores a user preference and project; the second turn recalls both without manually calling retain() or recall().

The application-side integration is one wrapper call:

from openai import OpenAI
from hms_litellm import wrap_openai

client = wrap_openai(
    OpenAI(),
    hms_api_url="http://127.0.0.1:18080",
    api_key="YOUR_HMS_API_KEY",
    bank_id="user-alice",
)

response = client.responses.create(
    model="gpt-4o-mini",
    input="What do you remember about my current project?",
)

wrap_openai() supports both client.responses.create(...) and client.chat.completions.create(...), including streaming. Use a stable, per-user bank_id; optionally set session_id to accumulate one conversation as a tracked HMS document.

Opt-in Image and Video Memory

The dataplane includes an opt-in openai_multimodal file parser. Images are validated and normalized locally; videos are decoded locally into a bounded, deterministic frame set. The visual description is rendered as grounded canonical Markdown and then enters the existing document, chunk, embedding, link, and recall pipeline. Raw video is never sent to the description provider.

The feature is disabled by default. Its current runtime support matrix is PostgreSQL; enabling the media path

Related repositories

Similar projects matched by category, topics, and programming language.

lopopolo
Featured
lopopolo GitHub avatar

harness-engineering

Harness Engineering is a methodology for improving coding agent outputs by carefully crafting the environment around them—providing curated context, tools, and executable constraints that encode an organization’s nonfunctional requirements and cumulative lessons.

AI & Machine LearningAI Agents
2,390
slvDev
Featured
slvDev GitHub avatar

esp32-ai

A 28.9 million parameter language model runs on an $8 ESP32-S3 microcontroller entirely on-device, generating simple stories at about 9.5 tokens per second.

AI & Machine LearningLarge Language Models
1,960
littledivy
Featured
littledivy GitHub avatar

mimic

mimic captures traffic from any iOS or web app and automatically generates a Python client library that lets you call the app's API like a regular library.

AI & Machine Learning
1,482