Memmy installeren op een VPS voor gedeeld AI-geheugen

Wat Memmy is en wat het opslaat

Memmy is een lokale geheugenhub voor AI-agents die op uw eigen VPS (virtual private server) draait. Het beheert één SQLite-database met de opgedane kennis van uw agents, waarbij elke agent op de server naar hetzelfde opslagpunt leest en schrijft. Het project is memmy-agent van MemTensor, valt onder de MIT-licentie en bevindt zich per juli 2026 in versie 1.0.4.

Slechts een deel hiervan is relevant op een server. Memmy levert een memory service die luistert op http://127.0.0.1:18960, een memmy-memory command line interface (CLI) die met die service communiceert, en een desktop workbench. De workbench is alleen verpakt voor macOS en Windows; op een Linux VPS draait u daarom de service en de CLI. Dit is voldoende om Claude Code, Codex en Cursor een gedeeld geheugen te geven.

Memmy sorteert de opgeslagen gegevens in vier lagen. L1 Trace is de ruwe interactie: het verzoek, het antwoord en de tool-aanroepen. L2 Policy is een procedure die is afgeleid van traces die nuttig bleken. L3 World Model is stabiele kennis over een project of een omgeving. Skill is een aanroepbare procedure die is gekristalliseerd uit een policy. De service wijst een laag toe wanneer deze een interactie verwerkt, waardoor u deze niet handmatig hoeft aan te maken.

Wat een gedeelde geheugenhub verandert ten opzichte van geheugen per tool

Elke agent gebruikt tegenwoordig zijn eigen geheugen. Claude Code bewaart instructiebestanden in de repository. Cursor houdt regels bij in de workspace-database. Codex slaat sessielogs op onder ~/.codex. Elke opslag hoort bij één tool, waardoor een feit dat u op maandag in de ene tool hebt aangeleerd, op dinsdag onbekend is in de andere. U betaalt daar dubbel voor: eenmaal in tokens die worden verbruikt om hetzelfde project opnieuw uit te leggen, en eenmaal in foutief werk wanneer een agent handelt op basis van een aanname die u elders al hebt gecorrigeerd.

Een hub verplaatst de opslag buiten de tool. Memmy leest ook de bestaande opslaglocaties, zodat u niet met een lege database begint. De scanner herkent zes bronnen: Claude Code op ~/.claude/projects/**/*.jsonl, Codex op ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl, OpenCode op ~/.local/share/opencode/opencode.db, de state.vscdb-bestanden van Cursor, de SQLite-databases van OpenClaw onder ~/.openclaw en Hermes onder ~/.hermes. U kunt handmatig een bron toevoegen met een naam en een lokaal pad.

De importtellers zullen niet overeenkomen, en dat is te verwachten. De scanner groepeert berichten per bron en conversatie en schrijft vervolgens één L1-geheugen per volledige interactie. Een interactie telt als volledig wanneer deze niet-lege gebruikersinhoud bevat en eindigt met een niet-leeg assistentbericht; een onderbroken sessie draagt dus niets bij. Berichten worden ontdubbeld met behulp van conversatie-checkpoints en stabiele interactie-ID's. Het aantal gescande items, het aantal geïmporteerde berichten en het aantal nieuwe geheugenitems verschillen allemaal tijdens dezelfde run.

Dit is het onderdeel dat aansluit bij hoe Claude Code context beheert binnen één sessie. Contextbeheer bepaalt wat er in één venster past. Een geheugenhub bepaalt wat er overblijft nadat dat venster is gesloten.

Wat u nodig heeft op de VPS

• Node.js 22 of nieuwer. De Memmy-documentatie vereist dit, en Ubuntu 24.04 levert standaard Node 18.
• git en een build-toolchain, omdat better-sqlite3 een native module is die tijdens de installatie gecompileerd kan worden.
• Ongeveer 2 GB RAM. De root-installatie haalt een grote workspace en een frontend-buildchain op.
• Enkele GB's vrije schijfruimte voor node_modules en de database.

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

node --version hoort v22 of hoger weer te geven. Een v18 hier betekent dat de NodeSource-stap niet is geslaagd, waardoor de installatie later zal falen bij de engine-controle van het project.

Memmy installeren vanaf broncode op 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 compileert de @memmy/memory-workspace naar Memory/dist. Voor een headless server hoeft er niets anders in de boomstructuur gebouwd te worden. Controleer of de native module is geladen:

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

Als die regel een foutmelding geeft in plaats van uitvoer, komt de native module niet overeen met uw Node-versie. Voer npm rebuild better-sqlite3 uit; dit is precies wat het startscript van het project zelf doet voordat het iets opstart.

