Memmy: Gemeinsamer Speicher für KI-Agenten auf dem VPS

Was Memmy ist und welche Daten es speichert

Memmy ist ein lokaler Memory-Hub für KI-Agenten, der auf Ihrem eigenen VPS (virtual private server) läuft. Er verwaltet eine SQLite-Datenbank mit dem Wissen Ihrer Agenten. Jeder Agent auf dem Server liest aus diesem gemeinsamen Speicher und schreibt in ihn. Das Projekt wird memmy-agent von MemTensor veröffentlicht, steht unter der MIT-Lizenz und hat im Juli 2026 die Version 1.0.4.

Für einen Server ist nur ein Teil davon relevant. Memmy stellt einen Memory-Dienst bereit, der auf http://127.0.0.1:18960 lauscht, eine memmy-memory-Befehlszeilenschnittstelle (CLI), die mit diesem Dienst kommuniziert, und eine Desktop-Arbeitsumgebung. Die Arbeitsumgebung ist nur für macOS und Windows verfügbar. Auf einem Linux-VPS führen Sie daher den Dienst und die CLI aus. Damit können Claude Code, Codex und Cursor einen gemeinsamen Speicher verwenden.

Memmy ordnet seine gespeicherten Inhalte vier Ebenen zu. L1 Trace ist der rohe Ablauf: die Anfrage, die Antwort und die Tool-Aufrufe. L2 Policy ist ein aus Traces abgeleitetes Verfahren, das sich als nützlich erwiesen hat. L3 World Model ist dauerhaftes Wissen über ein Projekt oder eine Umgebung. Skill ist ein aufrufbares Verfahren, das aus einer Policy herausgebildet wurde. Der Dienst weist beim Einlesen eines Turns eine Ebene zu. Sie erstellen diese Ebenen daher nicht manuell. Falls Ihnen diese Unterscheidungen abstrakt erscheinen: Memory ist eine der späteren Stufen in einem stufenweisen Lernpfad zum Erstellen von Agents. Die Ebenen werden verständlicher, sobald Sie selbst eine einfache Agent-Schleife geschrieben und beobachtet haben, dass sie zwischen zwei Ausführungen alles vergisst.

Was ein zentraler Memory-Hub gegenüber dem Speicher einzelner Tools ändert

Jeder Agent bringt heute seinen eigenen Speicher mit. Claude Code legt Anweisungsdateien im Repository ab. Cursor speichert Regeln in seiner Workspace-Datenbank. Codex legt Sitzungsprotokolle unter ~/.codex ab. Jeder Speicher gehört zu genau einem Tool. Eine Information, die Sie einem Tool am Montag beigebracht haben, ist dem anderen Tool am Dienstag unbekannt. Das verursacht doppelte Kosten: einmal durch die Tokens, die Sie für die erneute Erklärung desselben Projekts aufwenden, und einmal durch fehlerhafte Arbeit, wenn ein Agent auf einer Annahme basiert, die Sie an anderer Stelle bereits korrigiert haben.

Ein Hub verlagert den Speicher aus dem Tool heraus. Memmy liest außerdem die vorhandenen Speicher ein. Sie beginnen daher nicht mit einer leeren Datenbank. Der Scanner kennt sechs Quellen: Claude Code unter ~/.claude/projects/**/*.jsonl, Codex unter ~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl, OpenCode unter ~/.local/share/opencode/opencode.db, die state.vscdb-Dateien von Cursor, die SQLite-Datenbanken von OpenClaw unter ~/.openclaw und Hermes unter ~/.hermes. Sie können manuell eine Quelle mit einem Namen und einem lokalen Pfad hinzufügen.

Die Importzähler werden nicht übereinstimmen. Das ist erwartetes Verhalten. Der Scanner gruppiert Nachrichten nach Quelle und Konversation und schreibt anschließend pro vollständigem Turn eine L1-Memory. Ein Turn gilt als vollständig, wenn er nichtleeren Benutzerinhalt enthält und mit einer nichtleeren Assistentennachricht endet. Eine unterbrochene Sitzung trägt daher nichts bei. Nachrichten werden anhand von Konversationsprüfpunkten und stabilen Turn-IDs dedupliziert. Die Anzahl der gescannten Nachrichten, die Anzahl der importierten Nachrichten und die Anzahl der neuen Memories unterscheiden sich bei demselben Lauf.

Dieser Abschnitt ergänzt wie Claude Code den Kontext innerhalb einer Sitzung verwaltet. Die Kontextverwaltung entscheidet, was in ein einzelnes Kontextfenster passt. Ein Memory-Hub entscheidet, was nach dem Schließen dieses Fensters erhalten bleibt.

