README.md

# DeMemWM

This repo is forked from [Boyuan Chen](https://boyuan.space/)'s research template [repo](https://github.com/buoyancy99/research-template). By its MIT license, you must keep this sentence in `README.md` and the `LICENSE` file to credit the author.

DeMemWM is a Memory-DiT video prediction project built on the local research template. The primary algorithm entry point is `DeMemWMMinecraft`, registered through the Hydra algorithm config `dememwm_memory_dit`.

## Quick Start

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest tests
```

Run a local offline experiment after setting the dataset path in `configurations/dataset/video_minecraft.yaml`:

```bash
python main.py +name=dememwm_debug algorithm=dememwm_memory_dit wandb.mode=offline
```

Use `resume_ckpt_path=/path/to/checkpoint.ckpt` for deterministic checkpoint resume, or keep `auto_resume=true` to resume from `output_dir/checkpoints` when available.

## Layout

- `algorithms/worldmem/dememwm/`: DeMemWM memory construction, retrieval, scheduling, diagnostics, and injection code.
- `algorithms/worldmem/dememwm_memory_dit.py`: primary DeMemWM algorithm class.
- `configurations/algorithm/dememwm_memory_dit.yaml`: consumed DeMemWM training and evaluation contract.
- `scripts/`: Slurm and inspection scripts using the DeMemWM naming.
- `tests/`: static and unit coverage for DeMemWM config, retrieval, compression, schedules, and training behavior.

## Reproducibility Notes

- Keep `wandb.mode=offline` for local reproducible runs that do not depend on network access.
- Set `seed=<int>` on the command line to seed Lightning and dataloader workers.
- Runtime artifacts such as `outputs/`, `slurm_logs/`, Python caches, checkpoints, and local datasets are ignored by git.
- The default Hydra training config selects `algorithm: dememwm_memory_dit`.