Zero-Mem/Zero-mem

What is Zero-Mem?

Zero-Mem is a framework that gives AI agents a memory system — a way to store and retrieve past interactions so they can answer questions about them. The key idea is that most memory operations (building, organizing, finding, and checking evidence) happen without calling a large language model (LLM) at all. Only the final step — actually generating the answer — uses an LLM. This makes memory operations cheap and fast.

How it works

1. Store the original text. The system keeps the raw interaction traces (conversations or documents) as-is. It extracts entities (people, places, things) and encodes the text into vectors, but it does not create summaries or semantic triples.

2. Build two complementary structures:

   • An entity–context graph that shows how entities relate to each other.
   • A temporal hierarchy that preserves local context and time order.

3. Profile the query. When a question arrives, the system identifies cues like the subject, answer type, time references, and source boundaries to guide retrieval.

4. Retrieve evidence. It pulls candidates from both the graph and the hierarchy, then adds bounded supporting context (relational or local).

5. Calibrate and answer. It filters the evidence, sends it to a reader LLM (e.g., GPT-4o-mini), and applies deterministic checks on evidence support, answer type, and format.

What "zero-token" means

Memory construction, organization, routing, retrieval, evidence closure, and calibration use no LLM calls and no LLM input/output tokens. However, the encoder (BGE-M3), named-entity recognition (spaCy), storage, and the final question-answering inference do have costs.

Components

• run.py — the entry point for generating answers.
• ZeroMem — combines retrieval and the reader.
• ZeroMemConfig — holds runtime settings.
• ZeroMemReaderClient — manages final-QA requests and diagnostics.
• Supporting modules for indexing, embeddings, NER, query profiling, retrieval, evidence, reader, calibration, and data I/O.

Setup

• Install dependencies: pip install -r requirements.txt and download the spaCy model en_core_web_trf.
• Default models: BGE-M3 for dense encoding, gpt-4o-mini as the final reader (configurable via environment variables).
• The reader uses an OpenAI-compatible Chat Completions endpoint; you set the API key privately in your shell.
• GPU support requires a compatible PyTorch build and, for spaCy, CuPy.

Data formats

Two layouts are supported:

1. LoCoMo conversations — a single JSON array of conversation/QA data at the repository root (locomo10.json).
2. Prepared question–corpus pairs — two JSON arrays (questions.json and chunks.json) under a dataset directory, e.g., dataset/hotpotqa56K/ or dataset/hotpotqa224K/.

Reported results (from the manuscript)

Final-QA reader	LoCoMo F1	LoCoMo BLEU-1	HotpotQA 56K F1	HotpotQA 224K F1	HotpotQA 448K F1
GPT-4o-mini	59.15	52.96	72.07	66.43	65.04
Qwen2.5-14B-Instruct	57.57	51.41	68.58	65.47	61.02

These are manuscript-reported numbers, not new measurements of this release. The manuscript also reports 57.6% lower memory-operation time than the fastest compared baseline (LightMem), measured outside final QA.

Outputs

For fusion mode, each run produces prediction files (compact and raw), a run config, performance statistics, failure diagnostics (if any), and a log. Graph and hierarchy modes produce similarly named files. The entry point generates answers only — benchmark scoring is done separately.

Resuming runs

To resume an interrupted run, keep the original output directory (including the .jsonl and run_config.json files), set OUT to the exact path, and rerun only the Python generation command with --resume, using the same settings.

Notes

• The token budget for reader prompts uses an approximate whitespace-word count during evidence construction; actual token usage is reported separately when the provider returns it.
• Datasets and the Qwen serving environment are not bundled; you must supply them.
• The directory name hotpotqa224K does not automatically create a 224K-token context — you must prepare the corpus and boundaries to match the benchmark protocol.