Was Sie auf dem VPS benötigen

• Node.js 22 oder neuer. Die Memmy-Dokumentation setzt diese Version voraus, und Ubuntu 24.04 liefert Node 18 aus.
• git und eine Build-Toolchain, weil better-sqlite3 ein natives Modul ist, das während der Installation kompiliert werden kann.
• Etwa 2 GB RAM. Die Installation als root lädt einen großen Workspace und eine Toolchain für den Frontend-Build.
• Einige GB freien Speicherplatz für node_modules und die Datenbank.

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 sollte v22 oder höher ausgeben. Ein v18 an dieser Stelle bedeutet, dass der NodeSource-Schritt nicht erfolgreich war. Die Installation schlägt später bei der Engine-Prüfung des Projekts fehl.

Install Memmy aus dem Quellcode unter 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 kompiliert den @memmy/memory-Workspace zu Memory/dist. Für einen Headless-Server muss nichts anderes im Verzeichnisbaum kompiliert werden. Prüfen Sie, ob das native Modul geladen wurde:

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

Wenn diese Zeile statt einer Ausgabe einen Fehler auslöst, ist das native Modul nicht mit Ihrer Node-Version kompatibel. Führen Sie npm rebuild better-sqlite3 aus. Genau das macht auch das Startskript des Projekts, bevor es irgendetwas startet.

Die README beschreibt bash scripts/dev-start.sh als Start mit einem einzigen Befehl. Führen Sie diesen Befehl nicht auf einem Headless-VPS aus. Er startet zusätzlich zum Memory-Service die Electron-Desktop-Shell und einen Vite-Dev-Server auf Port 19000. Electron benötigt eine Anzeige. Auf einem Server ohne grafische Sitzung bleibt das Skript daher hängen oder wird beendet.

Memorieservice starten und seine Antwort prüfen

npm run memory:serve:dev

Dies ist die dokumentierte Methode, um den Memorieservice aus dem Quellcode zu starten. Er bindet an 127.0.0.1:18960, speichert die Datenbank unter ~/.memmy/memory-service/memory.sqlite und liest die Konfiguration aus ~/.memmy/config.yaml. Die README nennt dieselben Werte, wenn Sie sie explizit angeben möchten:

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

Fragen Sie aus einer zweiten Shell ab, ob der Dienst aktiv ist:

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

Der Health-Endpunkt ist der einzige Endpunkt, der niemals ein Token verlangt. Deshalb eignet er sich für die Prüfung. Wenn curl mit dem Code 7 und einer Failed to connect to 127.0.0.1 port 18960-Meldung beendet wird, lauscht kein Prozess. Lesen Sie das Terminal, in dem der Dienst läuft. Ein Absturz beim Start wird dort ausgegeben. Die häufigste Ursache ist, dass das native SQLite-Modul nicht geladen werden kann. ss -lntp | grep 18960 bestätigt den Socket, sobald der Dienst läuft.

Die übrige HTTP-API (Programmierschnittstelle) befindet sich unter /api/v1.

• POST /api/v1/memory/add schreibt eine Memory und POST /api/v1/memory/search fragt Memories ab.
• GET /api/v1/memory/:id und DELETE /api/v1/memory/:id lesen einen Eintrag und entfernen ihn.
• POST /api/v1/sessions/open und POST /api/v1/sessions/:sessionId/close begrenzen eine Agentensitzung.
• POST /api/v1/turns/start und POST /api/v1/turns/:turnId/complete erfassen einen Turn.
• GET /api/v1/panel/overview, /api/v1/panel/analysis und /api/v1/panel/items versorgen das Dashboard.

Memmy reserviert einen Portblock. Im Headless-Betrieb verwenden Sie nur den ersten Port: 18960 für Memories, 18970 für den Gateway-Health-Endpunkt, 18980 für die Weboberfläche und die administrative HTTP-Schnittstelle, 18990 für die mit memmy serve gestartete OpenAI-kompatible API sowie 19000 und 19010 für den Dev-Server des Desktop-Frontends. Wenn auf Ihrem System bereits etwas einen dieser Ports belegt, sollten Sie diese Portliste prüfen.

Woher der Befehl memmy-memory tatsächlich kommt

Hier schlägt eine erste Installation häufig fehl. Lesen Sie deshalb die Information direkt aus dem Paket aus, statt zu raten. Der Befehlsname hat nichts mit dem Namen des Repositorys zu tun. Er stammt aus dem Feld bin des Workspace, in dem der Befehl definiert ist:

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

