Publish Cache Atlas static site

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+public/media/minicache-depth-axis.mp4 filter=lfs diff=lfs merge=lfs -text
+public/media/minicache-layer-merge.mp4 filter=lfs diff=lfs merge=lfs -text
+public/media/minicache-retention.mp4 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,30 @@
+# build output
+dist/
+
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+__pycache__/
+*.pyc
+
+# jetbrains setting folder
+.idea/
+
+# internal planning notes
+PROJECT_DIRECTION.md
+research/

.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

README.md

@@ -1,10 +1,33 @@
 ---
 title: Cache Atlas
-emoji: 🚀
-colorFrom: gray
+emoji: 🧠
+colorFrom: blue
 colorTo: indigo
 sdk: static
+app_build_command: npm run build
+app_file: dist/index.html
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Cache Atlas
+
+Public notes and demos for learning modern inference systems by implementing the core pieces.
+
+This repo holds:
+
+- paper notes written as implementation writeups
+- diagrams and Manim renders
+- inline demos embedded in articles
+- links to standalone implementation repos
+- reproduction notes for the code paths I build
+
+Current paper track:
+
+1. <https://arxiv.org/abs/2405.14366> — MiniCache
+2. <https://arxiv.org/abs/2412.03409> — PrefixKV
+
+## Commands
+
+- `npm run dev`
+- `npm run build`

animations/scenes/minicache_intro.py

