MemoryAI Local (Windows)

Wersja testowa (alpha/beta). To wczesna, publicznie udostępniona wersja projektu, testowana głównie w CI, nie na szerokiej flocie realnych maszyn użytkowników. Może zawierać błędy. Chętnie poznam Twoją opinię, uwagi i zgłoszenia problemów, najlepiej przez Issues w tym repozytorium, będę je na bieżąco poprawiać.

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.

Related MCP server: BaseGrid MCP Server

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.

Domyślnie wszystko (modele, baza, indeks dokumentów) działa lokalnie, bez połączenia z internetem po jednorazowym pobraniu wag modeli.

Instalacja

Pobierz najnowszy instalator (MemoryAI.Local_<wersja>_x64-setup.exe) z zakładki 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.

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, 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, session_end, rag_search
                          - 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.

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ł

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.

CI

• 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, 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.

• 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,

• testy antywirusowe (Defender + 2 popularne AV), 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, lista objaw → przyczyna → naprawa, gotowa do wklejenia w odpowiedzi na zgłoszenie.

Licencja

Projekt jest udostępniony na licencji MIT, pełna treść w pliku LICENSE. W skrócie: możesz go dowolnie używać, kopiować, modyfikować i rozpowszechniać, także komercyjnie, pod warunkiem zachowania noty o prawach autorskich. Kod jest dostarczany "tak jak jest", bez gwarancji.