Dieser Befehl gibt {"memmy-memory":"./dist/src/cli/index.js"} aus. Der erstellte Einstiegspunkt ist also Memory/dist/src/cli/index.js. Er ist erst nach npm run memory:build vorhanden, weil der Build dist erzeugt und die Datei als ausführbar markiert. Führen Sie ihn direkt aus:

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

Wenn Sie den kurzen Namen in Ihrem PATH verwenden möchten, verknüpfen Sie dieselbe Datei:

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

Die CLI verwendet standardmäßig http://127.0.0.1:18960 und akzeptiert --url, --token, --config, --source und --user-id. Ihre Unterbefehle sind init, health, search, add, get und delete. Außerdem gibt es Session- und Turn-Aufrufe, die Agents statt Menschen verwenden. memmy-memory search "deploy steps" und memmy-memory add "staging migrates on deploy" führt ein Agent am häufigsten aus.

Wie verbinden Sie Claude Code mit Memmy?

Claude Code verfügt über keine Plugin-Schnittstelle für den Speicher. Memmy kann sich daher nicht direkt einklinken. Die Integration ist einfacher. Claude Code führt memmy-memory als normalen Shell-Befehl aus. Eine Anweisungsdatei teilt ihm mit, wann dieser Befehl ausgeführt werden soll. Das dokumentierte Installationsprogramm von Memmy erstellt diese Datei für Sie: memmy-memory init --agent legt eine Speicher-Anweisungsdatei im Regelverzeichnis des Ziel-Agenten ab.

Schreiben Sie die Anweisung einmal von Hand. So wissen Sie genau, welche Vorgaben der Agent erhalten hat. Claude Code liest CLAUDE.md zu Beginn jeder Sitzung aus dem Projektstammverzeichnis. Ein Abschnitt wie dieser bildet daher die gesamte Integration:

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

Machen Sie sich klar, welchen Nutzen das bietet. Es handelt sich um eine Integration auf Anweisungsebene. Sie funktioniert daher nur, wenn das Modell den Befehl ausführt. Der Aufruf wird nicht erzwungen. Wenn eine Sitzung ohne add endet, wurde nichts gespeichert. Beim nächsten Suchvorgang ist dann nur ein leeres Ergebnis als Hinweis verfügbar. Das ist derselbe Kompromiss wie bei den eigenen Speicherdateien von Claude Code, mit einem Unterschied: Der Speicher ist gemeinsam nutzbar. Dadurch ist die Notiz auf demselben Rechner auch für Codex und Cursor verfügbar. Ein Harness mit einer echten Plugin-Schnittstelle schließt diese Lücke, statt um die Ausführung zu bitten. Deshalb gehört dauerhafter Speicher neben Budgetbegrenzungen und Berechtigungsregeln zu den empfehlenswerten DeepSeek-Harness-Plugins.

Die umgekehrte Richtung erfordert keine Einrichtung. Der Scanner von Memmy liest bereits ~/.claude/projects/**/*.jsonl. Dort schreibt Claude Code seine Sitzungsprotokolle. Führen Sie Memmy auf demselben Server aus, auf dem Sie Claude Code in einer tmux-Sitzung ausführen. Dann wird die Arbeit des Vortags ohne weitere Konfiguration zu Speicher.

Funktioniert Memmy als MCP-Server für Claude Code?

Nein. Wenn Sie das wissen, sparen Sie sich einen Nachmittag. MCP (model context protocol) unterscheidet zwischen Clients und Servern. Memmy ist ein Client. Memmy stellt Verbindungen zu MCP-Servern her und stellt deren Tools seiner eigenen Agent-Laufzeitumgebung bereit. Memmy veröffentlicht keinen MCP-Endpunkt, auf den claude mcp add verweisen kann. Die einzige MCP-Bridge im Repository gehört zur Composio-Integration innerhalb der lokalen Desktop-API. Diese API bindet einen zufälligen Port auf 127.0.0.1 und ist durch ihren eigenen x-memmy-mcp-token-Header geschützt.

Die Client-Seite wird in ~/.memmy/config.yaml konfiguriert. Die Datei, auf die MEMMY_CONFIG verweist, liegt unter tools.mcpServers:

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

type akzeptiert stdio, sse und streamableHttp. Ein stdio-Server wird als Kindprozess von Memmy ausgeführt. Deshalb muss sein Befehl auf demselben Rechner vorhanden sein und unter demselben Benutzer ausgeführt werden. Wenn Sie MCP-Server auf einem VPS betreiben, sind dies die Server, die Sie hier eintragen sollten.