@@ -0,0 +1,159 @@
+from manim import *
+
+
+config.background_color = BLACK
+
+INK = "#E7EDF4"
+MUTED = "#9AA6B2"
+ACCENT = "#79D2FF"
+GREEN = "#7DF0C8"
+RED = "#FF8B84"
+CARD = "#0B0E12"
+
+
+def box(width, height, stroke=INK, fill=CARD, opacity=1.0):
+    return RoundedRectangle(
+        width=width,
+        height=height,
+        corner_radius=0.08,
+        stroke_color=stroke,
+        stroke_width=2,
+        fill_color=fill,
+        fill_opacity=opacity,
+    )
+
+
+class MiniCacheDepthAxis(Scene):
+    def construct(self):
+        title = Text("KV cache papers attack different axes", color=INK, font_size=40)
+        title.to_edge(UP)
+
+        left_frame = box(4.8, 3.8, stroke=ACCENT)
+        right_frame = box(4.8, 3.8, stroke=GREEN)
+        frames = VGroup(left_frame, right_frame).arrange(RIGHT, buff=0.5).shift(DOWN * 0.15)
+
+        left_title = Text("token-axis", color=ACCENT, font_size=26).next_to(left_frame, UP, buff=0.18)
+        right_title = Text("depth-axis", color=GREEN, font_size=26).next_to(right_frame, UP, buff=0.18)
+
+        token_grid = VGroup()
+        for _ in range(5):
+            row = VGroup(*[Square(side_length=0.38, stroke_color=ACCENT, fill_color=ACCENT, fill_opacity=0.08) for _ in range(7)])
+            row.arrange(RIGHT, buff=0.04)
+            token_grid.add(row)
+        token_grid.arrange(DOWN, buff=0.06).move_to(left_frame)
+
+        keep = SurroundingRectangle(VGroup(token_grid[0], token_grid[1], token_grid[2]), color=ACCENT, buff=0.08)
+        drop = Cross(VGroup(token_grid[3], token_grid[4]), stroke_color=RED, stroke_width=4).scale(1.1)
+
+        layers = VGroup()
+        for idx in range(6):
+            rect = box(3.4, 0.38, stroke=GREEN, fill=GREEN, opacity=0.1)
+            rect.add(Text(f"layer {idx + 1}", color=INK, font_size=18).move_to(rect))
+            layers.add(rect)
+        layers.arrange(DOWN, buff=0.12).move_to(right_frame)
+
+        merge_a = SurroundingRectangle(VGroup(layers[2], layers[3]), color=GREEN, buff=0.08)
+        merge_b = SurroundingRectangle(VGroup(layers[4], layers[5]), color=GREEN, buff=0.08)
+        arrow = Arrow(LEFT * 0.9, RIGHT * 0.9, color=GREEN).move_to(right_frame.get_bottom() + UP * 0.38)
+        note = Text("MiniCache compresses across depth", color=MUTED, font_size=24).to_edge(DOWN)
+
+        self.play(Write(title))
+        self.play(FadeIn(frames), FadeIn(left_title), FadeIn(right_title))
+        self.play(LaggedStart(*[FadeIn(row, shift=UP * 0.08) for row in token_grid], lag_ratio=0.08))
+        self.play(Create(keep), Create(drop))
+        self.play(LaggedStart(*[FadeIn(layer, shift=RIGHT * 0.08) for layer in layers], lag_ratio=0.08))
+        self.play(Create(merge_a), Create(merge_b), GrowArrow(arrow))
+        self.play(FadeIn(note))
+        self.wait(1)
+
+
+class MiniCacheLayerMerge(Scene):
+    def construct(self):
+        title = Text("Middle and deep layers may be redundant", color=INK, font_size=40)
+        title.to_edge(UP)
+
+        layer_stack = VGroup()
+        colors = [ACCENT, ACCENT, GREEN, GREEN, GREEN, GREEN]
+        for idx, color in enumerate(colors):
+            rect = box(4.4, 0.46, stroke=color, fill=color, opacity=0.12)
+            rect.add(Text(f"layer {idx + 1}", color=INK, font_size=18).move_to(rect))
+            layer_stack.add(rect)
+        layer_stack.arrange(DOWN, buff=0.16).shift(LEFT * 1.7 + DOWN * 0.15)
+
+        similar_a = SurroundingRectangle(VGroup(layer_stack[2], layer_stack[3]), color=GREEN, buff=0.08)
+        similar_b = SurroundingRectangle(VGroup(layer_stack[4], layer_stack[5]), color=GREEN, buff=0.08)
+
+        compressed = VGroup()
+        for label in ["compressed pair", "compressed pair"]:
+            rect = box(2.8, 0.62, stroke=GREEN, fill=GREEN, opacity=0.12)
+            rect.add(Text(label, color=INK, font_size=18).move_to(rect))
+            compressed.add(rect)
+        compressed.arrange(DOWN, buff=0.36).shift(RIGHT * 2.4)
+
+        arrows = VGroup(
+            Arrow(similar_a.get_right(), compressed[0].get_left(), color=GREEN, buff=0.2),
+            Arrow(similar_b.get_right(), compressed[1].get_left(), color=GREEN, buff=0.2),
+        )
+
+        memory_before = Text("memory before", color=MUTED, font_size=20).next_to(layer_stack, DOWN, buff=0.28)
+        memory_after = Text("memory after", color=MUTED, font_size=20).next_to(compressed, DOWN, buff=0.28)
+        bars_before = VGroup(*[Rectangle(width=0.42, height=0.18, stroke_width=0, fill_color=ACCENT, fill_opacity=1) for _ in range(6)]).arrange(RIGHT, buff=0.06).next_to(memory_before, DOWN, buff=0.16)
+        bars_after = VGroup(*[Rectangle(width=0.42, height=0.18, stroke_width=0, fill_color=GREEN, fill_opacity=1) for _ in range(4)]).arrange(RIGHT, buff=0.06).next_to(memory_after, DOWN, buff=0.16)
+
+        note = Text("compress the cache without only dropping tokens", color=MUTED, font_size=24).to_edge(DOWN)
+
+        self.play(Write(title))
+        self.play(LaggedStart(*[FadeIn(layer, shift=UP * 0.08) for layer in layer_stack], lag_ratio=0.08))
+        self.play(Create(similar_a), Create(similar_b))
+        self.play(GrowArrow(arrows[0]), FadeIn(compressed[0]))
+        self.play(GrowArrow(arrows[1]), FadeIn(compressed[1]))
+        self.play(FadeIn(memory_before), FadeIn(bars_before))
+        self.play(FadeIn(memory_after), FadeIn(bars_after))
+        self.play(FadeIn(note))
+        self.wait(1)
+
+
+class MiniCacheRetention(Scene):
+    def construct(self):
+        title = Text("Retention keeps the sharp mismatches", color=INK, font_size=40)
+        title.to_edge(UP)
+
+        tokens = VGroup()
+        fills = [GREEN, GREEN, GREEN, RED, GREEN, RED, GREEN, GREEN]
+        labels = ["0.98", "0.97", "0.99", "0.71", "0.96", "0.68", "0.98", "0.99"]
+        for fill, label in zip(fills, labels):
+            square = RoundedRectangle(
+                width=0.78,
+                height=0.78,
+                corner_radius=0.08,
+                stroke_color=fill,
+                stroke_width=2,
+                fill_color=fill,
+                fill_opacity=0.12,
+            )
+            number = Text(label, color=INK, font_size=18).move_to(square)
+            tokens.add(VGroup(square, number))
+        tokens.arrange(RIGHT, buff=0.14).shift(UP * 0.35)
+
+        caption = Text("cross-layer similarity per token", color=MUTED, font_size=24).next_to(tokens, UP, buff=0.24)
+        threshold = DashedLine(
+            start=tokens.get_left() + DOWN * 0.85,
+            end=tokens.get_right() + DOWN * 0.85,
+            color=MUTED,
+            dash_length=0.1,
+        )
+        threshold_label = Text("similar enough -> merge", color=GREEN, font_size=22).next_to(threshold, DOWN, buff=0.16)
+
+        kept = VGroup(
+            SurroundingRectangle(tokens[3], color=RED, buff=0.08),
+            SurroundingRectangle(tokens[5], color=RED, buff=0.08),
+        )
+        kept_label = Text("retain the unusually distinct pairs", color=RED, font_size=24).to_edge(DOWN)
+
+        self.play(Write(title))
+        self.play(FadeIn(caption))
+        self.play(LaggedStart(*[FadeIn(token, shift=UP * 0.08) for token in tokens], lag_ratio=0.08))
+        self.play(Create(threshold), FadeIn(threshold_label))
+        self.play(Create(kept[0]), Create(kept[1]))
+        self.play(FadeIn(kept_label))
+        self.wait(1)

astro.config.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+
+import mdx from '@astrojs/mdx';
+import react from '@astrojs/react';
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [mdx(), react()]
+});

package.json

@@ -0,0 +1,23 @@
+{
+  "name": "cache-atlas",
+  "type": "module",
+  "version": "0.0.1",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^5.0.4",
+    "@astrojs/react": "^5.0.4",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "astro": "^6.1.9",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
+  }
+}

public/media/minicache-depth-axis.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7ccd98f2c8dc35b850e72befd292cba69cb3a340345fbeb658e95dbb6bcda3fa
+size 175526

public/media/minicache-layer-merge.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:730416da0386dc6627faea6fad19c81c314c717aaba29c4f424842499be22207
+size 165670

public/media/minicache-retention.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:48d94ebcd3c115cd0e52e3408780f2b721b00cbc663bf4a6b0fdf960b7e489ba
+size 131083

research/FIRST_PAPER_DECISION.md

