Memmy na VPS: wspólna pamięć dla agentów AI

Czym jest Memmy i jakie dane przechowuje

Memmy to lokalne centrum pamięci dla agentów AI, uruchamiane na własnym VPS (wirtualnym serwerze prywatnym). Przechowuje jedną bazę danych SQLite z informacjami zdobytymi przez agentów. Każdy agent na tym serwerze odczytuje te same dane i zapisuje w nich informacje. Projekt jest memmy-agent firmy MemTensor, jest udostępniany na licencji MIT i ma wersję 1.0.4 według stanu na lipiec 2026.

Na serwerze znaczenie ma tylko część projektu. Memmy udostępnia usługę pamięci nasłuchującą na http://127.0.0.1:18960, interfejs wiersza poleceń memmy-memory (CLI), który komunikuje się z tą usługą, oraz środowisko robocze. Środowisko robocze jest dostępne wyłącznie dla systemów macOS i Windows. Na VPS z systemem Linux należy więc uruchomić usługę i CLI. To wystarczy, aby Claude Code, Codex i Cursor korzystały ze wspólnej pamięci.

Memmy dzieli przechowywane dane na cztery warstwy. L1 Trace to surowy przebieg interakcji: żądanie, odpowiedź i wywołania narzędzi. L2 Policy to procedura wyprowadzona z przebiegów, która okazała się przydatna. L3 World Model to trwała wiedza o projekcie lub środowisku. Skill to procedura możliwa do wywołania, wyodrębniona z zasad. Usługa przypisuje warstwę podczas importowania przebiegu. Nie trzeba tworzyć warstw ręcznie.

Co zmienia wspólne centrum pamięci w porównaniu z pamięcią poszczególnych narzędzi

Obecnie każdy agent ma własny mechanizm pamięci. Claude Code przechowuje pliki instrukcji w repozytorium. Cursor przechowuje reguły w bazie danych obszaru roboczego. Codex przechowuje dzienniki sesji w ~/.codex. Każdy magazyn należy do jednego narzędzia, dlatego informacja przekazana w poniedziałek jednemu narzędziu jest nieznana innemu narzędziu we wtorek. Koszt występuje dwukrotnie: w tokenach zużytych na ponowne wyjaśnianie tego samego projektu oraz w błędnych działaniach agenta opartych na założeniu, które zostało już skorygowane w innym miejscu.

Centrum przenosi magazyn poza narzędzie. Memmy odczytuje również istniejące magazyny, dlatego nie rozpoczyna pracy z pustą bazą danych. Skaner obsługuje sześć źródeł: Claude Code w ~/.claude/projects/**/*.jsonl, Codex w ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl, OpenCode w ~/.local/share/opencode/opencode.db, pliki state.vscdb programu Cursor, bazy danych SQLite programu OpenClaw w ~/.openclaw oraz Hermes w ~/.hermes. Źródło można dodać ręcznie, podając nazwę i lokalną ścieżkę.

Liczniki importu nie będą się zgadzać, co jest oczekiwane. Skaner grupuje komunikaty według źródła i konwersacji, a następnie zapisuje jedną pamięć L1 dla każdej kompletnej tury. Tura jest kompletna, gdy zawiera niepustą treść użytkownika i kończy się niepustą wiadomością asystenta, dlatego przerwana sesja nie wnosi żadnych danych. Duplikaty komunikatów są usuwane za pomocą punktów kontrolnych konwersacji i stabilnych identyfikatorów tur. Liczba przeskanowanych elementów, liczba zaimportowanych komunikatów i liczba nowych pamięci różnią się podczas tego samego uruchomienia.

To element uzupełniający sposób zarządzania kontekstem przez Claude Code w jednej sesji. Zarządzanie kontekstem określa, co mieści się w jednym oknie. Centrum pamięci określa, co pozostaje po zamknięciu tego okna.

Wymagania dotyczące VPS

• Node.js 22 lub nowszy. Dokumentacja Memmy wymaga tej wersji, a Ubuntu 24.04 dostarcza Node 18.
• git oraz zestaw narzędzi do kompilacji, ponieważ better-sqlite3 jest modułem natywnym, który może zostać skompilowany podczas instalacji.
• Około 2 GB pamięci RAM. Instalacja w katalogu root pobiera duży obszar roboczy oraz łańcuch narzędzi do kompilacji frontendu.
• Kilka GB wolnego miejsca na dysku dla node_modules i bazy danych.

sudo apt update
sudo apt install -y git build-essential python3 curl ca-certificates sqlite3
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version