Den Memory-Speicher privat halten

Alles, was Memmy besitzt, liegt unter ~/.memmy: config.yaml, der Arbeitsbereich, memory-service/memory.sqlite und Laufzeitdateien. Scannen und Einlesen erfolgen lokal. Die Erinnerungen werden in diese lokale SQLite-Datei geschrieben. Damit ist der Standardbetrieb tatsächlich lokal.

Zwei Pfade greifen auf das Netzwerk zu. MEMMY_CLOUD_SERVICE verwendet standardmäßig https://memmy-api.memtensor.cn und aktiviert den Kontomodus mit seinen Testtokens. Im API-Key-Modus wird dieser Dienst daher nie aufgerufen. Das Programm zur Verbesserung der Erinnerungen ist eine separate Option in den Datenschutzeinstellungen. Sie ist deaktiviert, bis Sie sie aktivieren.

Ein dritter Pfad wird leichter übersehen. Wenn Sie einen gehosteten Embedding-Provider konfigurieren, wird der Text jeder Erinnerung an diesen Provider gesendet, damit er in einen Vektor umgewandelt werden kann. Die lokale Speicherung schützt davor nicht. Nur ein selbst gehosteter Embedding-Endpunkt schließt diesen Pfad.

Belassen Sie Port 18960 an der Loopback-Adresse. Dafür ist keine Firewall-Regel erforderlich, weil ein Dienst, der an 127.0.0.1 gebunden ist, vom System aus nicht erreichbar ist. Greifen Sie stattdessen über SSH von Ihrem Laptop darauf zu:

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

Wenn Sie den Dienst jemals an eine weiter gefasste Adresse binden, setzen Sie zuerst ein Token. Wenn Sie storage.token in der Konfiguration oder die Umgebungsvariable MEMMY_MEMORY_TOKEN beziehungsweise MEMORY_SERVICE_TOKEN setzen, erfordern alle Endpunkte außer dem Health-Endpunkt ein Bearer-Token. Konfigurationswerte unterstützen ${ENV_NAME}-Referenzen. Dadurch bleiben das Token und Ihre Model-API-Keys aus der Datei heraus. Das entspricht der Vorgehensweise Secrets aus AI-Agents herauszuhalten und einer standardmäßig ablehnenden ufw-Richtlinie als zusätzlicher Absicherung, falls eine künftige Version ihre Standard-Bind-Adresse ändert.

Sichern Sie ~/.memmy, bevor Sie dem System vertrauen

memory.sqlite ist der gesamte Datenspeicher. Die Vektoren liegen über die Erweiterung sqlite-vec in derselben Datei. Damit besteht das Backup aus einer einzigen Datei. Wenn Sie sie während eines Schreibvorgangs des Dienstes mit cp kopieren, kann eine inkonsistente Datenbankkopie entstehen. Verwenden Sie stattdessen den eigenen Backup-Befehl von SQLite:

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

Damit wird eine konsistente Kopie erstellt, während der Dienst weiterläuft. Übertragen Sie diese regelmäßig auf ein anderes System. Dafür eignet sich restic für die externe Speicherung. Der Verlust von config.yaml betrifft nur die Anbietereinstellungen, die Sie erneut eingeben können. Der Verlust von memory.sqlite betrifft alle gespeicherten Erinnerungen. Auf keinem anderen Pfad des Systems existiert eine zweite Kopie.

Den Memory-Dienst unter systemd ausführen

npm run memory:serve:dev in einer Shell wird mit der Shell beendet. Eine Unit-Datei hält den Dienst über Reboots hinweg aktiv.

