Memory Stores in selbst gehosteten Sandboxes

Sitzungen in einer selbst gehosteten Umgebung hängen Memory Stores genauso an wie Sitzungen in Cloud-Umgebungen. Führe sie in resources auf, wenn du die Sitzung erstellst, wie in Einen Memory Store an eine Session anhängen gezeigt. Eine Sitzung akzeptiert bis zu 8 Memory Stores.

Der Unterschied liegt darin, wer den Store materialisiert. In einer selbst gehosteten Umgebung lädt dein Worker statt der Infrastruktur von Anthropic jeden Store in die Sandbox herunter und synchronisiert die Änderungen des Agenten zurück.

Voraussetzungen

• Ein Worker, der Memory Stores einbindet: Verwende die ant CLI 1.33.0 oder neuer oder EnvironmentWorker aus dem Python-, TypeScript- oder Go-SDK.
• Ein POSIX-Dateisystem: Windows-Hosts werden nicht unterstützt, da der Worker beim Öffnen von Memory-Dateien O_NOFOLLOW benötigt. Ein Dateisystem, das zwischen Groß- und Kleinschreibung unterscheidet, wird empfohlen, damit Memory-Pfade, die sich nur in der Groß-/Kleinschreibung unterscheiden, nicht kollidieren.
• Ein beschreibbares Verzeichnis /mnt/memory: Siehe Den Host vorbereiten.
• Das Secret des Arbeitselements: Wenn dein eigener Code den Worker startet, leite das Secret des Arbeitselements an ihn weiter.

Den Host vorbereiten

Bevor du den Worker startest, erstelle das übergeordnete Verzeichnis und mache es für den Benutzer beschreibbar, unter dem der Worker läuft:

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

Erstelle die Verzeichnisse für die einzelnen Stores nicht selbst. Der Worker erstellt das mount_path-Verzeichnis jedes Stores (zum Beispiel /mnt/memory/user-preferences), wenn eine Sitzung startet, und entfernt es, wenn die Sitzung endet. Wenn unter diesem Pfad bereits etwas existiert, weigert sich der Worker, die Arbeit der Sitzung zu starten.

Beim Muster mit einer Sandbox pro Sitzung benötigt das Sandbox-Image ein beschreibbares /mnt/memory. Du musst die Memory-Verzeichnisse nicht per Bind-Mount mit dem Host verbinden, da der Worker ihren Inhalt in den Store hochlädt, bevor die Sandbox beendet wird.

Sitzungen isolieren, die sich einen Store teilen

Zwei Sitzungen können denselben Store nicht gleichzeitig auf einem Host einbinden, da beide denselben Pfad benötigen. Wenn deine Sitzungen denselben Store anhängen, führe eine Sitzung pro Dateisystem aus. Wenn du jeder Sitzung ihre eigene Sandbox gibst, ist diese Regel erfüllt.

Wie der Worker mit Memory umgeht

Wenn der Worker ein Arbeitselement beansprucht, dessen Sitzung Memory Stores angehängt hat, geht er wie folgt vor:

1. Er lädt jeden Store in seinen mount_path herunter. Dies ist dasselbe Verzeichnis unter /mnt/memory/, das Cloud-Sitzungen verwenden, und der System-Prompt der Sitzung beschreibt es dem Agenten. Ein Store namens „User Preferences“ landet zum Beispiel unter /mnt/memory/user-preferences/.
2. Er öffnet diese Verzeichnisse für die Datei-Tools. Der Agent bearbeitet Memories mit denselben Datei-Tools, die er im Arbeitsverzeichnis verwendet.
3. Er gleicht Änderungen nach Tool-Aufrufen ab, höchstens einmal pro Synchronisierungsintervall (standardmäßig 15 Sekunden). Memories, die sich im Store geändert haben, werden auf die Festplatte geschrieben, und Dateien, die der Agent geändert hat, werden in den Store hochgeladen.
4. Er führt eine abschließende Synchronisierung durch, wenn die Sitzung endet. Er schließt noch ausstehende Uploads bis zu 30 Sekunden lang ab und entfernt dann die Verzeichnisse, die er erstellt hat.