De README documenteert bash scripts/dev-start.sh als een commando om alles in één keer te starten. Voer dit niet uit op een headless VPS. Het start de Electron desktop-shell en een Vite dev-server op poort 19000 naast de memory-service. Omdat Electron een display vereist, zal het script op een server zonder grafische sessie blijven hangen of afsluiten.

Start de memory service en controleer of deze reageert

npm run memory:serve:dev

Dit is de gedocumenteerde manier om de memory service vanuit de broncode uit te voeren. Deze bindt 127.0.0.1:18960, houdt de database bij op ~/.memmy/memory-service/memory.sqlite en leest de configuratie van ~/.memmy/config.yaml. De README vermeldt dezelfde waarden wanneer u ze expliciet wilt opgeven:

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

Vraag vanuit een tweede terminal of de service actief is:

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

Health is het enige endpoint dat nooit om een token vraagt; daarom is dit de juiste probe. Als curl afsluit met code 7 en een Failed to connect to 127.0.0.1 port 18960-melding, luistert er niets. Lees de terminal waarin de service draait, aangezien een crash bij het opstarten daar wordt weergegeven. De meest voorkomende oorzaak is het niet kunnen laden van de native SQLite-module. ss -lntp | grep 18960 bevestigt de socket zodra de service actief is.

De rest van de HTTP API (application programming interface) bevindt zich onder /api/v1.

• POST /api/v1/memory/add schrijft naar het geheugen en POST /api/v1/memory/search voert queries uit.
• GET /api/v1/memory/:id en DELETE /api/v1/memory/:id lezen en verwijderen één item.
• POST /api/v1/sessions/open en POST /api/v1/sessions/:sessionId/close omsluiten een agentsessie.
• POST /api/v1/turns/start en POST /api/v1/turns/:turnId/complete leggen één beurt vast.
• GET /api/v1/panel/overview, /api/v1/panel/analysis en /api/v1/panel/items voeden het dashboard.

Memmy reserveert een blok poorten; headless gebruikt u alleen de eerste: 18960 voor memory, 18970 voor gateway health, 18980 voor de web-UI en admin HTTP, 18990 voor de OpenAI-compatibele API die memmy serve start, en vervolgens 19000 en 19010 voor de dev-server van de desktop-frontend. Als een andere service op uw systeem een van deze poorten bezet houdt, is dit de lijst waar u moet zoeken.

Waar het commando memmy-memory vandaan komt

Dit is het punt waar een eerste installatie meestal misgaat; lees het daarom in het pakket in plaats van te gokken. De naam van het commando heeft niets te maken met de naam van de repository. Het is afkomstig uit het bin-veld van de workspace waarin het is gedefinieerd:

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

Dit geeft {"memmy-memory":"./dist/src/cli/index.js"} weer. Het gebouwde entry point is dus Memory/dist/src/cli/index.js, en dit bestaat pas na npm run memory:build, omdat het build-proces dist aanmaakt en het bestand uitvoerbaar maakt. Voer het direct uit:

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

Als u de korte naam in uw PATH wilt hebben, maak dan een link naar datzelfde bestand:

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

De CLI gebruikt standaard http://127.0.0.1:18960 en accepteert --url, --token, --config, --source en --user-id. De subcommando's zijn init, health, search, add, get en delete, plus session- en turn-aanroepen die door agents worden gebruikt in plaats van door mensen. memmy-memory search "deploy steps" en memmy-memory add "staging migrates on deploy" zijn de twee die een agent het meest uitvoert.

Hoe verbindt u Claude Code met Memmy?

Claude Code beschikt niet over een interface voor memory-plugins, waardoor Memmy hier niet direct op inhaakt. De integratie is eenvoudiger. Claude Code voert memmy-memory uit als een standaard shell-commando, en een instructiebestand geeft aan wanneer dit moet gebeuren. Het gedocumenteerde installatieprogramma van Memmy schrijft dit bestand voor u: memmy-memory init --agent plaatst een geheugeninstructiebestand in de rules-directory van de doelagent.

Schrijf de instructie eenmaal handmatig, zodat u precies weet wat er aan de agent is meegegeven. Claude Code leest CLAUDE.md aan het begin van elke sessie vanuit de project root, dus een sectie zoals deze vormt de volledige integratie:

## 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.

Wees duidelijk over wat dit u oplevert. Het betreft integratie op instructieniveau, wat betekent dat het alleen werkt wanneer het model besluit het commando uit te voeren. Niets dwingt de aanroep af. Als een sessie eindigt zonder de add, is er niets opgeslagen en is het enige signaal een leeg resultaat bij de volgende zoekopdracht. Dit is dezelfde afweging als bij de eigen geheugenbestanden van Claude Code, met één verschil: de opslag wordt gedeeld, waardoor de notitie ook Codex en Cursor op dezelfde machine bereikt.