[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

Legen Sie das Token nicht in der Unit ab. Speichern Sie es in /etc/memmy/memory.env, im Besitz von root und mit den Rechten 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 der Statusausgabe bedeutet, dass systemd ExecStart überhaupt nicht ausführen konnte. Prüfen Sie daher which npm: Bei einer NodeSource-Installation befindet es sich unter /usr/bin/npm, bei nvm unter einem Pfad im Home-Verzeichnis des Benutzers. Diesen Pfad findet systemd nicht. Eine Unit, die startet und sofort beendet wird, ist dagegen innerhalb von npm fehlgeschlagen. journalctl -u memmy-memory -n 50 gibt den Grund aus. Die Vorgehensweise ist dieselbe wie bei jedem anderen systemd-Dienst auf einem VPS.

Was Memmy noch nicht leistet

• Es gibt keinen Linux-Desktop-Build. Die Packaging-Skripte decken macOS und Windows ab. Daher sind die Workbench, der Onboarding-Assistent und das Memory-Dashboard nicht direkt auf dem Server verfügbar.
• memory:serve:dev führt den TypeScript-Einstiegspunkt über tsx aus, also über einen Entwicklungsweg. Das Repository enthält außerdem memory:serve für kompilierten Output. Führen Sie npm run ohne Argumente aus, um zu sehen, welche Skripte Ihr Checkout tatsächlich enthält.
• Die Abfrage erstellt ihr Suchfenster aus den neuesten 2,000 Vektorzeilen und wendet die Top-K-Auswahl innerhalb dieses Fensters an. In einem sehr großen Speicher kann eine ältere Memory außerhalb dieses Fensters liegen.
• Die Embedding-Erstellung erfolgt nach der Erfassung. Ein Fehler wird daher in eine Retry-Warteschlange eingereiht, anstatt den Agentenlauf zu blockieren. Eine soeben hinzugefügte Memory ist möglicherweise noch nicht über die Vektorsuche auffindbar.
• Eine SQLite-Datei bedeutet einen einzelnen Node. Es gibt kein Clustering. Ein zweiter Server hat daher einen separaten Speicher.

Version 1.0.4 und ungefähr 329 Sterne im Juli 2026 zeigen, dass es sich um ein junges Projekt handelt. Flags, Pfade und Skriptnamen ändern sich zwischen Releases. Lesen Sie das Feld bin und die Ausgabe von npm run in Ihrem eigenen Checkout, anstatt einem von irgendwo kopierten Befehl zu vertrauen, auch wenn er hier steht.

FAQ

Warum gibt der Health Check „connection refused“ zurück?

Auf Port 18960 lauscht kein Prozess. Ein curl-Exit-Code 7 mit Failed to connect to 127.0.0.1 port 18960 bedeutet, dass der Memory-Dienst nicht läuft oder beim Start beendet wurde. Lesen Sie daher die Terminalausgabe oder das Journal, in dem der Dienst gestartet wurde. Die beiden häufigsten Ursachen sind ein better-sqlite3-natives Modul, das nicht zu Ihrer Node-Version passt und mit npm rebuild better-sqlite3 behoben wird, sowie eine Node-Version unter 22. Prüfen Sie den Socket mit ss -lntp | grep 18960, sobald der Dienst läuft.

Woher stammt der Befehl memmy-memory nach dem Build aus dem Quellcode?

Aus dem Feld bin des Workspace-Pakets @memmy/memory, nicht aus dem Namen des Repositorys. Führen Sie node -p "JSON.stringify(require('./Memory/package.json').bin)" im Checkout aus. Der Befehl gibt {"memmy-memory":"./dist/src/cli/index.js"} aus. Diese Datei existiert erst nach npm run memory:build, weil der Build dist erstellt und die Datei als ausführbar markiert. Führen Sie sie mit node Memory/dist/src/cli/index.js health aus, oder erstellen Sie für den kurzen Namen einen symbolischen Link nach /usr/local/bin.

Kann ich Memmy mit claude mcp add zu Claude Code hinzufügen?

Nein. Memmy ist ein MCP-Client, kein MCP-Server. Memmy stellt ausgehende Verbindungen zu den unter tools.mcpServers in ~/.memmy/config.yaml aufgeführten Servern her und stellt deren Tools seiner eigenen Laufzeitumgebung bereit. Claude Code erreicht Memmy auf dem umgekehrten Weg, indem es die memmy-memory-CLI als Shell-Befehl ausführt. Gesteuert wird dies durch eine Anweisungsdatei, die memmy-memory init --agent in das Rules-Verzeichnis des Agents schreibt.

Sendet Memmy meine Memories an einen Cloud-Dienst?

Scanning und Ingestion laufen lokal. Die Memories werden unter ~/.memmy/memory-service/memory.sqlite auf Ihrer eigenen Festplatte gespeichert. MEMMY_CLOUD_SERVICE verweist im Account-Modus und für Testtokens auf https://memmy-api.memtensor.cn. Das Programm zur Verbesserung der Memories bleibt deaktiviert, bis Sie es aktivieren. Relevant ist der Embedding-Provider: Ein gehostetes Embedding-Modell erhält den Text jeder Memory, die es in einen Vektor umwandelt. Wenn das problematisch ist, verwenden Sie einen Endpoint, den Sie selbst betreiben.