Memmy installeren: lokaal gedeeld geheugen voor AI-agents

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 gebruikt één SQLite-database voor wat uw agents hebben geleerd. Elke agent op de server leest uit en schrijft naar dezelfde opslag. Het project is memmy-agent van MemTensor, valt onder de MIT-licentie en heeft versie 1.0.4 sinds juli 2026.

Op een server is slechts een deel ervan relevant. Memmy levert een geheugendienst die op http://127.0.0.1:18960 luistert, een memmy-memory-opdrachtregelinterface (CLI) die met die dienst communiceert, en een desktopwerkbank. De werkbank is alleen beschikbaar voor macOS en Windows. Op een Linux-VPS voert u daarom de dienst en de CLI uit. Dat is voldoende om Claude Code, Codex en Cursor één gedeeld geheugen te geven.

Memmy deelt de opgeslagen gegevens in vier lagen in. L1 Trace is de onbewerkte beurt: het verzoek, het antwoord en de toolaanroepen. L2 Policy is een procedure die uit traces is afgeleid en nuttig is gebleken. L3 World Model is stabiele kennis over een project of omgeving. Skill is een aanroepbare procedure die uit een policy is geconsolideerd. De dienst wijst een laag toe wanneer deze een beurt opneemt. U maakt de lagen dus niet handmatig aan.

Wat een gedeelde geheugencentrale verandert ten opzichte van geheugen per tool

Elke agent brengt tegenwoordig een eigen geheugen uit. Claude Code bewaart instructiebestanden in de repository. Cursor bewaart regels in de werkruimtedatabase. Codex bewaart sessielogboeken onder ~/.codex. Elke opslaglocatie hoort bij één tool. Daardoor is een feit dat u op maandag in de ene tool hebt aangeleerd, op dinsdag onbekend in een andere tool. Dat kost u twee keer: eerst in tokens die u uitgeeft om hetzelfde project opnieuw uit te leggen, en daarna door onjuist werk wanneer een agent handelt op basis van een aanname die u elders al hebt gecorrigeerd.

Een centrale geheugencentrale haalt de opslag uit de tool. Memmy leest ook de bestaande opslaglocaties, zodat u niet met een lege database begint. De scanner kent 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 komen niet overeen. Dat is verwacht. De scanner groepeert berichten per bron en gesprek en schrijft vervolgens één L1-geheugen per volledige beurt. Een beurt geldt als volledig wanneer deze niet-lege gebruikersinhoud bevat en eindigt met een niet-leeg assistentbericht. Een onderbroken sessie draagt daarom niets bij. Berichten worden ontdubbeld met controlepunten voor gesprekken en stabiele beurt-ID's. Het aantal gescande berichten, het aantal geïmporteerde berichten en het aantal nieuwe geheugens verschillen dus allemaal tijdens dezelfde uitvoering.

Dit is het onderdeel dat hoort bij hoe Claude Code de context binnen één sessie beheert. Contextbeheer bepaalt wat in één venster past. Een geheugencentrale bepaalt wat behouden blijft nadat dat venster wordt gesloten.

Wat u nodig hebt op de VPS

• Node.js 22 of nieuwer. De Memmy-documentatie vereist dit, en Ubuntu 24.04 levert Node 18.
• git en een buildtoolchain, omdat better-sqlite3 een native module is die tijdens de installatie kan worden gecompileerd.
• Ongeveer 2 GB RAM. De installatie als root haalt een grote workspace en een frontend-buildtoolchain op.
• Enkele GB 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 moet v22 of hoger weergeven. v18 betekent hier dat de NodeSource-stap niet is uitgevoerd. De installatie mislukt later bij de enginecontrole van het project.

Memmy installeren vanuit de 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-werkruimte naar Memory/dist. Voor een headless server hoeft niets anders in de structuur te worden gebouwd. Controleer of de native module is geladen:

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

Als die regel een fout genereert in plaats van uitvoer te tonen, komt de native module niet overeen met uw Node-versie. Voer npm rebuild better-sqlite3 uit. Dit is precies wat het eigen startscripts van het project doet voordat het iets start.

In de README staat bash scripts/dev-start.sh beschreven als een startopdracht met één commando. Voer deze opdracht niet uit op een headless VPS. De opdracht start de Electron-desktopshell en een Vite-devserver op poort 19000 naast de memory service. Electron heeft een display nodig. Op een server zonder grafische sessie blijft het script daarom hangen of wordt het beëindigd.