@@ -0,0 +1,125 @@
+# First Paper Decision
+
+## Decision
+
+We should **write generally first, implement narrowly first**.
+
+That means:
+
+## First post
+
+**Why KV cache papers matter**
+
+This is the right first post because it does three things:
+
+1. explains the space before we commit to one paper
+2. gives us a reusable framing for later posts
+3. supports the first interactive demo naturally
+
+It should answer:
+
+- what the KV cache is
+- why decode becomes memory-bound
+- why people keep proposing compression / eviction / budget allocation
+- why this repo is focusing on cache-efficiency papers
+
+## First implementation
+
+**MiniCache**
+
+## Why MiniCache first
+
+MiniCache is not the flashiest option, but it is the best first implementation target.
+
+Reasons:
+
+1. **Cleaner scope**
+   - training-free
+   - no heavy VLM integration needed on day one
+   - easier to isolate the core method
+
+2. **Better odds of shipping**
+   - more self-contained than PrefixKV
+   - less adapter pain
+   - easier to make a concise repo that feels complete
+
+3. **Good visuals anyway**
+   - cross-layer redundancy
+   - kept vs compressed cache state
+   - depth-wise compression
+   - memory / quality tradeoffs
+
+4. **Sets up the rest of the series**
+   - once we have one clean cache-efficiency implementation, later papers like PrefixKV and CAKE become easier to explain
+
+## Why not PrefixKV first
+
+PrefixKV is still a strong paper.
+
+But it is better as the **second** project, not the first.
+
+Reasons:
+
+- more adapter complexity
+- more tied to vision-language model internals
+- higher chance of getting stuck in model integration before the repo identity is established
+
+PrefixKV is still the better paper if the top priority becomes:
+
+- image-based demos
+- VLM-specific cache allocation
+- a stronger visual public artifact
+
+But for the first clean implementation repo, MiniCache has better odds.
+
+## Recommended sequence
+
+### Step 1
+
+Write:
+
+- `Why KV cache papers matter`
+
+### Step 2
+
+Implement:
+
+- `MiniCache`
+
+### Step 3
+
+Write:
+
+- `MiniCache from first principles`
+
+### Step 4
+
+Then move to:
+
+- `PrefixKV`
+
+That gives the project both:
+
+- one clean systems implementation first
+- one more visual VLM-oriented paper second
+
+## What to build with MiniCache
+
+For the implementation repo:
+
+- minimal standalone cache-compression module
+- one benchmark script
+- one toy memory simulator
+- one clean README
+
+For the blog:
+
+- one diagram showing depth-wise redundancy
+- one memory budget chart
+- one inline demo showing how cache size changes under different compression settings
+
+## Current call
+
+If we start now, the best immediate move is:
+
+> finish the first post and build MiniCache first

research/blog-patterns.md

@@ -0,0 +1,63 @@
+# Blog and repo patterns
+
+Internal note. This file is intentionally hidden from the public repo.
+
+## References checked
+
+- `mni-ml`
+- Distill
+- `lucidrains/x-transformers`
+- `huggingface/ml-intern`
+- Lil'Log
+
+## What to borrow
+
+### mni-ml
+
+- extremely sparse home page
+- curriculum / table-of-contents structure
+- article-first navigation
+- short explanatory paragraphs
+- direct, not academic, tone
+
+### Distill
+
+- visuals do explanatory work, not decorative work
+- interaction appears exactly where the reader needs it
+- one section, one mental model
+- explanations progress from intuition to mechanism
+
+### lucidrains
+
+- README is the product
+- install and usage appear immediately
+- small runnable examples beat long prose
+- public package surface stays focused
+
+### ml-intern
+
+- repo structure is disciplined
+- setup path is explicit
+- use `uv` and make local development obvious
+
+For this project, borrow the discipline, not the agent architecture.
+
+### Lil'Log
+
+- table of contents helps long posts
+- strong use of sectioning and references
+- good for survey-style notes
+
+## Practical synthesis
+
+### Hub repo
+
+- `mni-ml` home page
+- Distill-style inline demos
+- concise system writing
+
+### Implementation repos
+
+- lucidrains-style README
+- `ml-intern`-style setup discipline
+- tight public API

src/components/CacheBudgetDemo.tsx

@@ -0,0 +1,85 @@
+import { type CSSProperties, useMemo, useState } from "react";
+
+export default function CacheBudgetDemo() {
+  const [layers, setLayers] = useState(24);
+  const [prefix, setPrefix] = useState(256);
+  const [tokenCost, setTokenCost] = useState(2.4);
+
+  const totalMb = useMemo(() => {
+    return (layers * prefix * tokenCost) / 1024;
+  }, [layers, prefix, tokenCost]);
+
+  return (
+    <div style={styles.card}>
+      <div style={styles.label}>inline demo</div>
+      <p style={styles.copy}>
+        Tiny proxy for why cache-budget papers exist at all. Push layer count, kept prefix length, or per-token memory cost,
+        and the memory bill climbs fast.
+      </p>
+
+      <div style={styles.grid}>
+        <label style={styles.control}>
+          <span>layers</span>
+          <strong>{layers}</strong>
+          <input type="range" min="8" max="48" step="4" value={layers} onChange={(e) => setLayers(Number(e.target.value))} />
+        </label>
+        <label style={styles.control}>
+          <span>kept prefix</span>
+          <strong>{prefix}</strong>
+          <input type="range" min="64" max="1024" step="64" value={prefix} onChange={(e) => setPrefix(Number(e.target.value))} />
+        </label>
+        <label style={styles.control}>
+          <span>mb / token / layer</span>
+          <strong>{tokenCost.toFixed(1)}</strong>
+          <input type="range" min="0.5" max="4" step="0.1" value={tokenCost} onChange={(e) => setTokenCost(Number(e.target.value))} />
+        </label>
+      </div>
+
+      <div style={styles.result}>
+        <span>estimated cache memory</span>
+        <strong>{totalMb.toFixed(1)} MB</strong>
+      </div>
+    </div>
+  );
+}
+
+const styles: Record<string, CSSProperties> = {
+  card: {
+    border: "1px solid rgba(231,237,244,0.14)",
+    background: "rgba(11,14,18,0.92)",
+    padding: "18px",
+    margin: "24px 0",
+  },
+  label: {
+    color: "#9aa6b2",
+    fontSize: "12px",
+    textTransform: "uppercase",
+  },
+  copy: {
+    color: "#9aa6b2",
+    lineHeight: 1.8,
+  },
+  grid: {
+    display: "grid",
+    gridTemplateColumns: "repeat(auto-fit, minmax(180px, 1fr))",
+    gap: "12px",
+    marginTop: "12px",
+  },
+  control: {
+    display: "grid",
+    gap: "8px",
+    border: "1px solid rgba(231,237,244,0.14)",
+    padding: "12px",
+    background: "rgba(8,10,12,0.92)",
+    color: "#e7edf4",
+  },
+  result: {
+    display: "grid",
+    gap: "6px",
+    marginTop: "14px",
+    padding: "12px",
+    border: "1px solid rgba(231,237,244,0.14)",
+    background: "rgba(8,10,12,0.92)",
+    color: "#e7edf4",
+  },
+};

