# MemoryAI Local (Windows)

W pełni lokalna, offline wersja MemoryAI, trwała pamięć długoterminowa
dla Claude Desktop, dystrybuowana jako jeden instalator `.exe` dla Windows.
Bez Dockera, bez Postgresa, bez terminala. Dane nigdy nie opuszczają dysku,
chyba że użytkownik świadomie włączy opcjonalny tryb chmurowy.

## Po co to jest, w praktyce

Zastanawiałeś się kiedyś, dlaczego Claude zapomina wszystko, o czym
rozmawialiście wczoraj? Domyślnie każda nowa rozmowa zaczyna się od zera, za każdym razem musisz od nowa tłumaczyć swój projekt, przypominać podjęte
decyzje i powtarzać swoje preferencje. MemoryAI Local to rozwiązuje: daje
Claude prawdziwą, długoterminową pamięć oraz możliwość czytania Twoich
własnych dokumentów, całkowicie offline i bez konfigurowania czegokolwiek.

**Planowanie projektu.** Zanim: pracowałeś z Claude nad pomysłem na biznes
cały weekend, a w poniedziałek otwierasz nową rozmowę i asystent nie
pamięta niczego, trzeba znowu opisywać założenia od podstaw. Po: piszesz
po prostu "kontynuujmy pracę nad biznesplanem", a Claude sam wraca do
tematu, dokładnie tam, gdzie skończyliście w weekend.

**Szukanie w swoich dokumentach.** Zanim: chcesz zapytać o konkretny
fragment własnego pliku PDF, musisz go ręcznie otworzyć, znaleźć akapit,
skopiować i wkleić do czatu. Po: wskazujesz folder ze swoimi plikami raz,
przy pierwszym uruchomieniu, i od tej pory pytasz wprost: "sprawdź w moich
dokumentach, jakie były założenia budżetu na ten rok", a Claude sam
znajduje właściwą treść.

**Zero konfiguracji.** Nie musisz znać się na programowaniu. Pobierasz
jeden plik instalacyjny, klikasz kilka razy "Dalej" i gotowe, bez
terminala, bez dodatkowych narzędzi. Wszystko liczy się na Twoim własnym
komputerze, a Twoje pliki i wspomnienia z rozmów nigdy nie opuszczają dysku.

## Dla kogo to jest

Dla użytkownika Claude Desktop, który chce, żeby Claude pamiętał rozmowy
między sesjami i umiał przeszukiwać jego własne dokumenty, ale nie chce (i
nie musi umieć) instalować Node.js, Pythona, Dockera ani edytować plików
konfiguracyjnych ręcznie. Cała instalacja to pobranie jednego pliku,
kilka kliknięć "Dalej" i restart Claude Desktop.

## Co robi

- **Trwała pamięć rozmów**: zapis, wyszukiwanie hybrydowe (wektorowe +
  pełnotekstowe) i automatyczna dystylacja sesji do zwięzłych wspomnień.
- **Lokalny RAG na własnych dokumentach**: wskazujesz jeden folder
  (`.doc`, `.docx`, `.pdf`, `.txt`), a MemoryAI Local go indeksuje i
  pilnuje na bieżąco (nowe/zmienione/usunięte pliki), żeby Claude mógł
  przeszukiwać jego treść w rozmowie.
- **Panel ustawień w zasobniku systemowym**: bo Claude Desktop sam w sobie
  nie ma miejsca na onboarding ani konfigurację MCP.
- **Opcjonalny tryb chmurowy**: jeśli wolisz oddać dystylację/embedding
  zewnętrznemu dostawcy (Anthropic/OpenAI/Gemini) zamiast liczyć lokalnie,
  możesz to włączyć w ustawieniach; klucze API trzymane są w Windows
  Credential Manager, nigdy plaintext w plikach configu.
- **Drugie, niezależne wyszukiwanie w sieci (opcjonalne)**: narzędzie MCP
  `web_search_gemini` odpytuje Google Search przez oficjalne, darmowe API
  Gemini (Google AI Studio) - przydatne obok wbudowanego wyszukiwania Claude
  Desktop (opartego o Brave), gdy chcesz zestawić wynik z dwóch niezależnych
  wyszukiwarek. Włącza się automatycznie, gdy w ustawieniach zapisano klucz
  API dla dostawcy "Google Gemini" (ten sam klucz co dla trybu chmurowego
  wyżej) - bez klucza narzędzie zwraca czytelną instrukcję zamiast błędu.