De geheugendienst starten en controleren of deze antwoord geeft

npm run memory:serve:dev

Dit is de gedocumenteerde manier om de geheugendienst vanuit de broncode uit te voeren. De dienst luistert op 127.0.0.1:18960, houdt de database bij op ~/.memmy/memory-service/memory.sqlite en leest de configuratie uit ~/.memmy/config.yaml. In het README-bestand staan dezelfde waarden expliciet vermeld:

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

Vraag de dienst vanuit een tweede shell of deze actief is:

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

Health is het enige endpoint waarvoor nooit een token nodig is. Daarom is dit de juiste controle. Als curl wordt afgesloten met code 7 en een bericht met Failed to connect to 127.0.0.1 port 18960, luistert er niets. Lees de terminal waarin de dienst wordt uitgevoerd, omdat een crash bij het opstarten daar wordt weergegeven. De gebruikelijke oorzaak is dat de native SQLite-module niet kan worden geladen. ss -lntp | grep 18960 bevestigt de socket zodra de dienst actief is.

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

• POST /api/v1/memory/add schrijft een geheugenitem en POST /api/v1/memory/search voert query's 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 markeren het begin en einde van een agentsessie.
• POST /api/v1/turns/start en POST /api/v1/turns/:turnId/complete registreren één beurt.
• GET /api/v1/panel/overview, /api/v1/panel/analysis en /api/v1/panel/items leveren gegevens aan het dashboard.

Memmy reserveert een reeks poorten. In headless-modus gebruikt u alleen de eerste poort: 18960 voor geheugen, 18970 voor de gatewaystatus, 18980 voor de webinterface en de beheer-HTTP-interface, 18990 voor de OpenAI-compatibele API die memmy serve start, en vervolgens 19000 en 19010 voor de ontwikkelserver van de desktopfrontend. Als een ander proces op uw systeem al een van deze poorten gebruikt, kunt u dit in die lijst controleren.

Waar de opdracht memmy-memory daadwerkelijk vandaan komt

Hier gaat een eerste installatie meestal mis. Lees dit daarom uit het pakket in plaats van te raden. De opdrachtnaam heeft niets te maken met de naam van de repository. De naam komt uit het veld bin van de workspace waarin de opdracht is gedefinieerd:

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

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

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

Als u de korte naam in uw PATH wilt gebruiken, maakt u een koppeling naar hetzelfde 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 subopdrachten zijn init, health, search, add, get en delete. Daarnaast zijn er session- en turn-aanroepen die agents gebruiken in plaats van gebruikers. memmy-memory search "deploy steps" en memmy-memory add "staging migrates on deploy" zijn de twee opdrachten die een agent het vaakst uitvoert.

Hoe verbindt u Claude Code met Memmy?

Claude Code heeft geen interface voor geheugenplugins, dus Memmy haakt er niet rechtstreeks op in. De integratie is eenvoudiger. Claude Code voert memmy-memory uit als een gewone shellopdracht. Een instructiebestand bepaalt wanneer dit gebeurt. Het gedocumenteerde installatieprogramma van Memmy maakt dat bestand voor u aan: memmy-memory init --agent plaatst een instructiebestand voor geheugen in de regelsdirectory van de doelagent.

Schrijf de instructie eenmalig handmatig. Zo weet u precies welke instructie de agent krijgt. Claude Code leest CLAUDE.md vanuit de projectroot aan het begin van elke sessie. Een sectie zoals deze vormt daarom 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 oplevert. Het gaat om integratie op instructieniveau. De integratie werkt dus alleen wanneer het model besluit de opdracht uit te voeren. Niets dwingt die aanroep af. Als een sessie eindigt zonder add, is er niets opgeslagen. De enige aanwijzing is dan een leeg resultaat bij de volgende zoekopdracht. Dat is dezelfde afweging als bij de eigen geheugenbestanden van Claude Code, met één verschil: de opslag wordt gedeeld. De notitie is daardoor ook beschikbaar in Codex en Cursor op dezelfde computer.