src/layouts/Layout.astro

@@ -0,0 +1,287 @@
+---
+const { title = "Cache Atlas" } = Astro.props;
+const path = Astro.url.pathname;
+---
+
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<link rel="icon" href="/favicon.ico" />
+		<meta name="generator" content={Astro.generator} />
+		<title>{title}</title>
+	</head>
+	<body>
+		<header class="site-header">
+			<div class="header-inner">
+				<a class="brand" href="/">Cache Atlas</a>
+				<nav>
+					<a class:list={{ active: path === "/" }} href="/">Home</a>
+					<a class:list={{ active: path.startsWith("/notes") }} href="/notes">Notes</a>
+				</nav>
+			</div>
+		</header>
+		<slot />
+	</body>
+</html>
+
+<style>
+	:root {
+		color-scheme: dark;
+		font-family: "IBM Plex Mono", "SF Mono", Menlo, monospace;
+		--bg: #000;
+		--ink: #e7edf4;
+		--muted: #9aa6b2;
+		--line: rgba(231, 237, 244, 0.14);
+		--card: rgba(11, 14, 18, 0.92);
+		--accent: #79d2ff;
+	}
+
+	* {
+		box-sizing: border-box;
+	}
+
+	html,
+	body {
+		margin: 0;
+		width: 100%;
+		min-height: 100%;
+		background: var(--bg);
+		color: var(--ink);
+	}
+
+	a {
+		color: inherit;
+		text-decoration: none;
+	}
+
+	body {
+		font-size: 16px;
+	}
+
+	.site-header {
+		position: sticky;
+		top: 0;
+		z-index: 10;
+		border-bottom: 1px solid var(--line);
+		background: rgba(0, 0, 0, 0.9);
+		backdrop-filter: blur(14px);
+	}
+
+	.header-inner {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 16px;
+		width: min(1040px, calc(100% - 32px));
+		margin: 0 auto;
+		padding: 18px 0;
+	}
+
+	.brand {
+		font-weight: 600;
+		letter-spacing: 0;
+	}
+
+	nav {
+		display: flex;
+		align-items: center;
+		gap: 14px;
+	}
+
+	nav a {
+		color: var(--muted);
+		font-size: 12px;
+		text-transform: uppercase;
+	}
+
+	nav a.active,
+	nav a:hover {
+		color: var(--ink);
+	}
+
+	:global(main.page) {
+		width: min(980px, calc(100% - 32px));
+		margin: 0 auto;
+		padding: 48px 0 44px;
+	}
+
+	:global(main.article-shell) {
+		width: min(900px, calc(100% - 32px));
+		margin: 0 auto;
+		padding: 38px 0 42px;
+	}
+
+	:global(.eyebrow),
+	:global(.label) {
+		color: var(--muted);
+		font-size: 12px;
+		text-transform: uppercase;
+	}
+
+	:global(h1) {
+		margin: 12px 0 20px;
+		font-size: clamp(40px, 7vw, 82px);
+		line-height: 0.96;
+		font-weight: 600;
+	}
+
+	:global(.article-shell h1) {
+		max-width: 860px;
+		font-size: clamp(34px, 5vw, 62px);
+	}
+
+	:global(h2) {
+		margin: 40px 0 14px;
+		font-size: clamp(24px, 3vw, 38px);
+		line-height: 1.02;
+	}
+
+	:global(p),
+	:global(li) {
+		color: var(--muted);
+		line-height: 1.8;
+	}
+
+	:global(.lede) {
+		max-width: 820px;
+		font-size: 19px;
+		color: var(--ink);
+	}
+
+	:global(blockquote) {
+		margin: 22px 0;
+		padding: 14px 18px;
+		border-left: 2px solid var(--accent);
+		background: rgba(11, 14, 18, 0.92);
+	}
+
+	:global(code) {
+		font-family: inherit;
+	}
+
+	:global(pre) {
+		overflow-x: auto;
+		padding: 16px;
+		border: 1px solid var(--line);
+		background: var(--card);
+	}
+
+	:global(.note-card) {
+		margin: 22px 0;
+		padding: 18px;
+		border: 1px solid var(--line);
+		background: var(--card);
+	}
+
+	:global(.meta-grid) {
+		display: grid;
+		grid-template-columns: repeat(3, minmax(0, 1fr));
+		gap: 12px;
+		margin: 20px 0 26px;
+	}
+
+	:global(.meta-cell) {
+		padding: 14px;
+		border: 1px solid var(--line);
+		background: var(--card);
+	}
+
+	:global(.meta-cell strong) {
+		display: block;
+		margin-bottom: 6px;
+		font-size: 12px;
+		color: var(--muted);
+		text-transform: uppercase;
+	}
+
+	:global(.source-list),
+	:global(.bullet-list) {
+		padding-left: 18px;
+	}
+
+	:global(.source-list a),
+	:global(.inline-link) {
+		color: var(--accent);
+	}
+
+	:global(.category-list) {
+		display: grid;
+		grid-template-columns: repeat(2, minmax(0, 1fr));
+		gap: 12px;
+		margin: 14px 0 0;
+		padding: 0;
+		list-style: none;
+	}
+
+	:global(.category-list li) {
+		padding: 14px;
+		border: 1px solid var(--line);
+		background: var(--card);
+	}
+
+	:global(.category-list strong) {
+		display: block;
+		margin-bottom: 4px;
+		color: var(--ink);
+	}
+
+	:global(.article-nav) {
+		display: grid;
+		grid-template-columns: repeat(2, minmax(0, 1fr));
+		gap: 12px;
+		margin-top: 34px;
+		padding-top: 18px;
+		border-top: 1px solid var(--line);
+	}
+
+	:global(.article-nav a) {
+		display: block;
+		min-height: 86px;
+		padding: 14px;
+		border: 1px solid var(--line);
+		background: var(--card);
+	}
+
+	:global(.article-nav span) {
+		display: block;
+		margin-bottom: 6px;
+		color: var(--muted);
+		font-size: 12px;
+		text-transform: uppercase;
+	}
+
+	:global(.article-nav strong) {
+		color: var(--ink);
+		line-height: 1.35;
+	}
+
+	:global(.video-figure) {
+		margin: 24px 0;
+	}
+
+	:global(.video-figure video) {
+		display: block;
+		width: 100%;
+		border: 1px solid var(--line);
+		background: #050607;
+	}
+
+	:global(.video-figure figcaption) {
+		margin-top: 10px;
+		color: var(--muted);
+	}
+
+	@media (max-width: 860px) {
+		:global(.meta-grid) {
+			grid-template-columns: 1fr;
+		}
+
+		:global(.category-list),
+		:global(.article-nav) {
+			grid-template-columns: 1fr;
+		}
+	}
+</style>