Voor de andere richting is geen configuratie vereist. De scanner van Memmy leest reeds ~/.claude/projects/**/*.jsonl, de locatie waar Claude Code zijn sessietranscripties schrijft. Voer Memmy uit op dezelfde server waar u Claude Code binnen een tmux-sessie draait, en het werk van gisteren wordt automatisch geheugen zonder dat u iets hoeft te configureren.

Werkt Memmy als een MCP-server voor Claude Code?

Nee, en het kennen van deze richting bespaart u een middag werk. MCP (model context protocol) kent clients en servers. Memmy is een client. Het maakt verbinding met MCP-servers en stelt hun tools beschikbaar aan zijn eigen agent-runtime. Het publiceert geen MCP-endpoint waar claude mcp add naar kan verwijzen. De enige MCP-bridge in de repository hoort bij de Composio-integratie binnen de lokale desktop-API, en die API bindt een willekeurige poort op 127.0.0.1 achter zijn eigen x-memmy-mcp-token-header.

De client-zijde wordt geconfigureerd in ~/.memmy/config.yaml, het bestand waar MEMMY_CONFIG naar verwijst, onder tools.mcpServers:

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

type accepteert stdio, sse en streamableHttp. Een stdio-server draait als een onderliggend proces van Memmy, wat betekent dat het commando op dezelfde machine moet bestaan en onder dezelfde gebruiker moet draaien. Als u al MCP-servers op een VPS laat draaien, zijn dat de servers die u hier moet opgeven.

De geheugenopslag privé houden

Alles wat Memmy bezit, bevindt zich onder ~/.memmy: config.yaml, de werkruimte, memory-service/memory.sqlite en runtime-bestanden. Scannen en opname vinden lokaal plaats en herinneringen worden naar dat lokale SQLite-bestand geschreven, waardoor de standaardinstelling daadwerkelijk lokaal is.

Twee paden bereiken het netwerk. MEMMY_CLOUD_SERVICE staat standaard op https://memmy-api.memtensor.cn en ondersteunt de accountmodus met proeftokens, waardoor de API-sleutelmodus deze nooit aanroept. Het programma voor geheugenverbetering is een afzonderlijke schakelaar in de privacyinstellingen, die uitgeschakeld is totdat u deze zelf inschakelt.

Een derde pad is makkelijker over het hoofd te zien. Als u een gehoste embedding-provider configureert, wordt de tekst van elke herinnering naar die provider verzonden zodat deze kan worden omgezet in een vector. Lokale opslag helpt daar niet. Een embedding-endpoint dat u zelf host, is de enige manier om dit af te sluiten.

Houd poort 18960 op het loopback-adres. Hiervoor is geen firewallregel nodig, omdat een service die gebonden is aan 127.0.0.1 vanaf een andere machine helemaal niet bereikbaar is. Benader deze in plaats daarvan vanaf uw laptop via SSH:

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

Als u deze ooit breder bindt, stel dan eerst een token in. Door storage.token in de configuratie in te stellen, of de omgevingsvariabele MEMMY_MEMORY_TOKEN of MEMORY_SERVICE_TOKEN te gebruiken, vereist elk endpoint behalve health een bearer-token. Configuratie-waarden ondersteunen ${ENV_NAME}-verwijzingen, zodat het token en uw model API-sleutels buiten het bestand zelf blijven. Dat is dezelfde gewoonte als geheimen buiten AI-agents houden op andere plekken, en een default deny ufw-beleid is uw vangnet voor het geval een toekomstige versie het standaard bind-adres wijzigt.

Maak een back-up van ~/.memmy voordat u erop vertrouwt

memory.sqlite is de volledige opslag. De vectoren bevinden zich in hetzelfde bestand via de sqlite-vec-extensie, dus één bestand vormt de back-up. Het kopiëren hiervan met cp terwijl de service schrijft, kan leiden tot een inconsistente database. Gebruik het ingebouwde back-upcommando van SQLite:

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

Dit genereert een consistente kopie terwijl de service blijft draaien. Verplaats deze kopie volgens een schema naar een externe locatie; hiervoor is restic naar externe opslag bedoeld. Het verlies van config.yaml kost u providerinstellingen die u opnieuw kunt invoeren. Het verlies van memory.sqlite kost u al uw herinneringen, en er is geen andere kopie aanwezig op de machine.

De memory service uitvoeren onder systemd