Voor de omgekeerde richting is geen configuratie nodig. De scanner van Memmy leest ~/.claude/projects/**/*.jsonl al. Claude Code schrijft daar zijn sessietranscripten. Voer Memmy uit op dezelfde server waarop u Claude Code in een tmux-sessie uitvoert. Het werk van gisteren wordt dan geheugen zonder dat u iets hoeft te configureren.

Werkt Memmy als MCP-server voor Claude Code?

Nee. Als u de richting kent, bespaart u een middag. MCP (model context protocol) heeft clients en servers. Memmy is een client. Memmy maakt verbinding met MCP-servers en biedt hun tools aan de eigen agentruntime. Memmy publiceert geen MCP-endpoint waar claude mcp add verbinding mee kan maken. De enige MCP-bridge in de repository hoort bij de Composio-integratie binnen de lokale desktop-API. Die API luistert op een willekeurige poort op 127.0.0.1, achter de eigen x-memmy-mcp-token-header.

De clientzijde wordt geconfigureerd in ~/.memmy/config.yaml, het bestand waarnaar MEMMY_CONFIG 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 child process van Memmy. Daarom moet de opdracht op dezelfde machine bestaan en als dezelfde gebruiker worden uitgevoerd. Als u MCP-servers op een VPS uitvoert, zijn dat de servers die u hier moet opgeven.

De geheugenopslag privé houden

Alles wat Memmy beheert, staat onder ~/.memmy: config.yaml, de werkruimte, memory-service/memory.sqlite en runtime-bestanden. Scannen en opnemen gebeuren lokaal. Geheugens worden naar dat lokale SQLite-bestand geschreven. De standaardinstelling is dus daadwerkelijk lokaal.

Twee paden maken wel verbinding met het netwerk. MEMMY_CLOUD_SERVICE verwijst standaard naar https://memmy-api.memtensor.cn en ondersteunt de accountmodus met de bijbehorende proeftokens. De modus met een API-sleutel maakt daarom nooit verbinding met deze service. Het programma voor geheugenverbetering is een afzonderlijke schakeloptie in de privacyinstellingen en staat uit totdat u deze inschakelt.

Een derde pad is minder zichtbaar. Als u een gehoste embeddingprovider configureert, wordt de tekst van elk geheugen naar die provider verzonden, zodat deze de tekst in een vector kan omzetten. Lokale opslag voorkomt dat niet. Alleen een embeddingendpoint dat u zelf host, kan dit voorkomen.

Houd poort 18960 op het loopbackadres. Hiervoor is geen firewallregel nodig, omdat een service die aan 127.0.0.1 is gebonden helemaal niet vanaf buiten de host bereikbaar is. Gebruik SSH om er vanaf uw laptop verbinding mee te maken:

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

Als u de service ooit aan een breder adres bindt, stelt u eerst een token in. Als u storage.token in de configuratie instelt, of de omgevingsvariabele MEMMY_MEMORY_TOKEN of MEMORY_SERVICE_TOKEN gebruikt, vereist elk endpoint behalve health een bearer-token. Configuratiewaarden ondersteunen verwijzingen naar ${ENV_NAME}. Daardoor blijven het token en uw model-API-sleutels buiten het bestand zelf. Dit is dezelfde werkwijze als geheimen buiten AI-agents houden en een standaard-denybeleid voor ufw biedt een extra beveiligingslaag als een toekomstige versie het standaard-bindadres wijzigt.

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

memory.sqlite is de volledige opslag. De vectoren staan via de extensie sqlite-vec in hetzelfde bestand. Eén bestand is dus de back-up. Als u dit bestand met cp kopieert terwijl de service ernaar schrijft, kan de database beschadigd raken. Gebruik de eigen back-upopdracht van SQLite:

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

Hiermee maakt u een consistente kopie terwijl de service actief blijft. Zet deze volgens een schema op een andere machine. Daarvoor gebruikt u restic naar externe opslag. Als u config.yaml verliest, gaan de providerinstellingen verloren. Die kunt u opnieuw invoeren. Als u memory.sqlite verliest, gaan al uw herinneringen verloren. Geen ander bestand op de machine bevat een tweede kopie.

De geheugendienst uitvoeren onder systemd

npm run memory:serve:dev in een shell stopt zodra de shell stopt. Een unitbestand houdt de service ook na het opnieuw opstarten actief.