src/pages/index.astro

@@ -0,0 +1,126 @@
+---
+import Layout from "../layouts/Layout.astro";
+---
+
+<Layout title="Cache Atlas">
+  <main class="page">
+    <div class="eyebrow">research implementation lab</div>
+    <h1>KV-cache and inference papers, studied through code.</h1>
+    <p class="lede">
+      Cache Atlas is my public notebook for learning modern inference systems by implementing the core mechanics.
+      Each note explains what I read, what I built, and how to reproduce the experiment instead of treating the paper
+      as a black box.
+    </p>
+
+    <section class="toc">
+      <div class="label">notes</div>
+      <ol>
+        <li>
+          <a href="/notes/why-kv-cache-papers-matter">Why KV cache papers matter</a>
+          <p>A map of the memory problem that motivated the first implementation.</p>
+        </li>
+        <li>
+          <a href="/notes/minicache-paper-notes">MiniCache paper notes</a>
+          <p>Depth-axis compression, the implementation boundary, and the pieces I reproduced in PyTorch.</p>
+        </li>
+      </ol>
+    </section>
+
+    <section class="toc">
+      <div class="label">categories</div>
+      <ul class="category-list">
+        <li>
+          <strong>KV-cache memory</strong>
+          <p>Cache growth, compression axes, retention policies, and decode-time memory pressure.</p>
+        </li>
+        <li>
+          <strong>Paper reproductions</strong>
+          <p>Small implementation tracks that turn one paper mechanism into runnable code.</p>
+        </li>
+        <li>
+          <strong>Visual demos</strong>
+          <p>Animations and interactive components that make the systems behavior easier to inspect.</p>
+        </li>
+        <li>
+          <strong>Benchmarks</strong>
+          <p>Minimal scripts that measure the implemented path before scaling up the experiment.</p>
+        </li>
+      </ul>
+    </section>
+
+    <section class="toc">
+      <div class="label">repos</div>
+      <ul>
+        <li>
+          <a href="https://github.com/rishabhsai/minicache-pytorch" target="_blank" rel="noreferrer">minicache-pytorch</a>
+          <p>Standalone PyTorch package with clean-room primitives, tests, examples, and benchmark scripts.</p>
+        </li>
+        <li>
+          <strong>prefixkv-pytorch</strong>
+          <p>Planned next track for token and layer budget allocation in vision-language generation.</p>
+        </li>
+      </ul>
+    </section>
+
+    <section class="toc">
+      <div class="label">next note</div>
+      <p>
+        The next note should be a reproduction report for <strong>minicache-pytorch</strong>: the API, the tensor
+        tests, a small benchmark result, and the exact commands needed to reproduce the implementation locally.
+      </p>
+    </section>
+  </main>
+</Layout>
+
+<style>
+  h1 {
+    margin: 12px 0 20px;
+    max-width: 900px;
+    font-size: clamp(40px, 7vw, 82px);
+    line-height: 0.96;
+    font-weight: 600;
+  }
+
+  .lede,
+  .card p {
+    color: var(--muted);
+    line-height: 1.8;
+  }
+
+  .lede {
+    max-width: 820px;
+    font-size: 19px;
+    color: var(--ink);
+  }
+
+  .toc {
+    margin-top: 28px;
+    padding-top: 18px;
+    border-top: 1px solid var(--line);
+  }
+
+  .toc ol,
+  .toc ul {
+    margin: 12px 0 0;
+    padding-left: 20px;
+  }
+
+  .toc li {
+    margin: 0 0 14px;
+  }
+
+  .toc a,
+  .toc strong {
+    color: var(--ink);
+  }
+
+  .toc a {
+    text-decoration: underline;
+    text-decoration-color: rgba(121, 210, 255, 0.45);
+    text-underline-offset: 3px;
+  }
+
+  .toc p {
+    margin: 6px 0 0;
+  }
+</style>