Polecenie node --version powinno wyświetlić v22 lub nowszą wersję. Wartość v18 oznacza, że krok z NodeSource nie został wykonany, a instalacja zakończy się później niepowodzeniem podczas sprawdzania wersji engine projektu.

Instalowanie Memmy ze źródeł w Ubuntu 24.04

git clone https://github.com/MemTensor/memmy-agent.git
cd memmy-agent
cp .env.example .env
npm install
npm run memory:build

npm run memory:build kompiluje obszar roboczy @memmy/memory do Memory/dist. W przypadku serwera bez interfejsu graficznego nie trzeba kompilować żadnych innych elementów drzewa. Należy sprawdzić, czy moduł natywny został załadowany:

node -e "require('better-sqlite3'); console.log('better-sqlite3 loads')"

Jeśli ten wiersz zgłasza błąd zamiast wyświetlać wynik, moduł natywny nie jest zgodny z używaną wersją Node. Należy uruchomić npm rebuild better-sqlite3. Jest to dokładnie polecenie wykonywane przez własny skrypt startowy projektu przed uruchomieniem jakiegokolwiek składnika.

README opisuje bash scripts/dev-start.sh jako polecenie uruchamiające całość. Nie należy uruchamiać go na bezobsługowym VPS. Uruchamia powłokę graficzną Electron oraz serwer deweloperski Vite na porcie 19000, obok usługi pamięci. Electron wymaga środowiska graficznego, dlatego na serwerze bez sesji graficznej skrypt zatrzyma się lub zakończy działanie.

Uruchom usługę pamięci i sprawdź, czy odpowiada

npm run memory:serve:dev

Jest to udokumentowany sposób uruchamiania usługi pamięci z kodu źródłowego. Usługa nasłuchuje na 127.0.0.1:18960, przechowuje bazę danych w ~/.memmy/memory-service/memory.sqlite i odczytuje konfigurację z ~/.memmy/config.yaml. W pliku README podano te same wartości jawnie:

npm run memory:serve:dev -- \
  --host 127.0.0.1 --port 18960 \
  --db ~/.memmy/memory-service/memory.sqlite \
  --config ~/.memmy/config.yaml

W drugim powłoce sprawdź, czy usługa działa:

curl -sS http://127.0.0.1:18960/api/v1/health

Punkt końcowy sprawdzania stanu jest jedynym, który nigdy nie wymaga tokena, dlatego nadaje się do tego testu. Jeśli curl zakończy działanie kodem 7 i wyświetli komunikat Failed to connect to 127.0.0.1 port 18960, oznacza to, że nic nie nasłuchuje. Należy sprawdzić terminal, w którym działa usługa, ponieważ informacje o awarii podczas uruchamiania są wyświetlane właśnie tam. Zwykle przyczyną jest nieudane załadowanie natywnego modułu SQLite. Polecenie ss -lntp | grep 18960 potwierdza dostępność gniazda po uruchomieniu usługi.

Pozostała część interfejsu HTTP (application programming interface) znajduje się pod adresem /api/v1.

• POST /api/v1/memory/add zapisuje pamięć, a POST /api/v1/memory/search wykonuje zapytania.
• GET /api/v1/memory/:id i DELETE /api/v1/memory/:id odczytują oraz usuwają pojedynczy wpis.
• POST /api/v1/sessions/open i POST /api/v1/sessions/:sessionId/close wyznaczają początek i koniec sesji agenta.
• POST /api/v1/turns/start i POST /api/v1/turns/:turnId/complete rejestrują pojedynczą turę.
• GET /api/v1/panel/overview, /api/v1/panel/analysis i /api/v1/panel/items zasilają dashboard.

Memmy rezerwuje blok portów. W trybie bez interfejsu graficznego używany jest tylko pierwszy z nich: 18960 dla pamięci, 18970 dla sprawdzania stanu gateway, 18980 dla web UI i administracyjnego HTTP, 18990 dla interfejsu API zgodnego z OpenAI uruchamianego przez memmy serve, a następnie 19000 i 19010 dla serwera deweloperskiego frontendu desktopowego. Jeśli któryś z tych portów jest już zajęty na danym komputerze, należy sprawdzić właśnie tę listę.

Skąd faktycznie pochodzi polecenie memmy-memory

W tym miejscu zwykle występuje błąd podczas pierwszej instalacji. Należy odczytać tę informację z pakietu, zamiast jej się domyślać. Nazwa polecenia nie ma związku z nazwą repozytorium. Pochodzi z pola bin obszaru roboczego, który je definiuje:

node -p "JSON.stringify(require('./Memory/package.json').bin)"