- **Web chat (opcjonalne, eksperymentalne)**: zestaw narzędzi MCP, które
  odpytują realne, zalogowane sesje webowe zamiast płatnych API - kosztem
  znacznie wolniejszej odpowiedzi (dziesiątki sekund do kilku minut) i
  jednorazowego pobrania przeglądarki Chromium (ok. 150-200 MB, osobno od
  instalatora - patrz ekran "Web chat" w ustawieniach). Każdy dostawca wymaga
  osobnego, ręcznego zalogowania się w widocznym oknie przeglądarki przy
  pierwszym uruchomieniu:
  - `ask_gemini_web` - pyta czat webowy Gemini (gemini.google.com/app),
    inny model/jakość niż darmowe API w `web_search_gemini` wyżej.
  - `generate_gemini_web_image` - prosi Gemini web o wygenerowanie obrazu z
    opisu tekstowego, zapisywanego jako lokalny plik.
  - `ask_perplexity_web` - pyta czat webowy Perplexity (perplexity.ai),
    odpowiedzi zwykle z cytowanymi źródłami z żywego wyszukiwania, dobre
    jako niezależne zestawienie z Gemini.
  - `notebooklm_generate` - wgrywa źródło (URL lub tekst) do nowego
    notatnika w NotebookLM i generuje z niego audio overview (podcast MP3),
    skrót do nauki (study guide) lub streszczenie; najwolniejsze z tej
    grupy (realnie minuty, nie sekundy).

  **Automatyzacja czatu webowego może naruszać regulamin danego serwisu -
  to najbardziej opcjonalny tryb ze wszystkich, świadomie oznaczony jako
  eksperymentalny i używany na własne ryzyko, na własnym koncie.**

Domyślnie wszystko (modele, baza, indeks dokumentów) działa lokalnie, bez
połączenia z internetem po jednorazowym pobraniu wag modeli - poza tymi
jawnie opt-in wyjątkami opisanymi wyżej.

## Instalacja