src/pages/notes/index.astro

@@ -0,0 +1,74 @@
+---
+import Layout from "../../layouts/Layout.astro";
+---
+
+<Layout title="Notes - Cache Atlas">
+  <main class="page">
+    <div class="eyebrow">notes</div>
+    <h1>Paper notes and implementation writeups.</h1>
+    <p class="lede">
+      These notes track my learning process in public: one mechanism at a time, with enough implementation detail,
+      visuals, and reproduction notes to make the code path inspectable.
+    </p>
+
+    <section class="toc">
+      <ol>
+        <li>
+          <a href="/notes/why-kv-cache-papers-matter">Why KV cache papers matter</a>
+          <p>The opening map of the memory problem behind modern inference serving.</p>
+        </li>
+        <li>
+          <a href="/notes/minicache-paper-notes">MiniCache paper notes</a>
+          <p>The first paper-specific implementation note, centered on <a href="https://arxiv.org/abs/2405.14366" target="_blank" rel="noreferrer">arXiv:2405.14366</a>.</p>
+        </li>
+      </ol>
+    </section>
+
+    <section class="toc">
+      <div class="label">categories</div>
+      <ul class="category-list">
+        <li>
+          <strong>KV-cache memory</strong>
+          <p>Cache footprint, decode bottlenecks, and compression strategies.</p>
+        </li>
+        <li>
+          <strong>Implementation notes</strong>
+          <p>Reproducible code paths with tests, examples, and benchmark commands.</p>
+        </li>
+      </ul>
+    </section>
+
+    <section class="toc">
+      <div class="label">next note</div>
+      <p>
+        Next up: a short reproduction report for <strong>minicache-pytorch</strong>, including the public API,
+        the current test coverage, and a first benchmark table.
+      </p>
+    </section>
+  </main>
+</Layout>
+
+<style>
+  .toc {
+    margin-top: 28px;
+    padding-top: 18px;
+    border-top: 1px solid var(--line);
+  }
+
+  .toc ol {
+    margin: 12px 0 0;
+    padding-left: 20px;
+  }
+
+  .toc li {
+    margin: 0 0 14px;
+  }
+
+  .toc a {
+    color: var(--ink);
+  }
+
+  .toc p {
+    margin: 6px 0 0;
+  }
+</style>

src/pages/notes/minicache-paper-notes.mdx