To polecenie wyświetla {"memmy-memory":"./dist/src/cli/index.js"}. Zatem zbudowany punkt wejścia to Memory/dist/src/cli/index.js. Istnieje on dopiero po wykonaniu npm run memory:build, ponieważ proces kompilacji tworzy dist i nadaje plikowi uprawnienia do wykonywania. Należy uruchomić go bezpośrednio:

node Memory/dist/src/cli/index.js health

Aby używać krótkiej nazwy dostępnej w PATH, należy utworzyć dowiązanie do tego samego pliku:

sudo ln -s "$PWD/Memory/dist/src/cli/index.js" /usr/local/bin/memmy-memory
memmy-memory health

Interfejs CLI domyślnie używa http://127.0.0.1:18960 i akceptuje --url, --token, --config, --source oraz --user-id. Jego podpolecenia to init, health, search, add, get i delete, a także wywołania sesji i tur, z których korzystają agenty, a nie użytkownicy. memmy-memory search "deploy steps" i memmy-memory add "staging migrates on deploy" to dwa polecenia, które agent uruchamia najczęściej.

Jak połączyć Claude Code z Memmy?

Claude Code nie ma interfejsu wtyczek pamięci, dlatego Memmy nie integruje się z nim bezpośrednio. Integracja jest prostsza. Claude Code uruchamia memmy-memory jako zwykłe polecenie powłoki, a plik instrukcji określa, kiedy należy je uruchomić. Udokumentowany instalator Memmy zapisuje ten plik automatycznie: memmy-memory init --agent umieszcza plik instrukcji pamięci w katalogu reguł docelowego agenta.

Instrukcję należy raz utworzyć ręcznie, aby dokładnie wiedzieć, jakie informacje otrzymał agent. Claude Code odczytuje CLAUDE.md z katalogu głównego projektu na początku każdej sesji, dlatego poniższa sekcja wystarcza do skonfigurowania integracji:

## Memory

Before starting a task, run `memmy-memory search "<topic>"` and read what comes back.
When a task is done, run `memmy-memory add "<what you learned>"` for anything that will matter next session.

Należy jasno określić, co zapewnia takie rozwiązanie. Jest to integracja na poziomie instrukcji, więc działa tylko wtedy, gdy model zdecyduje się uruchomić polecenie. Wywołanie nie jest wymuszane. Jeśli sesja zakończy się bez add, nic nie zostanie zapisane, a jedynym sygnałem będzie pusty wynik przy następnym wyszukiwaniu. Jest to ten sam kompromis co w przypadku własnych plików pamięci Claude Code, z jedną różnicą: magazyn jest współdzielony, więc notatka jest również dostępna dla Codex i Cursor na tym samym komputerze.

Drugi kierunek nie wymaga żadnej konfiguracji. Skaner Memmy już odczytuje ~/.claude/projects/**/*.jsonl, czyli lokalizację, w której Claude Code zapisuje transkrypcje sesji. Należy uruchomić Memmy na tym samym serwerze, na którym działa Claude Code w sesji tmux, aby praca z wczoraj automatycznie stała się pamięcią.

Czy Memmy działa jako serwer MCP dla Claude Code?

Nie. Znajomość tej architektury pozwala uniknąć niepotrzebnej pracy. MCP (model context protocol) obejmuje klientów i serwery. Memmy jest klientem. Łączy się z serwerami MCP i udostępnia ich narzędzia własnemu środowisku uruchomieniowemu agenta. Nie udostępnia punktu końcowego MCP, z którym claude mcp add może się połączyć. Jedyny most MCP w repozytorium należy do integracji Composio w ramach lokalnego API aplikacji desktopowej. To API wiąże losowy port na 127.0.0.1 i używa własnego nagłówka x-memmy-mcp-token.

Konfiguracja po stronie klienta znajduje się w ~/.memmy/config.yaml, czyli w pliku wskazywanym przez MEMMY_CONFIG, w katalogu tools.mcpServers:

tools:
  mcpServers:
    example:
      type: stdio
      command: npx
      args:
        - "-y"
        - "your-mcp-server"
      toolTimeout: 30
      enabledTools:
        - "*"

type akceptuje stdio, sse oraz streamableHttp. Serwer stdio działa jako proces potomny Memmy. Oznacza to, że jego polecenie musi być dostępne na tym samym komputerze i uruchamiane przez tego samego użytkownika. Jeśli serwery MCP działają już na VPS, należy wymienić tutaj właśnie te serwery.

Zachowanie prywatności magazynu pamięci

Wszystkie dane należące do Memmy znajdują się w ~/.memmy: config.yaml, obszar roboczy, memory-service/memory.sqlite oraz pliki środowiska wykonawczego. Skanowanie i pozyskiwanie danych odbywają się lokalnie, a pamięci są zapisywane w tym lokalnym pliku SQLite, dlatego domyślna konfiguracja zapewnia rzeczywiście lokalne działanie.

