memory-mcp

Persistenter, durchsuchbarer, versionierter Speicher für KI-Agenten — basierend auf Valkey (Redis-kompatibel), bereitgestellt als MCP-Server über HTTP.

Funktioniert mit jedem MCP-kompatiblen Agenten: Claude Code, Cursor, VS Code und anderen.

Funktionsweise

• Speichert benannte Speichereinträge mit Tags, Typen und Projektbereichen

• Suche nach Tag-Schnittmengen, Filterung nach Typ/Projekt und Teilstring-Suche

• Treffer-Tracking (häufig abgerufene Einträge werden bevorzugt)

• Vollständige Versionshistorie mit Rollback-Funktion

• Prometheus-Metriken-Endpunkt

• Optionale Bearer-Token-Authentifizierung

Schnellstart

cp .env.example .env
# Optional: set MEMORY_MCP_AUTH_TOKEN in .env (see Auth section)
docker compose up -d

Dies lädt das vorgefertigte Image von GHCR. Der MCP-Server ist nun unter http://127.0.0.1:3106/mcp verfügbar.

Um stattdessen lokal zu bauen:

docker compose build
docker compose up -d

Verwendung eines bestehenden Redis oder Valkey

Standardmäßig startet docker compose up -d einen gebündelten Valkey-Container. Um stattdessen eine Verbindung zu einer bestehenden Redis- oder Valkey-Instanz herzustellen, setzen Sie VALKEY_URL und starten Sie nur den memory-mcp-Dienst:

# .env
VALKEY_URL=redis://your-host:6379

docker compose up -d memory-mcp

Jeder Redis-kompatible Server (Redis 6+, Valkey, KeyDB, Upstash via rediss:// usw.) funktioniert. Der Server verwendet nur grundlegende Datenstrukturen: Hashes, Listen und Sets.

Agenten-Einrichtung

Kopieren Sie AGENTS.md aus diesem Repository in Ihr Projekt-Stammverzeichnis. Es weist Ihren Agenten an, wie die Speicher-Tools zu verwenden sind, was gespeichert werden soll und wann.

Registrieren Sie dann den MCP-Server bei Ihrem Agenten-Client:

Claude Code

# Without auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp

# With auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp \
  --header "Authorization: Bearer your-token"

Oder fügen Sie es manuell zu ~/.claude.json hinzu:

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Cursor

Fügen Sie es zu ~/.cursor/mcp.json (global) oder .cursor/mcp.json (Projekt) hinzu:

{
  "mcpServers": {
    "memory": {
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

VS Code (GitHub Copilot, MCP-Erweiterung)

Fügen Sie es zu .vscode/mcp.json in Ihrem Projekt hinzu:

{
  "servers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Lassen Sie die Zeile headers / Authorization in der Konfiguration weg, wenn Sie keine Authentifizierung verwenden.

Konfiguration

Kopieren Sie .env.example nach .env und bearbeiten Sie diese nach Bedarf.

Authentifizierung

Standardmäßig läuft der Server ohne Authentifizierung. Dies ist sicher, wenn er an den Loopback (127.0.0.1) gebunden ist und nur vom lokalen Rechner aus zugegriffen wird.

Um die Authentifizierung zu aktivieren:

# Generate a token
openssl rand -hex 32

# Add to .env
MEMORY_MCP_AUTH_TOKEN=your-generated-token

docker compose up -d

Alle Anfragen an POST /mcp müssen dann Folgendes enthalten:

Authorization: Bearer <token>

GET /health und GET /metrics sind immer ohne Authentifizierung zugänglich.

Verfügbare Tools

Speichertypen

pattern, decision, reference, feedback, incident, project, entity, state

Endpunkte

Datenmodell

Jeder Eintrag wird als Redis-Hash unter mem:<id> gespeichert:

Die Versionshistorie wird in einer Redis-Liste unter memver:<id> gespeichert (neueste zuerst, begrenzt auf MAX_VERSIONS_PER_ENTRY).

Tag-, Typ- und Projektindizes sind Redis-Sets (tag:<name>, type:<name>, project:<name>).

Lizenz

MIT