@@ -0,0 +1,134 @@
+---
+layout: ../../layouts/Layout.astro
+title: MiniCache paper notes - Cache Atlas
+---
+
+<main class="article-shell">
+
+<div class="eyebrow">note 02</div>
+
+# MiniCache paper notes
+
+The first implementation target is:
+
+> <a class="inline-link" href="https://arxiv.org/abs/2405.14366" target="_blank" rel="noreferrer">MiniCache: KV Cache Compression in Depth Dimension for Large Language Models</a>
+
+The paper is interesting for one simple reason: it attacks the cache along a less crowded axis.
+
+Most cache papers make an argument about **which tokens** to keep. MiniCache instead starts from the observation that adjacent middle-to-deep layers can carry highly similar KV state, then asks whether that redundancy can be compressed directly.
+
+<div class="meta-grid">
+  <div class="meta-cell">
+    <strong>arxiv</strong>
+    <a class="inline-link" href="https://arxiv.org/abs/2405.14366" target="_blank" rel="noreferrer">2405.14366</a>
+  </div>
+  <div class="meta-cell">
+    <strong>official project</strong>
+    <a class="inline-link" href="https://minicache.vmv.re/" target="_blank" rel="noreferrer">minicache.vmv.re</a>
+  </div>
+  <div class="meta-cell">
+    <strong>official repo</strong>
+    <a class="inline-link" href="https://github.com/AkideLiu/MiniCache" target="_blank" rel="noreferrer">AkideLiu/MiniCache</a>
+  </div>
+</div>
+
+## Paper snapshot
+
+From the abstract, the public claim is:
+
+- KV cache states show high similarity between adjacent layers in the middle-to-deep part of the network
+- disentangling magnitude and direction makes merging easier
+- a token retention strategy can avoid merging the most distinct pairs
+- the method is training-free and complementary to quantization and sparsity
+
+The specific abstract lines that matter for implementation are in the paper itself:
+
+- <a class="inline-link" href="https://arxiv.org/abs/2405.14366" target="_blank" rel="noreferrer">arXiv:2405.14366</a>
+
+For this reproduction, I am not rebuilding the entire official evaluation stack. I am isolating the core tensor behavior so the method is easy to read, test, and extend.
+
+## What I implemented first
+
+The first pass keeps the scope tight instead of recreating the full paper stack at once.
+
+`minicache-pytorch` focuses on:
+
+- magnitude / direction decomposition
+- adjacent-layer direction interpolation
+- reconstruction with preserved magnitude
+- a simple token-retention primitive based on inter-layer similarity
+- tight unit tests around those behaviors
+- one benchmark script for the pairwise compression path
+
+That is already enough to make the method inspectable.
+
+<figure class="video-figure">
+  <video autoPlay loop muted playsInline controls preload="metadata">
+    <source src="/media/minicache-layer-merge.mp4" type="video/mp4" />
+  </video>
+  <figcaption>
+    The merge intuition: if nearby layers are partially redundant, the compression path can live between layers rather than only across tokens.
+  </figcaption>
+</figure>
+
+## What we are adding beyond the official repo
+
+There is already an official MiniCache repo. That means the standalone implementation needs a different job.
+
+The added value is:
+
+- smaller surface area
+- easier install and packaging
+- a public API instead of only evaluation glue
+- tests around the math primitives
+- examples that fit in a README
+- diagrams and animations that explain the method
+
+That is the same pattern that makes a lot of lucidrains repos useful: not necessarily beating the official codebase, but turning an idea into something easier to inspect and reuse.
+
+## Retention is where the method gets more interesting
+
+The part that makes MiniCache feel less like “just average layers” is the retention step.
+
+If two adjacent layers are already similar for a token, merging them should be cheap. If they diverge sharply for a token, blindly merging them is where quality loss is most likely to appear.
+
+That makes the core retention primitive:
+
+1. compute a similarity score between adjacent layer states
+2. keep a mask for the highly distinct token positions
+3. only merge the easy cases
+
+That gives the implementation repo something concrete and testable to grow around.
+
+<figure class="video-figure">
+  <video autoPlay loop muted playsInline controls preload="metadata">
+    <source src="/media/minicache-retention.mp4" type="video/mp4" />
+  </video>
+  <figcaption>
+    A simple retention picture: tokens with unusually low cross-layer similarity are kept out of the merge path.
+  </figcaption>
+</figure>
+
+## Sources
+
+<ul class="source-list">
+  <li><a href="https://arxiv.org/abs/2405.14366" target="_blank" rel="noreferrer">MiniCache paper (arXiv:2405.14366)</a></li>
+  <li><a href="https://minicache.vmv.re/" target="_blank" rel="noreferrer">MiniCache project page</a></li>
+  <li><a href="https://github.com/AkideLiu/MiniCache" target="_blank" rel="noreferrer">Official MiniCache GitHub repo</a></li>
+  <li><a href="https://mni-ml.github.io/" target="_blank" rel="noreferrer">mni-ml</a></li>
+  <li><a href="https://distill.pub/2020/communicating-with-interactive-articles/" target="_blank" rel="noreferrer">Distill: Communicating with Interactive Articles</a></li>
+  <li><a href="https://github.com/lucidrains/x-transformers" target="_blank" rel="noreferrer">lucidrains/x-transformers</a></li>
+</ul>
+
+<nav class="article-nav" aria-label="Article navigation">
+  <a href="/notes/why-kv-cache-papers-matter">
+    <span>Previous</span>
+    <strong>Why KV cache papers matter</strong>
+  </a>
+  <a href="https://github.com/rishabhsai/minicache-pytorch" target="_blank" rel="noreferrer">
+    <span>Next</span>
+    <strong>Open minicache-pytorch</strong>
+  </a>
+</nav>
+
+</main>

src/pages/notes/why-kv-cache-papers-matter.mdx