Dwie ścieżki korzystają z sieci. MEMMY_CLOUD_SERVICE domyślnie wskazuje https://memmy-api.memtensor.cn i obsługuje tryb konta wraz z jego tokenami wersji próbnej, dlatego tryb klucza API nigdy z niego nie korzysta. Program ulepszania pamięci jest osobnym przełącznikiem w ustawieniach prywatności i pozostaje wyłączony do czasu jego włączenia.

Trzecią ścieżkę łatwiej przeoczyć. Po skonfigurowaniu zewnętrznego dostawcy embeddingów tekst każdej pamięci jest wysyłany do tego dostawcy, aby mógł zostać przekształcony w wektor. Lokalne przechowywanie danych nie rozwiązuje tego problemu. Jedynym sposobem na wyeliminowanie tego połączenia jest użycie własnego endpointu embeddingów.

Należy pozostawić port 18960 na adresie loopback. Nie wymaga to reguły zapory, ponieważ usługa powiązana z 127.0.0.1 nie jest w ogóle dostępna spoza tego hosta. Dostęp z laptopa należy uzyskać przez SSH:

ssh -N -L 18960:127.0.0.1:18960 you@your-vps

W przypadku powiązania usługi z szerszym adresem należy najpierw ustawić token. Ustawienie storage.token w konfiguracji albo zmiennej środowiskowej MEMMY_MEMORY_TOKEN lub MEMORY_SERVICE_TOKEN powoduje, że każdy endpoint z wyjątkiem endpointu health wymaga tokenu bearer. Wartości konfiguracji obsługują odwołania ${ENV_NAME}, dzięki czemu token i klucze API modeli pozostają poza samym plikiem. Jest to ta sama praktyka co przechowywanie sekretów poza agentami AI w pozostałych miejscach, a polityka ufw z domyślną odmową stanowi dodatkowe zabezpieczenie na wypadek zmiany domyślnego adresu powiązania w przyszłej wersji.

Wykonaj kopię zapasową ~/.memmy, zanim zaufasz temu plikowi

memory.sqlite to cała baza danych. Wektory są przechowywane w tym samym pliku za pośrednictwem rozszerzenia sqlite-vec, dlatego kopia zapasowa obejmuje jeden plik. Skopiowanie go za pomocą cp podczas zapisu przez usługę może spowodować niespójność bazy danych. Użyj wbudowanego polecenia tworzenia kopii zapasowych SQLite:

mkdir -p ~/memmy-backup
sqlite3 ~/.memmy/memory-service/memory.sqlite ".backup '$HOME/memmy-backup/memory.sqlite'"

Polecenie tworzy spójną kopię, gdy usługa nadal działa. Zgodnie z harmonogramem przesyłaj ją poza serwer. Do tego służy restic do zewnętrznej lokalizacji. Utrata config.yaml oznacza konieczność ponownego wprowadzenia ustawień dostawcy. Utrata memory.sqlite oznacza utratę wszystkich wspomnień, ponieważ na komputerze nie ma drugiej kopii.

Uruchamianie usługi pamięci za pomocą systemd

npm run memory:serve:dev uruchomione w powłoce kończy działanie razem z powłoką. Plik jednostki utrzymuje usługę po ponownym uruchomieniu systemu.

[Unit]
Description=Memmy memory service
After=network-online.target

[Service]
Type=simple
User=memmy
WorkingDirectory=/opt/memmy/memmy-agent
EnvironmentFile=/etc/memmy/memory.env
ExecStart=/usr/bin/npm run memory:serve:dev
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Token należy przechowywać poza jednostką. Należy umieścić go w /etc/memmy/memory.env, ustawić właściciela root i uprawnienia 600:

MEMMY_CONFIG=/home/memmy/.memmy/config.yaml
MEMMY_MEMORY_TOKEN=replace-this-with-a-long-random-string

sudo systemctl daemon-reload
sudo systemctl enable --now memmy-memory
systemctl status memmy-memory --no-pager
curl -sS http://127.0.0.1:18960/api/v1/health

status=203/EXEC w danych wyjściowych polecenia status oznacza, że systemd nie mogło w ogóle uruchomić ExecStart, dlatego należy sprawdzić which npm: w instalacji NodeSource jest to /usr/bin/npm, a w nvm znajduje się ono w katalogu domowym użytkownika, którego systemd nie znajdzie. Jednostka, która uruchamia się i natychmiast kończy działanie, zakończyła się błędem wewnątrz npm. Polecenie journalctl -u memmy-memory -n 50 wyświetla jego przyczynę. Mechanizm jest taki sam jak w przypadku dowolnej innej usługi systemd na VPS.