[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 de unit. Plaats het in /etc/memmy/memory.env, maak root eigenaar en stel modus 600 in:

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 helemaal niet kon uitvoeren. Controleer daarom which npm: dit is /usr/bin/npm bij een NodeSource-installatie en iets onder de thuismap van de gebruiker bij nvm. systemd kan dat niet vinden. Een unit die direct start en weer stopt, is binnen npm mislukt. journalctl -u memmy-memory -n 50 toont de reden. De werkwijze is hetzelfde als bij elke andere systemd-service op een VPS.

Wat Memmy nog niet doet

• Er is geen Linux-desktopbuild. De packaging-scripts ondersteunen macOS en Windows. Daardoor zijn de workbench, de onboardingwizard en het geheugendashboard niet beschikbaar op de server zelf.
• memory:serve:dev voert het TypeScript-entrypoint uit via tsx, een ontwikkelpad. De repository bevat ook memory:serve voor gecompileerde uitvoer. Voer npm run zonder argumenten uit om te zien welke scripts uw checkout daadwerkelijk bevat.
• Retrieval bouwt het zoekvenster op basis van de nieuwste 2,000 vectorrijen en past vervolgens Top-K-selectie binnen dat venster toe. In een zeer grote datastore kan een oude herinnering buiten dit venster vallen.
• Embedding vindt plaats na het vastleggen. Bij een fout wordt de verwerking naar een retry-queue gestuurd, zodat de beurt van de agent niet wordt geblokkeerd. Een herinnering die zojuist is toegevoegd, is mogelijk nog niet beschikbaar voor vectorzoekopdrachten.
• Eén SQLite-bestand betekent één node. Er is geen clustering. Een tweede server heeft dus een afzonderlijk geheugen.

Versie 1.0.4 en ongeveer 329 stars in juli 2026 wijzen op een jong project. Flags, paden en scriptnamen veranderen tussen releases. Controleer het veld bin en de uitvoer van npm run in uw eigen checkout. Vertrouw niet op een opdracht die u ergens hebt gekopieerd, ook niet hier.

FAQ

Waarom geeft de healthcheck 'connection refused'?

Er luistert niets op poort 18960. Een curl-exitcode 7 met Failed to connect to 127.0.0.1 port 18960 betekent dat de memoryservice niet actief is of tijdens het starten is gestopt. Lees daarom de terminaluitvoer of het journal op de plaats waar de service is gestart. De twee gebruikelijke oorzaken zijn een better-sqlite3 native module die niet overeenkomt met uw Node-versie, opgelost 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 de opdracht memmy-memory vandaan nadat de broncode is gebouwd?

Uit het veld bin van het @memmy/memory-workspacepakket, niet uit de naam van de repository. Voer node -p "JSON.stringify(require('./Memory/package.json').bin)" uit in de checkout. De opdracht toont dan {"memmy-memory":"./dist/src/cli/index.js"}. Dat bestand bestaat pas na npm run memory:build, omdat de build dist aanmaakt en het bestand uitvoerbaar maakt. Voer het uit als node Memory/dist/src/cli/index.js health, of maak er een symbolische koppeling naar in /usr/local/bin voor de korte naam.

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

Nee. Memmy is een MCP-client, geen MCP-server. De client maakt verbinding met servers die onder tools.mcpServers in ~/.memmy/config.yaml staan en biedt hun tools aan zijn eigen runtime aan. Claude Code bereikt Memmy op de andere manier: door de memmy-memory CLI als shellopdracht uit te voeren. Hierbij gebruikt Claude Code een instructiebestand dat memmy-memory init --agent naar de rules-directory van de agent schrijft.

Stuurt het uitvoeren van Memmy mijn memories naar een clouddienst?

Scannen en opnemen worden lokaal uitgevoerd. Memories worden opgeslagen in ~/.memmy/memory-service/memory.sqlite op uw eigen schijf. MEMMY_CLOUD_SERVICE verwijst voor de accountmodus en proef tokens naar https://memmy-api.memtensor.cn. Het programma voor memoryverbetering blijft uitgeschakeld totdat u het inschakelt. Let vooral op de embeddingprovider: een gehost embeddingmodel ontvangt de tekst van elke memory die het omzet in een vector. Gebruik daarom een endpoint dat u zelf beheert als dit van belang is.