Genesys

Die Intelligenzschicht für KI-Gedächtnis.

Bewertungs-Engine + kausaler Graph + Lebenszyklus-Manager für das Gedächtnis von KI-Agenten. Spricht nativ MCP.

Was ist das

Genesys ist eine Bewertungs-Engine, ein kausaler Graph und ein Lebenszyklus-Manager für KI-Gedächtnis. Erinnerungen werden durch eine multiplikative Formel (Relevanz × Konnektivität × Reaktivierung) bewertet, in einem kausalen Graphen verbunden und aktiv vergessen, wenn sie irrelevant werden. Es lässt sich an jedes Speicher-Backend anschließen und spricht nativ MCP.

Related MCP server: tentra

Warum

• Flaches Gedächtnis skaliert nicht. Alles in einen Vektorspeicher zu werfen, ermöglicht zwar Abruf, aber ohne Verständnis. Die 500. Erinnerung begräbt die 5, auf die es ankommt.

• Kein Vergessen = keine Intelligenz. Echte Gedächtnissysteme vergessen. Ohne aktives Bereinigen ertrinkt Ihre KI in veraltetem Kontext.

• Kein kausales Denken. Vektorähnlichkeit kann nicht beantworten: „Warum habe ich X gewählt?“ – dafür braucht man einen Graphen.

Ihre KI erinnert sich an alles, versteht aber nichts. Genesys behebt das.

Schnellstart

Die meisten sollten mit Option 1 (In-Memory) beginnen. Wenn Sie eine vollständig lokale Lösung ohne API-Schlüssel wünschen, springen Sie zu Option 3: Obsidian + lokal.

Option 1: In-Memory (null Abhängigkeiten)

Der schnellste Weg, Genesys auszuprobieren. Es ist keine Datenbank erforderlich – der Status wird im Arbeitsspeicher gehalten und optional in einer JSON-Datei gespeichert.

pip install genesys-memory
cp .env.example .env
# Set OPENAI_API_KEY in .env

uvicorn genesys.api:app --port 8000

Um den Status über Neustarts hinweg zu speichern, setzen Sie GENESYS_PERSIST_PATH in .env:

GENESYS_PERSIST_PATH=.genesys_state.json

Geben Sie dies an Claude weiter, damit es die Einrichtung für Sie übernimmt: "Installiere genesys-memory, erstelle eine .env mit meinem OpenAI-Schlüssel, starte den Server auf Port 8000 mit dem In-Memory-Backend und verbinde ihn als MCP-Server."

Option 2: Postgres + pgvector (Produktion)

Persistenter, skalierbarer Speicher mit Vektorsuche via pgvector.

pip install 'genesys-memory[postgres]'
cp .env.example .env

Bearbeiten Sie .env:

OPENAI_API_KEY=sk-...
GENESYS_BACKEND=postgres
DATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys

Starten Sie Postgres und führen Sie Migrationen aus:

docker compose up -d postgres
alembic upgrade head
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000

Geben Sie dies an Claude weiter, damit es die Einrichtung für Sie übernimmt: "Installiere genesys-memory[postgres], starte einen Postgres-Container mit pgvector mittels docker compose, führe alembic-Migrationen aus, erstelle eine .env mit meinem OpenAI-Schlüssel und DATABASE_URL, starte den Server mit GENESYS_BACKEND=postgres und verbinde ihn als MCP-Server."

Option 3: Obsidian Vault (Local-First)

Verwandelt Ihren Obsidian-Vault in einen Genesys-Speicher. Markdown-Dateien werden zu Gedächtnisknoten, [[wikilinks]] werden zu kausalen Kanten. Ein SQLite-Sidecar (.genesys/index.db) übernimmt die Indizierung.

pip install 'genesys-memory[obsidian]'
cp .env.example .env

Bearbeiten Sie .env:

OPENAI_API_KEY=sk-...
GENESYS_BACKEND=obsidian
OBSIDIAN_VAULT_PATH=/path/to/your/vault

Starten Sie den Server:

uvicorn genesys.api:app --port 8000

Beim ersten Start indiziert Genesys alle .md-Dateien im Vault und generiert Embeddings. Ein Datei-Watcher indiziert bei Änderungen an Notizen inkrementell neu.

Wenn OBSIDIAN_VAULT_PATH nicht gesetzt ist, erkennt Genesys den Pfad automatisch durch die Suche nach .obsidian/ in ~/Documents/personal, ~/Documents/Obsidian und ~/obsidian.

Vollständig lokal (keine API-Schlüssel)

Verwenden Sie den lokalen Embedding-Provider, um den Obsidian-Modus ohne externe Abhängigkeiten auszuführen:

pip install 'genesys-memory[obsidian,local]'

GENESYS_BACKEND=obsidian
GENESYS_EMBEDDER=local
OBSIDIAN_VAULT_PATH=/path/to/your/vault
# No OPENAI_API_KEY needed

uvicorn genesys.api:app --port 8000

Dies verwendet all-MiniLM-L6-v2 (384-dim) via sentence-transformers für Embeddings. Das Modell wird bei der ersten Verwendung heruntergeladen (~80 MB).

Verbinden Sie Claude Desktop – fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "genesys": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Oder für Claude Code:

