# CacheMind: installation and notebook setup

Paper: **CacheMind: From Miss Rates to Why—Natural-Language, Trace-Grounded Reasoning for Cache Replacement**, ASPLOS 2026. https://doi.org/10.1145/3779212.3790136

## Environment

The repository provides `code_files/RAG.yaml`, a Conda environment export for Linux with Python 3.8.20, PyTorch 2.4.1, and CUDA 12.1. It contains platform-specific packages and a machine-specific `prefix`; it is not a portable lockfile. The notebooks record Python 3.8.20. The local-model workflow needs compatible GPU resources; hosted-model notebooks need access to the chosen provider.

```sh
git clone https://github.com/kaushal1803/cachemind.git
cd cachemind
sed '/^prefix:/d' code_files/RAG.yaml > RAG-local.yaml
conda env create -n cachemind -f RAG-local.yaml
conda activate cachemind
python -m ipykernel install --user --name cachemind --display-name "CacheMind"
```

Open the notebooks in Jupyter or a notebook editor and select the **CacheMind** kernel. Start from `code_files/` so relative imports of `rag_source` resolve. Package resolution may require maintainer updates: the exported environment is historical and does not list every package used in every optional notebook section (for example, the OpenAI SDK). No fresh installation or full reproduction is claimed by these instructions.

## Prepare the required data

1. Open `code_files/make_rag_dataset.ipynb`. Set `file_paths`, `cache_set_sizes`, `policy_descriptions`, `workload_descriptions`, `disassembly_files`, and `source_files` to your trace inputs and source/disassembly files.
2. Review the save/load paths before running cells. The notebook writes `processed_data.pkl` in its working directory; the OpenAI/Hugging Face notebooks load `../data/processed_data.pkl`, while `RAG_application.ipynb` loads `processed_data.pkl`. Use one consistent path, or place the generated file at the path required by the selected notebook.
3. Open `RAG_application_OpenAI.ipynb`, `RAG_application_HF.ipynb`, or `RAG_application.ipynb` for the desired backend. Configure your own model access, local model paths, and credentials in your environment. Review each cell before running it; optional sections reference additional datasets, local checkpoints, and experiment-specific paths.

The public checkout contains notebooks, retrieval code, environment metadata, and the categorized benchmark-question PDF. It does **not** contain the `data/` directory, prepared `processed_data.pkl`, raw eviction traces, or local model checkpoints referenced by the notebooks. Obtain or generate those inputs before expecting an end-to-end run. The PDF is not a substitute for the CSV/DOCX inputs referenced by evaluation cells.

## Repository map

- `code_files/rag_source.py`: retrieval and trace reasoning helpers.
- `code_files/make_rag_dataset.ipynb`: trace preprocessing.
- `code_files/RAG_application*.ipynb`: model-specific workflows.
- `analysis/`: evaluation and qualitative analysis notebooks.
- `Categorized Benchmark Questions.pdf`: benchmark questions.

## Citation and archiving

Use [CITATION.cff](CITATION.cff) for the paper citation. No software DOI or archived release was verified for this repository as of October 2, 2026. Until one is published, identify the exact Git commit used alongside the paper DOI. These instructions were checked against commit `9b756ce19eaaba358fc7476c50bd23a3c72c3f79`.