@@ -0,0 +1,221 @@
+---
+layout: ../../layouts/Layout.astro
+title: Why KV cache papers matter - Cache Atlas
+---
+
+import CacheBudgetDemo from "../../components/CacheBudgetDemo";
+
+<main class="article-shell">
+
+<div class="eyebrow">note 01</div>
+
+# Why KV cache papers matter
+
+The important shift is this:
+
+> as context windows grow, cache memory becomes a product constraint, not just a systems detail
+
+That is why the last stretch of serving papers keeps circling the same family of ideas:
+
+- compress the cache
+- evict part of the cache
+- allocate the cache unevenly across layers
+- specialize the policy for vision-language models
+
+I started with this map because the individual papers make more sense once the cache itself is treated as a product constraint.
+
+<div class="meta-grid">
+  <div class="meta-cell">
+    <strong>first implementation</strong>
+    MiniCache
+  </div>
+  <div class="meta-cell">
+    <strong>paper</strong>
+    <a class="inline-link" href="https://arxiv.org/abs/2405.14366" target="_blank" rel="noreferrer">arXiv:2405.14366</a>
+  </div>
+  <div class="meta-cell">
+    <strong>next note</strong>
+    <a class="inline-link" href="/notes/minicache-paper-notes">MiniCache paper notes</a>
+  </div>
+</div>
+
+<figure class="video-figure">
+  <video autoPlay loop muted playsInline controls preload="metadata">
+    <source src="/media/minicache-depth-axis.mp4" type="video/mp4" />
+  </video>
+  <figcaption>
+    One way to read the space: most cache work compresses or drops tokens along sequence length, while MiniCache asks what can be compressed across depth.
+  </figcaption>
+</figure>
+
+## The KV cache is not optional
+
+Autoregressive decoding without a cache is the obvious baseline and the wrong product system.
+
+Every generated token would force the model to recompute key and value state for the entire existing prefix. That makes decode cost grow with sequence length even when almost all of the old state is unchanged.
+
+The cache fixes that by storing old key and value tensors so later decode steps mainly append new state instead of rebuilding the past. The result is the modern serving stack:
+
+- prefill builds cache state from the prompt
+- decode reuses that state one token at a time
+
+The catch is that the cache itself gets expensive fast.
+
+## Why the memory bill gets ugly
+
+Cache size grows with several things at once:
+
+- number of layers
+- number of heads or KV groups
+- hidden dimensions
+- sequence length
+- batch size
+
+That is why serving teams keep running into the same practical problem:
+
+> the model still fits, but throughput collapses because memory traffic and cache footprint dominate decode
+
+This is also why there is not one single “KV cache paper.” There is a whole cluster of them.
+
+## The main paper buckets
+
+The easiest way to organize the space is by the axis they attack.
+
+### 1. Token-axis compression and eviction
+
+These papers ask:
+
+> which old tokens are worth keeping?
+
+Examples:
+
+- <a class="inline-link" href="https://arxiv.org/abs/2412.03409" target="_blank" rel="noreferrer">PrefixKV</a>
+- <a class="inline-link" href="https://arxiv.org/abs/2503.12491" target="_blank" rel="noreferrer">CAKE</a>
+
+This is especially natural for long prompts and vision-language models, where different parts of the prefix are not equally valuable.
+
+### 2. Depth-axis compression
+
+These papers ask:
+
+> how much redundancy exists across layers?
+
+This is the lane that made MiniCache interesting enough to start with. Instead of only asking which tokens to keep, it asks whether nearby layers carry overlapping information that can be compressed more directly.
+
+### 3. Architecture-specific cache policies
+
+These papers ask:
+
+> if the model is multimodal or has uneven layer behavior, should the cache budget be allocated differently?
+
+That is why PrefixKV is compelling even though it is not my first implementation target. It sits right at the intersection of cache policy and vision-language generation.
+
+## Why I started with MiniCache
+
+MiniCache is a good first implementation target because the core mechanic can be isolated without reproducing an entire serving stack.
+
+The paper:
+
+- <a class="inline-link" href="https://arxiv.org/abs/2405.14366" target="_blank" rel="noreferrer">MiniCache: KV Cache Compression in Depth Dimension for Large Language Models</a>
+
+Supporting links:
+
+- <a class="inline-link" href="https://minicache.vmv.re/" target="_blank" rel="noreferrer">official project page</a>
+- <a class="inline-link" href="https://github.com/AkideLiu/MiniCache" target="_blank" rel="noreferrer">official GitHub repo</a>
+
+Why it works as a first reproduction:
+
+- cleaner scope than PrefixKV
+- does not require starting in VLM adapter hell
+- easier to isolate the method itself
+- still rich enough for diagrams, demos, and benchmarks
+
+Tradeoffs:
+
+- it is less visually flashy than PrefixKV
+- it is not the strongest “image demo” paper
+
+That tradeoff is acceptable for this project because the goal is to publish code that is readable, testable, and easy to extend.
+
+<figure class="video-figure">
+  <video autoPlay loop muted playsInline controls preload="metadata">
+    <source src="/media/minicache-layer-merge.mp4" type="video/mp4" />
+  </video>
+  <figcaption>
+    The implementation intuition: if middle and deep layers are partially redundant, there is room to compress cache state across depth instead of only pruning tokens.
+  </figcaption>
+</figure>
+
+## What the public artifacts add
+
+The explanation site and implementation package have different jobs.
+
+### Hub repo: Cache Atlas
+
+Cache Atlas adds:
+
+- the explanation
+- the diagrams
+- the animation
+- the interactive demo
+- the paper comparison layer
+
+### Standalone repo: minicache-pytorch
+
+`minicache-pytorch` adds:
+
+- a clean-room reference implementation
+- a usable API
+- tight tests
+- benchmark scripts
+- a README that reads like a good lucidrains repo, not like a paper appendix
+- enough structure to grow cleanly, borrowing the packaging discipline of repos like `ml-intern` without copying its agent architecture
+
+That split keeps the notes readable while keeping the package focused on code, tests, and reproduction.
+
+## Example interactive demo
+
+The first demo does not need to be perfect. It just needs to make the memory problem obvious.
+
+<CacheBudgetDemo client:load />
+
+## What comes after this
+
+After MiniCache, the next paper track is PrefixKV.
+
+That gives the overall project a clean progression:
+
+1. general note on why cache papers matter
+2. depth-axis compression with MiniCache
+3. token / layer budget allocation with PrefixKV
+
+That order gives the project both:
+
+- a clean systems implementation first
+- a more visual VLM-oriented paper second
+
+## Sources
+
+<ul class="source-list">
+  <li><a href="https://arxiv.org/abs/2405.14366" target="_blank" rel="noreferrer">MiniCache paper (arXiv:2405.14366)</a></li>
+  <li><a href="https://minicache.vmv.re/" target="_blank" rel="noreferrer">MiniCache project page</a></li>
+  <li><a href="https://github.com/AkideLiu/MiniCache" target="_blank" rel="noreferrer">MiniCache GitHub repo</a></li>
+  <li><a href="https://arxiv.org/abs/2412.03409" target="_blank" rel="noreferrer">PrefixKV paper (arXiv:2412.03409)</a></li>
+  <li><a href="https://arxiv.org/abs/2503.12491" target="_blank" rel="noreferrer">CAKE paper (arXiv:2503.12491)</a></li>
+  <li><a href="https://distill.pub/" target="_blank" rel="noreferrer">Distill</a> for article structure and visual explanation style</li>
+  <li><a href="https://mni-ml.github.io/articles/inference/" target="_blank" rel="noreferrer">mni-ml inference article</a> for compact systems writing</li>
+  <li><a href="https://github.com/lucidrains" target="_blank" rel="noreferrer">lucidrains GitHub profile</a> for implementation-repo discipline and README style</li>
+</ul>
+
+<nav class="article-nav" aria-label="Article navigation">
+  <a href="/notes">
+    <span>Previous</span>
+    <strong>All notes</strong>
+  </a>
+  <a href="/notes/minicache-paper-notes">
+    <span>Next</span>
+    <strong>MiniCache paper notes</strong>
+  </a>
+</nav>
+
+</main>

tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [
+    ".astro/types.d.ts",
+    "**/*"
+  ],
+  "exclude": [
+    "dist"
+  ],
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react"
+  }
+}