claude mcp add --transport http genesys http://localhost:8000/mcp

Geben Sie dies an Claude weiter, damit es die Einrichtung für Sie übernimmt: "Installiere genesys-memory[obsidian,local], erstelle eine .env mit GENESYS_BACKEND=obsidian, GENESYS_EMBEDDER=local und OBSIDIAN_VAULT_PATH zu meinem Vault unter [YOUR_VAULT_PATH], starte den Server auf Port 8000 und verbinde ihn als MCP-Server. Keine API-Schlüssel erforderlich."

Option 4: FalkorDB (Graph-nativ)

Verwendet FalkorDB (Redis-basierte Graph-Datenbank) für natives Graph-Traversal.

pip install 'genesys-memory[falkordb]'
cp .env.example .env

Bearbeiten Sie .env:

OPENAI_API_KEY=sk-...
GENESYS_BACKEND=falkordb
FALKORDB_HOST=localhost

Starten Sie FalkorDB und den Server:

docker compose up -d falkordb
uvicorn genesys.api:app --port 8000

Geben Sie dies an Claude weiter, damit es die Einrichtung für Sie übernimmt: "Installiere genesys-memory[falkordb], starte einen FalkorDB-Container mittels docker compose, erstelle eine .env mit meinem OpenAI-Schlüssel und GENESYS_BACKEND=falkordb, starte den Server auf Port 8000 und verbinde ihn als MCP-Server."

Aus dem Quellcode

git clone https://github.com/rishimeka/genesys.git
cd genesys
pip install -e '.[dev]'

Seed-Skripte

Zwei Hilfsskripte befüllen eine laufende Genesys-Instanz über die REST-API mit Demodaten. Sie erfordern einen laufenden Server mit konfigurierter Clerk-Authentifizierung.

cp .env.example .env
# Set CLERK_SECRET_KEY and CLERK_USER_ID in .env

python seed_demo.py      # Creates 25 memories with causal edges and runs recall queries
python seed_recalls.py   # Runs 5 rounds of recall queries to build reactivation history

Beide Skripte lesen Anmeldedaten aus Umgebungsvariablen (via .env). Siehe .env.example für alle erforderlichen Variablen.

Mit Ihrer KI verbinden

Claude Code

claude mcp add --transport http genesys http://localhost:8000/mcp

Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "genesys": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Beliebiger MCP-Client

Verweisen Sie Ihren Client auf den MCP-Endpunkt:

http://localhost:8000/mcp

MCP-Tools

Funktionsweise

Jede Erinnerung wird durch drei miteinander multiplizierte Kräfte bewertet:

decay_score = relevance × connectivity × reactivation

• Relevanz nimmt mit der Zeit ab. Alte Erinnerungen verblassen, sofern sie nicht verstärkt werden.

• Konnektivität belohnt Erinnerungen mit vielen kausalen Verknüpfungen. Hub-Erinnerungen überleben.

• Reaktivierung stärkt Erinnerungen, die immer wieder abgerufen werden. Häufigkeit zählt.

Da die Formel multiplikativ ist, muss eine Erinnerung auf allen drei Achsen punkten, um zu überleben. Eine hochgradig vernetzte, aber nie abgerufene Erinnerung verblasst dennoch. Eine häufig abgerufene, aber kausal isolierte Erinnerung verblasst ebenfalls.

STORE → ACTIVE → DORMANT → FADING → PRUNED
           ↑                    │
           └── reactivation ────┘
                                  (only if score=0, orphan, not pinned)

Erinnerungen können auch in den Kern-Status befördert werden – strukturell wichtige Erinnerungen, die automatisch gepinnt und nie bereinigt werden.

Benchmark-Ergebnisse

Getestet am LoCoMo Long-Conversation-Memory-Benchmark (1.540 Fragen über 10 Konversationen, Kategorie 5 ausgeschlossen – kontradiktorische Fragen, bei denen die Ground Truth faktische Fehler enthält, z. B. falsche Daten und Ereigniszuordnungen):

Antwortmodell: gpt-4o-mini | Bewertungsmodell: gpt-4o-mini | Abruf k=20

Zum Vergleich: Mem0 erzielte 67,1% und Zep 75,1% im selben Benchmark. Vollständige Reproduktionsskripte befinden sich in benchmarks/.

Speicher-Backends

Konfiguration

Kopieren Sie .env.example nach .env und setzen Sie:

Siehe .env.example für alle Optionen.

Erstellt von

Genesys wurde von Rishi Meka bei Astrix Labs entwickelt. Es entstand aus der Frustration darüber, Claude in jeder Sitzung den Projektkontext neu erklären zu müssen. Das Ziel ist die Intelligenzschicht zwischen Ihrem LLM und Ihrem Gedächtnis – vollständig Open Source.

Mitwirken

Siehe CONTRIBUTING.md.

Lizenz

AGPL-3.0-or-later

Hinweis: Genesys-Releases vor v0.3.6 wurden fälschlicherweise als Apache 2.0 dokumentiert. Die LICENSE-Datei enthielt schon immer den AGPLv3-Text. Ab v0.3.6 verweist die gesamte Dokumentation korrekt auf AGPL-3.0-or-later mit einer Contributor License Agreement.