Memory Cell¶
Die Memory-Cell-Komponente bietet persistenten Key-Value-Speicher, der über Flow-Ausführungen hinweg erhalten bleibt. Sie unterstützt drei Operationen — Read, Write und Delete — sowie drei Scope-Ebenen, die die Sichtbarkeit gespeicherter Daten steuern.
Modi¶
Der Mode-Tab oben auf der Komponente wählt die Operation:
| Modus | Verhalten | Ausgabe |
|---|---|---|
| Read | Ruft den Wert für einen gegebenen Schlüssel ab. Gibt den Standardwert zurück, wenn der Schlüssel nicht existiert. | Data mit key, value und scope. |
| Write | Speichert einen Wert unter dem gegebenen Schlüssel (Upsert). Akzeptiert beliebige JSON-serialisierbare Inhalte: Strings, Zahlen, Objekte, Arrays. | Data mit key, value und scope. |
| Delete | Entfernt den Eintrag für den gegebenen Schlüssel. | Data mit key, deleted (Boolean) und scope. |
Die sichtbaren Felder der Komponente aktualisieren sich dynamisch je nach gewähltem Modus — zum Beispiel erscheint das Value-Feld nur im Write-Modus und das Default Value-Feld nur im Read-Modus.
Scopes¶
Das Scope-Dropdown bestimmt, wie die gespeicherten Daten partitioniert werden:
| Scope | Schlüssel | Sichtbarkeit | Voraussetzungen |
|---|---|---|---|
| Session | Chat-Session-ID | Isoliert auf die aktuelle Chat-Session. Jede Session hat ihren eigenen Schlüsselraum. | Keine — immer verfügbar. |
| User | User-ID (sub-Claim aus JWT) |
Über alle Sessions desselben Nutzers geteilt. Ein in einer Session geschriebener Wert ist in jeder anderen Session dieses Nutzers lesbar. | Karli-Studio-Session (JWT erforderlich). |
| Agent | Flow-ID | Über alle Sessions und alle Nutzer dieses Flows geteilt. Nützlich für Flow-Level-Konfiguration oder gemeinsame Zähler. | Keine — immer verfügbar. |
User-Scope benötigt Karli Studio
Der User-Scope extrahiert die Nutzeridentität aus dem Session-JWT, das vom Karli-Studio-Proxy eingefügt wird. Ist kein JWT verfügbar (z. B. bei eigenständigem Agentlab-Betrieb), führt die Auswahl des User-Scopes zu einem Fehler.
Felder¶
| Feld | Modi | Beschreibung |
|---|---|---|
| Key | Alle | Der Schlüssel zum Lesen, Schreiben oder Löschen. Unterstützt Tool-Modus — ein vorgelagertes LLM kann diesen dynamisch liefern. |
| Value | Write | Der zu speichernde Wert. Ist die Eingabe gültiges JSON, wird sie vor dem Speichern geparst, sodass strukturierte Daten (Objekte, Arrays) sauber erhalten bleiben. Einfache Strings, die kein gültiges JSON sind, werden unverändert gespeichert. Unterstützt Tool-Modus. |
| Default Value | Read | Wird zurückgegeben, wenn der Schlüssel nicht existiert. Leer lassen, um null zurückzugeben. |
Ausgabe¶
Die Komponente gibt eine einzelne Data-Ausgabe aus. Das Ausgabe-Label ändert sich dynamisch je nach Modus:
| Modus | Ausgabe-Label | Schlüsselfelder |
|---|---|---|
| Read | Value | key, value, scope |
| Write | Stored | key, value, scope |
| Delete | Deleted | key, deleted, scope |
Anwendungsbeispiele¶
Nutzerpräferenzen über Sessions hinweg merken¶
Scope auf User setzen und in einer Session einen Präferenzwert schreiben:
Mode: Write | Scope: User | Key: "preferred_language" | Value: "de"
In einer späteren Session wieder auslesen:
Mode: Read | Scope: User | Key: "preferred_language" | Default Value: "en"
Flow-weiter gemeinsamer Zähler¶
Scope auf Agent setzen, damit alle Sessions denselben Zähler teilen:
Mode: Read | Scope: Agent | Key: "invocation_count"
→ (im Flow inkrementieren)
Mode: Write | Scope: Agent | Key: "invocation_count" | Value: <inkrementiert>
Temporärer Session-Zustand¶
Session-Scope verwenden, um Zwischenergebnisse zu speichern, die nicht über Sessions hinweg sichtbar sein sollen:
Mode: Write | Scope: Session | Key: "draft_response" | Value: "..."
Speicher-Backend¶
Daten werden in der Datenbanktabelle agentlab_kv_store persistiert, die durch eine fork-spezifische Alembic-Migration angelegt wird. Jeder Eintrag ist eindeutig durch das Tripel (scope_type, scope_id, key) identifiziert. Schreibvorgänge sind Upserts — Schreiben auf einen existierenden Schlüssel überschreibt den Wert und aktualisiert den Zeitstempel.