diff --git a/CLAUDE.md b/CLAUDE.md
index 3b3c409..f9e5272 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -183,6 +183,7 @@ When user says **"KONIEC PRACY"**, execute in order:
 Before starting implementation, review current state of docs (see AGENTS.md for full list).
 
 ## Key Documentation
+- `docs/MEMORY.md` — project memory: known issues, confirmed patterns, ORM pitfalls, caching conventions
 - `docs/PROJECT_STRUCTURE.md` — detailed project structure and module status
 - `docs/REFACTORING_PLAN.md` — Domain migration plan and status
 - `docs/FRONTEND_REFACTORING_PLAN.md` — frontend migration plan (mostly complete)
diff --git a/docs/MEMORY.md b/docs/MEMORY.md
new file mode 100644
index 0000000..f48a7da
--- /dev/null
+++ b/docs/MEMORY.md
@@ -0,0 +1,43 @@
+# Pamięć projektu shopPRO
+
+Notatki i wnioski zebrane podczas pracy z kodem. Aktualizowane na bieżąco.
+
+---
+
+## Serwer produkcyjny
+
+- PHP < 8.0 — unikać `match`, named arguments, union types, `str_contains()` itp.
+- Zamiast `match` używać operatorów trójargumentowych (ternary) lub `if/else`
+
+## Znane problemy / TODO
+
+- `\Shared\Helpers\Helpers::send_email()` i `Shared\Email\Email::send()` — zduplikowana logika PHPMailer. Docelowo zunifikować w `Shared\Email\Email`
+- `shop\Search` — typo w `use`: `shop\Produt` zamiast `shop\Product`
+
+## Wzorce potwierdzone w projekcie
+
+- Metody frontendowe (z cache Redis) dodawane do istniejących repozytoriów Domain — NIE tworzymy osobnych FrontendService/AdminService
+- Klasy View (`front\Views\*`) są statyczne i bezstanowe — nie wymagają DI
+- Kontrolery (`Controllers\*`) są instancyjne z DI przez konstruktor
+- Autoloader obsługuje dwa formaty plików: `class.X.php` (legacy) i `X.php` (nowy) — oba działają bez zmian w autoloaderze
+- Nowe katalogi z dużej litery: `Views/`, `Controllers/` (legacy: `view/`, `controls/`, `factory/`)
+
+## Medoo ORM — pułapki
+
+- `$mdb->delete()` przyjmuje 2 argumenty (tabela, warunek), NIE 3 — wielokrotnie powodowało bugi (np. `newsletter_unsubscribe`)
+- `$mdb->get()` zwraca `null` gdy brak rekordu, NIE `false`
+- Przy `$mdb->insert()` sprawdzać `$mdb->id()` aby potwierdzić sukces
+
+## Redis cache — konwencje
+
+- TTL domyślnie 86400 (24h)
+- Klucze produktów: `shop\product:{id}:{lang}:{permutation_hash}`
+- Wzorzec czyszczenia: `CacheHandler::deletePattern("shop\\product:{$id}:*")`
+- Dane w cache są serializowane — wymagają `unserialize()` po `get()`
+
+## Aktualizacje klienckie
+
+- Pliki `*.md` NIGDY nie trafiają do ZIP aktualizacji
+- `updates/changelog.php` to plik serwisowy repozytorium, nie runtime klienta
+- Główny `.htaccess` wdrażany osobno, poza ZIP aktualizacji
+- W archiwum ZIP NIE powinno być folderu z nazwą wersji — struktura zaczyna się od katalogów projektu