Pobierz najnowszy instalator (`MemoryAI.Local_<wersja>_x64-setup.exe`) z zakładki
[Releases](https://github.com/cenkierpiotr/memoryai-local-windows2/releases)
i uruchom instalator. Nie wymaga uprawnień administratora.

Instalator jest celowo mały (kilkadziesiąt MB). Modele (embedding +
dystylacja) pobiera przy pierwszym uruchomieniu kreator pierwszego
uruchomienia, z obsługą wznawiania przerwanego pobierania i weryfikacją
SHA-256 każdego pliku. Przeglądarka Chromium potrzebna do opcjonalnego
"Web chat (Gemini)" (patrz wyżej) pobiera się dopiero po świadomym włączeniu
tej funkcji w ustawieniach - nie jest częścią instalatora ani kreatora
pierwszego uruchomienia.

**Wymagania:** Windows 10 (22H2+) lub Windows 11, x64. Nie wymaga
zainstalowanego Node.js, Pythona ani VC++ Redistributable, instalator
zawiera własny prywatny runtime Node oraz (jako zabezpieczenie) VC++
Redistributable x64.

**Aktualizacje:** brak automatycznego mechanizmu aktualizacji (świadomie,
nie planowane), nowa wersja to ręczne pobranie i uruchomienie kolejnego
instalatora z zakładki Releases, gdy się pojawi. Instalacja nowszej wersji
nie usuwa istniejącej bazy pamięci ani pobranych modeli (żyją osobno w
`%APPDATA%`).

### Ostrzeżenie Windows SmartScreen

Przy pierwszym uruchomieniu instalatora Windows może pokazać niebieski ekran
"Windows chronił Twój komputer" / "Nierozpoznana aplikacja". To **nie jest
wykrycie złośliwego oprogramowania**: to domyślne zachowanie SmartScreen dla
każdego nowego pliku `.exe`, który nie ma jeszcze podpisu cyfrowego (Authenticode)
opłaconego u zaufanego wystawcy certyfikatów. Instalator nie jest obecnie
podpisany (świadoma decyzja poza zakresem v1, patrz `docs/project-plan.md`),
więc ostrzeżenie pojawi się niezależnie od tego, jak bezpieczny jest kod w
środku.

Aby kontynuować instalację:

1. Na ekranie ostrzeżenia kliknij **"Więcej informacji"** ("More info").
2. Pojawi się nazwa pliku i przycisk **"Uruchom mimo to"** ("Run anyway"), kliknij go.

Jeśli chcesz zweryfikować integralność pobranego pliku przed uruchomieniem,
porównaj sumę SHA-256 z plikiem `.sha256.txt` dołączonym do tego samego
wydania w sekcji Releases (checksuma jest liczona i publikowana
automatycznie przy każdym tagowanym wydaniu przez
`.github/workflows/desktop-windows.yml`, budowana na realnym `windows-latest`
runnerze, nie cross-compile).

### Ostrzeżenia antywirusowe

Niezależnie od SmartScreen, program antywirusowy (Windows Defender lub inny
zainstalowany) może dodatkowo oznaczyć instalator lub proces w tle jako
podejrzany, z tego samego powodu (brak podpisu cyfrowego), a czasem też
dlatego, że aplikacja uruchamia lokalny model AI (wzorzec zachowania podobny
do niektórych narzędzi typu "cheat"/"stealer" dla silników heurystycznych
AV, mimo że kod nie robi nic złośliwego). Jeśli AV zablokuje lub usunie
plik, to fałszywy alarm (false positive), nie realne zagrożenie. Sprawdź
sumę SHA-256 z Releases, żeby potwierdzić, że plik nie został podmieniony,
i dodaj wyjątek w swoim AV dla folderu instalacji. Protokół testów pod
popularne silniki AV (Defender + 2 inne) jest udokumentowany w
[`docs/av-tests.md`](docs/av-tests.md), obecnie jako procedura do wykonania
przy pierwszym dostępie do licencji testowych (patrz "Status projektu"
niżej), nie jako już potwierdzony wynik.

### Pierwsze uruchomienie

Po instalacji kreator (Tauri, React) przeprowadza przez:
1. wybór tieru modelu dystylacji (`3b` dla maszyn z <16GB RAM, `7b` dla
   ≥16GB, przełączalne później w ustawieniach),
2. pobranie modeli (embedding ModernBERT ~68M param. + dystylacja Qwen2.5,
   GGUF, kwantyzowane),
3. opcjonalny wybór folderu do indeksowania RAG,
4. automatyczne dopisanie wpisu serwera MCP do `claude_desktop_config.json`
   metodą merge (istniejące wpisy innych serwerów MCP zostają nietknięte),
5. restart Claude Desktop.

## Architektura

Trzy niezależne procesy komunikujące się wyłącznie przez współdzieloną bazę
SQLite (WAL), żaden z nich nie jest właścicielem długo żyjącego stanu, który
inne muszą znać w czasie rzeczywistym poza pollingiem tabeli `settings`:

```
MemoryAI Tray (Tauri/Rust, autostart)          MemoryAI Ingest Worker (Node)
  - ikona w zasobniku, panel ustawień            - chokidar na folderze RAG
  - kreator pierwszego uruchomienia              - kolejka, chunking, embedding
  - zarządza cyklem życia workera                - kończy się po bezczynności
  - Windows Credential Manager, autostart         (domyślnie 5 min)
        |                                                |
        '--------------------  SQLite (WAL) --------------------'
                                    |
                        MemoryAI MCP Server (Node)
                          - spawnowany on-demand przez Claude Desktop (stdio)
                          - narzędzia: memory_save, memory_search,
                            memory_get_context, entity_save, entity_get,
                            session_end, rag_search, web_search_gemini,
                            ask_gemini_web, ask_perplexity_web,
                            notebooklm_generate, generate_gemini_web_image
                          - zero RAM gdy Claude Desktop nie jest uruchomiony
```

Silnik inferencji to `node-llama-cpp` (GGUF, CPU-only) dla obu modeli:
embedding `PKOBP/embed-modernbert-68m` (512-dim, ~300MB RAM) oraz dystylacja
`qwen2.5-instruct` w tierach `3b`/`7b`. Storage to SQLite + `sqlite-vec`
(wektory) + FTS5 (pełny tekst), łączone przez RRF (Reciprocal Rank Fusion), lokalny odpowiednik produkcyjnego stosu Postgres+pgvector+Redis.

Pełne uzasadnienie decyzji architektonicznych (framework UI, silnik
inferencji, format storage, model procesów) znajdziesz w
[`docs/project-plan.md`](docs/project-plan.md).

## Struktura repozytorium

Monorepo pnpm workspaces (Node 24+) z jednym podprojektem Rust wewnątrz
aplikacji desktop.

```
memoryai-local-windows/
├─ packages/
│  ├─ core/            # logika bez I/O procesowego: db, search (vec+FTS5+RRF),
│  │                    # llm (wrapper node-llama-cpp), dystylacja, chunking,
│  │                    # adaptery chmurowe, config, logging - reużywane
│  │                    # identycznie w mcp-server i ingest-worker
│  ├─ mcp-server/      # entrypoint stdio, definicje narzędzi MCP
│  ├─ ingest-worker/   # chokidar + kolejka + parsery (pdf-parse, mammoth) + embedding
│  ├─ model-manager/   # downloader modeli: HTTP Range, SHA-256, retry, mirror
│  └─ claude-config/   # merge wpisu MCP do claude_desktop_config.json
├─ apps/
│  └─ desktop/         # Tauri v2: tray, kreator, panel ustawień (React + TS)
│     └─ src-tauri/    # Rust: tray, single-instance, autostart, Credential Manager
├─ docs/               # plan architektury, testy chaosu/AV/wydajności, runbook
├─ tools/               # konwersja modeli HF→GGUF, generowanie manifestu, publikacja
└─ tests/e2e/           # scenariusze na czystej maszynie/VM
```

`packages/core` celowo nie importuje niczego procesowo-specyficznego (bez
`process.stdin`, bez chokidar, bez Tauri), dzięki temu ten sam kod
wyszukiwania i dystylacji działa identycznie w MCP serverze i w workerze, a
testy jednostkowe nie wymagają uruchamiania procesów.

## Rozwój / budowanie ze źródeł

```bash
pnpm install --frozen-lockfile
pnpm run build       # build wszystkich pakietów workspace
pnpm run test        # testy jednostkowe (vitest), wszystkie workspace'y
pnpm run typecheck   # tsc --noEmit dla wszystkich workspace'ów
pnpm run lint        # eslint .
```

Pełny instalator `.exe` (NSIS, przez Tauri) wymaga realnego Windows z
toolchainem Rust (MSVC target), budowany automatycznie w CI na
`windows-latest` (zobacz niżej), nie jest częścią standardowego `pnpm run build`
na innych platformach.

**Pułapka przy lokalnym/ręcznym buildzie Tauri po zmianie w `packages/mcp-server`:**
bundlowanie serwera MCP przez esbuild (`node scripts/bundle.mjs` w
`packages/mcp-server`, wynik: `dist-bundle/mcp-server.js`) to **osobny, ręczny
krok**, którego `pnpm run build` w `apps/desktop` NIE wywołuje (tam jest tylko
`tsc --noEmit && vite build` frontendu). `tauri.conf.json` traktuje
`apps/desktop/src-tauri/resources/mcp-server.js` jako statyczny plik zasobów,
nie jako wynik builda — trzeba go ręcznie nadpisać świeżym bundlem przed każdym
buildem Tauri, który dotyka kodu `packages/mcp-server`:

```bash
cd packages/mcp-server && node scripts/bundle.mjs
cp dist-bundle/mcp-server.js ../../apps/desktop/src-tauri/resources/mcp-server.js
```

Pominięcie tego kroku daje build, który wygląda na aktualny (kompiluje się,
testy przechodzą), ale niesie stary bundle serwera MCP w środku instalatora —
zdarzyło się to realnie 04.09.2026 (zob. `docs/runbook.md`).

### CI

- [`ci.yml`](.github/workflows/ci.yml), na każdy push: build, test, lint,
  typecheck równolegle na `ubuntu-latest` i `windows-latest`. To jedyne
  miejsce, gdzie kod jest realnie sprawdzany na prawdziwym Windows przy
  bieżącej pracy. Testy przechodzące lokalnie na Linuksie nie gwarantują
  przejścia na Windows (różnice w semantyce systemu plików, blokadach
  uchwytów itp.), dlatego ten job jest obowiązkowy przy każdej zmianie.
- [`desktop-windows.yml`](.github/workflows/desktop-windows.yml), pełny
  build instalatora NSIS na `windows-latest`, uruchamiany **wyłącznie** na
  tagach `v*` oraz ręcznie (`workflow_dispatch`). Świadomie nie na każdym
  pushu. Pełny build Tauri kosztuje realne minuty Actions. Przy tagu
  publikuje `.exe` + `.sha256.txt` bezpośrednio do GitHub Release.

## Prywatność i dane

- Baza pamięci i indeks RAG żyją w `%APPDATA%` użytkownika, w SQLite.
- Domyślnie żadne dane nie opuszczają maszyny, modele liczą lokalnie (CPU).
- Tryb chmurowy jest opt-in, wyłączony domyślnie; klucze API są trzymane w
  Windows Credential Manager, nigdy w plikach konfiguracyjnych plaintext.
- **Deinstalacja**: przycisk "Odinstaluj" w panelu ustawień (zakładka
  Advanced) lub standardowa deinstalacja z Windows uruchamiają ten sam
  deinstalator NSIS. Domyślny deinstalator usuwa tylko katalog instalacji
  (pliki programu), NIE dane użytkownika. Baza wspomnień i pobrane modele
  leżą osobno w `%APPDATA%`. Zaraz po zakończeniu deinstalacji pojawia się
  osobne okno Tak/Nie: "Czy chcesz również usunąć dane aplikacji (baza
  wspomnień i pobrane modele AI)? Tej operacji NIE MOŻNA cofnąć", domyślnie zaznaczone "Nie", żeby przypadkowe kliknięcie nie skasowało
  danych (`apps/desktop/src-tauri/nsis-hooks.nsh`).