Czego Memmy jeszcze nie robi

• Nie ma kompilacji dla pulpitu Linux. Skrypty pakietowania obejmują macOS i Windows, dlatego workbench, jego kreator wdrażania oraz panel pamięci nie są dostępne bezpośrednio na serwerze.
• memory:serve:dev uruchamia punkt wejścia TypeScript za pośrednictwem tsx, czyli ścieżki deweloperskiej. Repozytorium zawiera również memory:serve dla skompilowanego wyniku. Uruchom npm run bez argumentów, aby sprawdzić, które skrypty są faktycznie dostępne w używanej kopii repozytorium.
• Mechanizm pobierania buduje okno wyszukiwania na podstawie 2,000 najnowszych wierszy wektorów, a następnie stosuje w tym oknie wybór Top-K. W bardzo dużym magazynie starsza pamięć może znajdować się poza tym oknem.
• Osadzanie jest wykonywane po przechwyceniu danych, a błąd trafia do kolejki ponownych prób zamiast blokować turę agenta. Pamięć dodana przed chwilą może jeszcze nie być dostępna w wyszukiwaniu wektorowym.
• Jeden plik SQLite oznacza jeden węzeł. Nie ma klastrowania, więc drugi serwer ma oddzielną pamięć.

Wersja 1.0.4 i około 329 gwiazdek według stanu na lipiec 2026 wskazują, że jest to młody projekt. Flagi, ścieżki i nazwy skryptów zmieniają się między wydaniami. Odczytaj pole bin oraz wynik polecenia npm run w używanej kopii repozytorium, zamiast ufać poleceniu skopiowanemu z dowolnego źródła, w tym z tego tekstu.

FAQ

Dlaczego test kondycji zwraca odmowę połączenia?

Na porcie 18960 nic nie nasłuchuje. Kod zakończenia curl 7 wraz z Failed to connect to 127.0.0.1 port 18960 oznacza, że usługa pamięci nie działa albo zakończyła pracę podczas uruchamiania. Należy odczytać terminal lub dziennik, w którym została uruchomiona. Dwie typowe przyczyny to natywny moduł better-sqlite3 niezgodny z używaną wersją Node, co naprawia npm rebuild better-sqlite3, oraz wersja Node niższa niż 22. Po uruchomieniu usługi należy potwierdzić gniazdo za pomocą ss -lntp | grep 18960.

Skąd pochodzi polecenie memmy-memory po zbudowaniu ze źródeł?

Pochodzi z pola bin pakietu obszaru roboczego @memmy/memory, a nie z nazwy repozytorium. Należy uruchomić node -p "JSON.stringify(require('./Memory/package.json').bin)" w katalogu kopii roboczej. Polecenie wyświetli {"memmy-memory":"./dist/src/cli/index.js"}. Ten plik istnieje dopiero po wykonaniu npm run memory:build, ponieważ proces budowania tworzy dist i nadaje plikowi uprawnienie wykonywania. Należy uruchamiać go jako node Memory/dist/src/cli/index.js health albo utworzyć dowiązanie symboliczne w /usr/local/bin, aby używać krótszej nazwy.

Czy można dodać Memmy do Claude Code za pomocą claude mcp add?

Nie. Memmy jest klientem MCP, a nie serwerem MCP. Nawiązuje połączenia z serwerami wymienionymi w sekcji tools.mcpServers w ~/.memmy/config.yaml i udostępnia ich narzędzia własnemu środowisku wykonawczemu. Claude Code łączy się z Memmy w odwrotny sposób, uruchamiając interfejs wiersza poleceń memmy-memory jako polecenie powłoki. Sposób działania określa plik instrukcji, który memmy-memory init --agent zapisuje w katalogu reguł agenta.

Czy uruchomienie Memmy wysyła moje wspomnienia do usługi w chmurze?

Skanowanie i pozyskiwanie danych odbywają się lokalnie, a wspomnienia są zapisywane w ~/.memmy/memory-service/memory.sqlite na własnym dysku. MEMMY_CLOUD_SERVICE wskazuje https://memmy-api.memtensor.cn w trybie konta i w przypadku tokenów wersji próbnej. Program ulepszania pamięci pozostaje wyłączony do czasu jego włączenia. Należy monitorować dostawcę embeddingów. Hostowany model embeddingów otrzymuje tekst każdego wspomnienia, które przekształca w wektor. Jeśli ma to znaczenie, należy użyć punktu końcowego uruchomionego samodzielnie.