diff --git a/README.md b/README.md
index 78d41d0..e74e6dc 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,19 @@
 
 ---
 
+## Demo
+
+<!-- Absolute on purpose, same as the hero: this file is the PyPI long_description.
+     PyPI's camo proxy cannot resolve a repo-relative image, and a relative link
+     would not open the mp4 on GitHub. README.uk.md / README.ru.md stay relative. -->
+<p align="center">
+  <a href="https://github.com/Lexus2016/turbo_quant_memory/blob/main/assets/turbo-quant-memory-promo.mp4">
+    <img src="https://raw.githubusercontent.com/Lexus2016/turbo_quant_memory/main/assets/turbo-quant-memory-poster.jpg" alt="30-second demo of Turbo Quant Memory" width="300">
+  </a>
+  <br>
+  <a href="https://github.com/Lexus2016/turbo_quant_memory/blob/main/assets/turbo-quant-memory-promo.mp4">Watch the 30-second demo</a>
+</p>
+
 ## The problem
 
 A long session accumulates hard-won detail about why the code is the way it is. Then the context compacts and it is gone. Next session the agent re-reads the same files, re-derives the same conclusions, and bills you for the same tokens again.
diff --git a/README.ru.md b/README.ru.md
index c018d17..a9538f4 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -21,6 +21,16 @@
 
 ---
 
+## Демо
+
+<p align="center">
+  <a href="assets/turbo-quant-memory-promo.mp4">
+    <img src="assets/turbo-quant-memory-poster.jpg" alt="30-секундное демо Turbo Quant Memory" width="300">
+  </a>
+  <br>
+  <a href="assets/turbo-quant-memory-promo.mp4">Смотрите 30-секундное демо</a>
+</p>
+
 ## Проблема
 
 За долгую сессию накапливается выстраданное понимание того, почему код именно такой. Затем контекст сжимается — и это исчезает. В следующей сессии агент перечитывает те же файлы, заново выводит те же выводы и выставляет вам счёт за те же токены.
diff --git a/README.uk.md b/README.uk.md
index 48833bf..6c44427 100644
--- a/README.uk.md
+++ b/README.uk.md
@@ -21,6 +21,16 @@
 
 ---
 
+## Демо
+
+<p align="center">
+  <a href="assets/turbo-quant-memory-promo.mp4">
+    <img src="assets/turbo-quant-memory-poster.jpg" alt="30-секундне демо Turbo Quant Memory" width="300">
+  </a>
+  <br>
+  <a href="assets/turbo-quant-memory-promo.mp4">Дивіться 30-секундне демо</a>
+</p>
+
 ## Проблема
 
 За довгу сесію накопичується вистраждане розуміння того, чому код саме такий. Далі контекст стискається — і це зникає. У наступній сесії агент перечитує ті самі файли, повторно виводить ті самі висновки й виставляє вам рахунок за ті самі токени.
diff --git a/assets/turbo-quant-memory-poster.jpg b/assets/turbo-quant-memory-poster.jpg
new file mode 100644
index 0000000..047b842
Binary files /dev/null and b/assets/turbo-quant-memory-poster.jpg differ
diff --git a/assets/turbo-quant-memory-promo.mp4 b/assets/turbo-quant-memory-promo.mp4
new file mode 100644
index 0000000..6d21d66
Binary files /dev/null and b/assets/turbo-quant-memory-promo.mp4 differ
diff --git a/pyproject.toml b/pyproject.toml
index 211c9f7..94d9a8f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -102,6 +102,11 @@ include = [
   "/LICENSE",
   "/server.json",
 ]
+# The README demo is fetched from GitHub. Keep the ~2 MB mp4 out of the sdist;
+# the poster JPEG under /assets stays.
+exclude = [
+  "/assets/*.mp4",
+]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/turbo_memory_mcp"]