## Najczęstsze problemy

Skrót: pełna lista objaw → przyczyna → naprawa jest w
[`docs/runbook.md`](docs/runbook.md).

- **Claude Desktop po restarcie nie widzi MemoryAI Local**: sprawdź, czy
  wpis pojawił się w `claude_desktop_config.json` (kreator dopisuje go
  automatycznie po pierwszym uruchomieniu); jeśli plik był otwarty w innym
  edytorze w trakcie instalacji, zapis mógł się nie powieść. Uruchom
  ponownie kreator z panelu ustawień w zasobniku.
- **Ikona w zasobniku systemowym nie pojawia się po restarcie komputera**: sprawdź w Menedżerze zadań (zakładka Uruchamianie), czy autostart
  MemoryAI Local jest włączony; można go też włączyć ręcznie w panelu
  ustawień.
- **Pobieranie modeli w kreatorze się zatrzymuje/nie startuje**: najczęściej
  to tymczasowy problem sieci lub blokada przez firewall/AV; pobieranie
  wznawia się automatycznie od miejsca przerwania po ponownym uruchomieniu
  kreatora, nie zaczyna od zera.
- **Wyszukiwanie w RAG nie zwraca nic z nowo dodanego pliku**: Ingest
  Worker indeksuje pliki asynchronicznie w tle; dla dużych plików (duże
  PDF-y) to może potrwać dłużej niż jedno odświeżenie. Sprawdź status
  indeksowania w panelu ustawień, zanim uznasz to za błąd.