npm run memory:serve:dev in een shell stopt zodra de shell wordt afgesloten. Een unit-bestand houdt de service actief na een herstart van het systeem.

[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

Houd het token buiten het unit-bestand. Plaats het in /etc/memmy/memory.env, met root als eigenaar en rechten ingesteld op 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 in de statusuitvoer betekent dat systemd ExecStart in het geheel niet kon uitvoeren. Controleer daarom which npm: dit is /usr/bin/npm bij een NodeSource-installatie en bevindt zich in de home-directory van de gebruiker bij nvm, wat systemd niet zal vinden. Een unit die direct na het starten afsluit, is binnen npm mislukt; journalctl -u memmy-memory -n 50 toont de reden hiervoor. De werking is identiek aan elke andere systemd-service op een VPS.

Wat Memmy nog niet doet

• Er is geen Linux-desktopbuild. De packaging-scripts ondersteunen macOS en Windows, waardoor de workbench, de onboarding-wizard en het memory dashboard niet beschikbaar zijn op de server zelf.
• memory:serve:dev voert het TypeScript-entrypoint uit via tsx, een ontwikkelpad. De repository bevat ook memory:serve voor gecompileerde output. Voer npm run uit zonder argumenten om te zien welke scripts uw checkout daadwerkelijk bevat.
• Retrieval bouwt zijn zoekvenster op basis van de laatste 2.000 vectorrijen en past vervolgens Top-K-selectie toe binnen dat venster. In een zeer grote opslag kan een oud geheugen buiten dit bereik vallen.
• Embedding vindt plaats na de capture; bij een fout wordt het proces naar een retry-wachtrij verplaatst in plaats van de beurt van de agent te blokkeren. Een geheugen dat zojuist is toegevoegd, is mogelijk nog niet vindbaar via vector search.
• Eén SQLite-bestand betekent één node. Er is geen clustering, dus een tweede server is een tweede, afzonderlijk geheugen.

Versie 1.0.4 en ongeveer 329 sterren per juli 2026 duiden op een jong project. Flags, paden en scriptnamen wijzigen tussen releases. Lees het veld bin en de output van npm run in uw eigen checkout in plaats van te vertrouwen op een commando dat elders is gekopieerd, inclusief hier.

FAQ

Waarom geeft de health check 'connection refused' terug?

Er luistert niets op poort 18960. Een curl exitcode 7 met Failed to connect to 127.0.0.1 port 18960 betekent dat de memory service niet draait of is gecrasht tijdens het opstarten; raadpleeg de terminal of de journal waar deze is gestart. De twee gebruikelijke oorzaken zijn een better-sqlite3 native module die niet overeenkomt met uw Node-versie, wat u oplost met npm rebuild better-sqlite3, en een Node-versie lager dan 22. Controleer de socket met ss -lntp | grep 18960 zodra de service actief is.

Waar komt het memmy-memory commando vandaan na het bouwen vanuit de broncode?

Dit komt uit het bin veld van het @memmy/memory workspace-pakket, niet uit de naam van de repository. Voer node -p "JSON.stringify(require('./Memory/package.json').bin)" uit in de checkout en het print {"memmy-memory":"./dist/src/cli/index.js"}. Dat bestand bestaat pas na npm run memory:build, omdat het buildproces dist aanmaakt en het bestand uitvoerbaar maakt. Voer het uit als node Memory/dist/src/cli/index.js health, of maak een symlink naar /usr/local/bin voor de korte naam.

Kan ik Memmy toevoegen aan Claude Code met claude mcp add?

Nee. Memmy is een MCP-client, geen MCP-server. Het maakt verbinding met servers die onder tools.mcpServers in ~/.memmy/config.yaml staan vermeld en biedt hun tools aan aan zijn eigen runtime. Claude Code bereikt Memmy via de omgekeerde weg, door de memmy-memory CLI uit te voeren als shell-commando, aangestuurd door een instructiebestand dat memmy-memory init --agent naar de rules-directory van de agent schrijft.

Verstuurt het draaien van Memmy mijn herinneringen naar een cloudservice?

Scannen en ingestie gebeuren lokaal en herinneringen worden naar ~/.memmy/memory-service/memory.sqlite op uw eigen schijf geschreven. MEMMY_CLOUD_SERVICE wijst naar https://memmy-api.memtensor.cn voor de accountmodus en proeftokens, en het programma voor geheugenverbetering blijft uitgeschakeld totdat u het activeert. Het punt om in de gaten te houden is de embedding-provider: een gehost embedding-model ontvangt de tekst van elke herinnering die het omzet in een vector; gebruik dus een endpoint dat u zelf beheert als dat van belang is.