Der Memory Store auf der Seite von Anthropic bleibt die maßgebliche Quelle. Memory-Versionen, Schwärzung sowie das Anzeigen oder Bearbeiten von Memories in der Console funktionieren wie bei Cloud-Sitzungen. Die Lese- und Schreibvorgänge des Agenten auf Memories erscheinen im Event-Stream als gewöhnliche Tool-Events.

Da jeder Worker in einem Intervall synchronisiert, wird eine in einer Sitzung geschriebene Änderung für eine andere laufende Sitzung erst sichtbar, nachdem beide synchronisiert haben. Beim Standardintervall dauert das typischerweise deutlich weniger als eine Minute. Sitzungen in Cloud-Sandboxes sehen die Änderungen der jeweils anderen fast sofort.

Jedes Store-Verzeichnis enthält eine Markierungsdatei namens .anthropic-memory-store, die das Verzeichnis mit seinem Store verknüpft. Lass sie an ihrem Platz: Der Worker synchronisiert kein Verzeichnis, dessen Markierung fehlt oder verändert wurde.

Synchronisierung konfigurieren

Zwei EnvironmentWorker-Optionen steuern das Memory-Verhalten. Setze sie überall dort, wo du den Worker erstellst, auch in einem Webhook-Handler. Der Worker der ant CLI verwendet immer die Standardwerte.

Synchronisierungsintervall

memory_sync_interval legt fest, wie oft angehängte Stores während der Sitzung mit dem Server abgeglichen werden.

Ein kürzeres Intervall verkleinert das Zeitfenster, in dem eine andere Sitzung veraltete Memories sieht, auf Kosten von mehr Anfragen an den Memory Store.

Deaktiviere die Memory-Unterstützung nur bei Workern, deren Sitzungen keine Memory Stores anhängen. Ein deaktivierter Worker lädt Stores weder herunter noch synchronisiert er sie, sodass eine Sitzung mit angehängten Stores ohne diese läuft, obwohl ihr System-Prompt sie weiterhin beschreibt.

Solange die Memory-Unterstützung aktiviert ist, schlägt ein Arbeitselement, das ohne secret für eine Sitzung mit angehängten Stores eintrifft, fehl, anstatt ohne Memory zu laufen. Siehe Memory Stores lassen sich nicht einbinden.

Löschungen

memory_sync_deletions legt fest, ob eine Datei, die der Agent lokal löscht, auch aus dem Store gelöscht wird. Uploads und Downloads sind davon nicht betroffen.

Zum Beispiel, um alle 10 Sekunden zu synchronisieren und die Löschungen, die der Worker vorgenommen hätte, nur zu protokollieren:

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

Schreibgeschützte Stores und Konflikte

Bei einem Store, der mit access: "read_only" angehängt ist, verweigern die Tools write und edit Änderungen an Dateien in seinem Verzeichnis. Der Worker lädt nie etwas daraus hoch.

Änderungen über bash oder über ein benutzerdefiniertes Tool oder einen MCP-Server, den du aus der Sandbox bereitstellst, werden lokal nicht blockiert. Sie werden nie mit dem Store synchronisiert, und die nächste entfernte Änderung an dieser Memory überschreibt sie. Wenn die lokale Kopie selbst während der Sitzung unverändert bleiben muss:

• Deaktiviere das bash-Tool für diesen Agenten und gib ihm kein benutzerdefiniertes Tool, das in das Dateisystem der Sandbox schreibt.
• Binde den Store-Pfad nicht schreibgeschützt ein. Der Worker selbst muss das Verzeichnis erstellen und die heruntergeladenen Memories hineinschreiben.

Konflikte werden zugunsten des Stores aufgelöst. Angenommen, der Agent ändert eine Memory-Datei, die sich seit der letzten Synchronisierung der Sitzung auch im Store geändert hat. Bei der nächsten Synchronisierung behält der Worker die Version des Stores, überschreibt die lokale Datei damit und protokolliert eine Warnung. Die Tools write und edit selbst sind erfolgreich, und kein Fehler erreicht den Agenten. Wenn die Änderung des Agenten weiterhin relevant ist, kann er die Datei nach der Synchronisierung erneut lesen und die Änderung noch einmal vornehmen.

Fehlerbehebung

Siehe Memory Stores lassen sich nicht einbinden für die Log-Meldungen des Workers und deren Behebung.