## Status projektu

Fazy 0-6 planu (`docs/project-plan.md`) ukończone w zakresie osiągalnym bez
fizycznego dostępu do zewnętrznego sprzętu Windows/licencji AV/testerów
zewnętrznych, CI zielone na Linux i Windows. Świadomie zamrożone jako
udokumentowane wyjątki v1 (procedury gotowe do wykonania przy pierwszym
dostępie do takich zasobów):

- pełna matryca sprzętowa (kombinacje Win10/11, RAM, SSD/HDD, ścieżki z
  polskimi znakami, OneDrive on-demand), [`docs/test-matrix.md`](docs/test-matrix.md),
- testy antywirusowe (Defender + 2 popularne AV), [`docs/av-tests.md`](docs/av-tests.md),
- beta z realnymi nietechnicznymi testerami.

Poza zakresem v1 świadomie: wiele folderów RAG jednocześnie, reranker,
podpis cyfrowy instalatora, macOS/Linux, synchronizacja między urządzeniami,
GPU-first inference, UI wielojęzyczne (tylko PL + EN), automatyczne
aktualizacje.

Diagnostyka i znane problemy: [`docs/runbook.md`](docs/runbook.md), lista
objaw → przyczyna → naprawa, gotowa do wklejenia w odpowiedzi na zgłoszenie.

## O tym repozytorium

To publiczny snapshot projektu MemoryAI Local, aktualizowany okresowo (nie
przy każdym commicie) z prywatnego repozytorium rozwojowego. Historia gita
tutaj jest świadomie uproszczona do pojedynczych, czystych commitów per
wydanie, zamiast pełnej historii commitów roboczych.

## Licencja

Zobacz plik [`LICENSE`](LICENSE).