# Fehlerbehebung Nutzen Sie Hinweise zu Symptom, Ursache, Maßnahme und Sicherheit, wenn OAuth, MCP-Erkennung oder der Abruf sich nicht wie erwartet verhalten. - Canonical: https://docs.xmemo.dev/de/docs/troubleshooting - Locale: de-DE - Content-Locale: de-DE - Canonical-Content-Digest: 78719b9cecfa970434f8f31e363e6e5cca1f6171a945b7c98cd4db05a669dc4b - Edition-Digest: eb6f37c3532b84c7018eece3f8d632ff9ea14e57aea6fc0d0b81e9439102cc9e - Source-Revision: sha256:888cdc62dd33778dae5cd658cec828efa3504abd545d98fc35af9f3fbd35157a ## Verbindung ohne Schreiben in den memory überprüfen Jeder unten aufgeführte Pfad zur Problembehebung endet mit einem verification Schritt. Beginnen Sie mit einem Lesevorgang: Er weist credential und transport nach, ohne etwas zu verändern. ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H 'X-API-Key: ' \ 'https://xmemo.dev/v1/memories/search?query=connection%20check&limit=1' ``` ## status code interpretieren Der Status unterscheidet ein credential Problem von einem leeren memory store. ```text 200 — authorized; an empty results array just means nothing matched. 401 — the credential is missing or not valid. 403 — the credential is valid but lacks the required scope. ``` ## Client-Verbindungsfehler Wenn ein KI-Client oder Runner den MCP-Server nicht erreichen kann, isolieren Sie die Transportprotokoll-Aushandlung und das Host-Routing, bevor Sie Token rotieren. - Überprüfen Sie den Serverzustand mit einem direkten GET auf /health oder OPTIONS auf /mcp. - Prüfen Sie die Transportkompatibilität: Gehostete Clients nutzen Streamable HTTP (/mcp); lokale CLI-Tools nutzen stdio. - Stellen Sie sicher, dass Unternehmens-Proxys oder Firewalls gestreamte SSE-Antworten ohne Chunk-Abschneidung zulassen. ```bash curl -I -s 'https://xmemo.dev/mcp' ``` ## Authentifizierungsfehler Authentifizierungsfehler unterscheiden fehlende Anmeldedaten (401 Unauthorized) von unzureichenden Berechtigungen oder Mandantengrenzenverletzungen (403 Forbidden). - OAuth-Clients: Über die Host-App neu verbinden und memory:read sowie memory:write gewähren. - Direct MCP-Clients: Sicherstellen, dass XMEMO_KEY in der Prozessumgebung gesetzt ist, ohne Secrets in git offenzulegen. - 403 Forbidden: Bestätigen, dass das Token zum aktiven Mandanten und project scope gehört. ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H 'Authorization: Bearer ' \ 'https://xmemo.dev/v1/memories/search?query=auth%20check&limit=1' ``` ## Leere Abfrageergebnisse Wenn die Abfrage keine Ergebnisse liefert, deutet dies auf eine Bereichs- oder Abfrage-Diskrepanz hin, nicht auf einen Serverfehler. Lesevorgänge enden mit 200 OK, wenn keine Erinnerungen übereinstimmen. - Project scope-Diskrepanz: Überprüfen Sie, ob der anfragende Agent im selben project wie die gespeicherte Erinnerung operiert. - Agent-Instanzgrenze: Direct-Clients, die nach XMEMO_AGENT_INSTANCE_ID filtern, können keine unter anderen Instanzkennungen gespeicherten Erinnerungen lesen. - Statusprüfung: In der Memory Console verifizieren, dass die Erinnerung übergeben wurde und den Status active besitzt, nicht gelöscht oder veraltet. ```bash curl -s -H 'Authorization: Bearer ' \ 'https://xmemo.dev/v1/memories/search?query=test&limit=5&scope=project:demo' ``` ## Schreibsperren-Timeouts Gleichzeitige Schreibvorgänge von mehreren Runnern oder parallele Tool-Aufrufe können zu Sperrenkonflikten auf gemeinsam genutzten memory paths führen. - Implementieren Sie ein exponentielles Backoff mit zufälligem Jitter, wenn Schreibanfragen Sperrenkonflikte melden. - Übergeben Sie bei Wiederholungsversuchen einen clientseitigen Idempotenzschlüssel (idempotency key), um Duplikate zu verhindern. - Serialisieren Sie Mutationsvorgänge für hochfrequente Workflows mithilfe von Task-Warteschlangen oder Batch-APIs. ```bash curl -s -X POST 'https://xmemo.dev/v1/memories' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{"content":"Durable convention fact","path":"projects/demo/conventions"}' ``` ## Warum erinnert sich mein KI-Assistent nicht an etwas, das ich ihm zuvor mitgeteilt habe? Ich habe eine wichtige Präferenz oder ein Detail gespeichert, aber in einem späteren Chat verhält sich mein KI-Assistent so, als hätte er dies nie gesehen. Der Assistent ist möglicherweise mit einem anderen XMemo-Konto, Projekt oder Gerätekontext verbunden, oder die ursprüngliche Erinnerung wurde nicht gespeichert. Bitten Sie den Assistenten, ein kleines, unkritisches Testdetail zu speichern. Öffnen Sie anschließend die Memory Console und prüfen Sie, ob es unter dem von Ihnen verwendeten Konto und Projekt erscheint. Verwenden Sie ein frei erfundenes Testdetail; nutzen Sie keine privaten Daten anderer Personen. ## Warum verwechselt mein KI-Assistent meine Projekte oder Konversationen? Ein Detail aus einem Projekt taucht in einem anderen auf, oder der Assistent antwortet so, als gehörten zwei Konversationen zusammen. Der Assistent verwendet möglicherweise einen anderen Projekt- oder Kontokontext als denjenigen, in dem die Erinnerung gespeichert wurde. Wählen Sie im Assistenten das vorgesehene XMemo-Konto und -Projekt aus, verbinden Sie ihn bei Bedarf erneut und wiederholen Sie den Vorgang mit einem klar gekennzeichneten Testdetail. Verschieben Sie keine privaten Informationen zwischen Projekten, nur um deren Anzeige zu erzwingen. ## Wie kann ich meinen KI-Assistenten dazu bringen, etwas vollständig zu vergessen? Ich möchte eine Erinnerung entfernen lassen und muss sicherstellen, dass sie wirklich verschwunden ist. Das Einsehen, wiederherstellbare Entfernen, dauerhafte Löschen und Exportieren von Erinnerungen sind unterschiedliche Kontoaktionen. Öffnen Sie die Memory Console, suchen Sie die Erinnerung und nutzen Sie die entsprechende Funktion zum Löschen oder Vergessen; falls Sie die Funktion nicht finden, kontaktieren Sie den Support unter Angabe der Speicherreferenz. Löschen Sie ausschließlich die gewünschte Erinnerung und geben Sie niemals vertrauliche Inhalte in Support-Nachrichten weiter. ## Ich habe den Computer oder KI-Assistenten gewechselt; erinnert sich XMemo weiterhin an mich? Meine früheren Erinnerungen scheinen von neuen getrennt zu sein, nachdem ich das Gerät gewechselt, einen Assistenten neu gestartet oder den Host gewechselt habe. Die neue Assistentenverbindung stuft das Gerät oder den Assistenten möglicherweise als neue Quelle ein oder ist an einem anderen Konto angemeldet. Verbinden Sie XMemo in dem gewünschten Assistenten erneut, melden Sie sich am selben Konto an und halten Sie die Gerätebezeichnung der Verbindung stabil, sofern die Anwendung diese Option anbietet. Prüfen Sie das Konto, bevor Sie persönliche Informationen auf einem gemeinsam genutzten Computer speichern. ## Warum hat mein KI-Assistent denselben Sachverhalt doppelt gespeichert? Ich sehe nach einem Neuversuch oder Wiederverbinden zwei Kopien derselben Erinnerung. Der erste Speichervorgang war möglicherweise bereits erfolgreich, obwohl der Assistent das Ergebnis nicht angezeigt hat, sodass eine Wiederholung der Anfrage eine weitere Kopie anlegte. Öffnen Sie die Memory Console, vergleichen Sie die beiden Einträge und entfernen Sie nur das Duplikat, nachdem Sie Datumsangaben und Quelle überprüft haben. Löschen Sie nicht pauschal alle übereinstimmenden Erinnerungen, bevor Sie das Exemplar identifiziert haben, das Sie behalten möchten. ## Warum liefert mein KI-Assistent zu viel oder zu wenig aus meinem früheren Kontext? Der Assistent bringt irrelevante Details ein, übersieht die benötigte Entscheidung oder liefert eine überfrachtete Antwort. Die Anfrage deckt ein zu breites Thema oder Zeitfenster ab, oder der Assistent versucht, mehr gespeicherten Kontext heranzuziehen, als die Konversation erfordert. Grenzen Sie die Anfrage auf ein spezifischeres Thema, Projekt oder Zeitfenster ein und teilen Sie dem Assistenten mit, welche Entscheidung oder welches Detail am wichtigsten ist. Bitten Sie den Assistenten nicht darum, unbeteiligte private Erinnerungen offenzulegen, nur um die Konversation aufzufüllen. ## Ich habe XMemo getrennt; wie stelle ich sicher, dass der frühere Assistent keinen Zugriff mehr hat? Ich habe die Verbindung in einem Assistenten entfernt, bin mir aber unsicher, ob er weiterhin auf meine Erinnerungen zugreifen kann. Das Entfernen einer Verbindung aus der Benutzeroberfläche hebt die Verbindungsberechtigung auf Kontoebene nicht zwingend auf. Öffnen Sie die Einstellungen für verbundene Apps oder Sicherheitseinstellungen Ihres XMemo-Kontos, widerrufen Sie die frühere Assistentenverbindung und verbinden Sie nur die Verbindung neu, der Sie vertrauen. Widerrufen Sie ausschließlich die beabsichtigte Verbindung und teilen Sie keine Anmeldedaten Ihres Kontos. ## Warum kann mein KI-Assistent XMemo nicht mehr verwenden? XMemo war in meinem Assistenten verfügbar, aber die Speicheraktionen erscheinen nicht mehr oder der Assistent meldet, dass er sie nicht nutzen kann. Die Verbindung des Assistenten mit XMemo muss möglicherweise aktualisiert werden oder der Assistent ist an einem anderen Konto angemeldet. Öffnen Sie die Einstellungen für verbundene Anwendungen im Assistenten, trennen Sie XMemo und verbinden Sie es erneut. Starten Sie anschließend einen neuen Chat. Fügen Sie niemals geheime Zugangsdaten oder private Erinnerungen in einen Chat oder eine Supportanfrage ein. ## Welche XMemo-Verbindung soll ich in meinem KI-Assistenten verwenden? Ich bin mir unsicher, welche XMemo-Seite oder -Verbindung in die Einstellungen meines Assistenten gehört. Die Seite für das geführte Setup und die Assistentenverbindung dienen unterschiedlichen Zwecken, und gehostete sowie selbstverwaltete Setups haben getrennte Grenzen. Für den gehosteten Dienst beginnen Sie unter https://xmemo.dev/product/docs und folgen dem für Ihren Assistenten angezeigten Verbindungslink; fragen Sie den Support, falls Ihre Organisation Ihnen eine abweichende Setup-Seite bereitgestellt hat. Nutzen Sie keine lokalen Entwicklungsadressen und fügen Sie keine privaten Zugangsdaten in einen öffentlichen Chat ein. ## Was soll ich tun, wenn mein KI-Assistent weiterhin keine Verbindung zu XMemo herstellen kann? Ich habe die Verbindungsschritte wiederholt, aber der Assistent kann XMemo weiterhin nicht verwenden. Das Problem kann bei der Assistenten-App, Ihrem Konto oder einer veralteten Verbindung liegen, die durch öffentliche Dokumentation nicht analysiert werden kann. Wenden Sie sich mit dem Namen des Assistenten, dem ungefähren Zeitpunkt und einer kurzen Beschreibung der Beobachtungen an den Support; übermitteln Sie ausschließlich geschwärzte Details. Senden Sie niemals Anmeldedaten, Einmalcodes, Cookies oder privaten Speichertext. ## OAuth ist fehlgeschlagen oder das Zustimmungsfenster schließt nicht ab. Der Client zeigt 401 an, der OAuth-Browser öffnet sich nicht oder die Zustimmung kehrt ohne nutzbare Verbindung zum Client zurück. Die gehostete Autorisierung ist möglicherweise veraltet, die Browser-Übergabe wird blockiert oder der Client nutzt eine veraltete Serverregistrierung. Melden Sie sich in der Host-Anwendung vom XMemo MCP-Server ab, verbinden Sie die gehostete MCP-URL erneut und genehmigen Sie memory:read sowie memory:write nochmals. Wechseln Sie in OAuth-Clients nicht zu XMEMO_KEY, nur um eine veraltete OAuth-Sitzung zu umgehen. ## Die Anfrage gibt 403 Forbidden zurück. Der Server ist erreichbar und die Anmeldedaten werden erkannt, aber die angeforderte Projekt-, Tool- oder Speicheraktion wird verweigert. Der Berechtigung fehlt der erforderliche Scope, das Konto liegt außerhalb der gewählten Projektgrenze oder die Ressource gehört zu einem anderen Mandanten. Prüfen Sie das ausgewählte Konto und Projekt, verbinden Sie OAuth neu oder fordern Sie den gewünschten Scope an und wiederholen Sie denselben Vorgang, ohne die Ressource zu verändern. Erweitern Sie keine Scopes und kopieren Sie kein Token eines anderen Benutzers, um einen 403-Fehler zu beseitigen. ## Der MCP-Server verbindet sich, aber es erscheinen keine Tools. Der Host zeigt einen verbundenen Server an, aber tools/list ist leer oder die XMemo-Tools fehlen in der Tool-Auswahl des Modells. Der Client hat die Erkennung nicht aktualisiert, verwendet das falsche MCP-Profil oder ist mit einer veralteten URL bzw. Registrierung verbunden. Verbinden Sie den Server neu, überprüfen Sie, ob der Client das unterstützte MCP-Profil verwendet, und führen Sie die Tool-Erkennung erneut durch, bevor Sie Anmeldedaten ändern. Fügen Sie keine Bearer-Tokens in Screenshots, Support-Tickets oder Rezensionshinweise von Marketplaces ein. ## Ein direkter MCP-Client meldet, dass das Token fehlt. Ein direkter Client meldet, dass XMEMO_KEY nicht gesetzt, leer oder nicht verfügbar ist, obwohl die Variable auf dem System eingerichtet wurde. Der Client-Prozess hat die Umgebungsvariablen nicht übernommen, die Variable wurde in einer anderen Shell definiert oder die Konfiguration erwartet stattdessen eine Referenz auf einen Secret-Store. Setzen Sie XMEMO_KEY in der lokalen Umgebung oder im Secret-Store, starten Sie den Client neu und halten Sie XMEMO_AGENT_INSTANCE_ID stabil, wenn Attribution von Bedeutung ist. Halten Sie das echte Token außerhalb von Konfigurationsdateien, die in Git committet werden; öffentliche Beispiele dürfen nur auf Umgebungsvariablen verweisen. ## Die Agent-Instanz-ID ändert sich nach jedem Neustart. Derselbe lokale Runner wird als mehrere Agenten angezeigt oder Abrufe werden nach einem Neustart bzw. Redeployment über Instanzen hinweg aufgeteilt. XMEMO_AGENT_INSTANCE_ID wird beim Prozessstart generiert, anstatt in der lokalen Secret- oder Umgebungskonfiguration des Runners persistent gespeichert zu werden. Generieren Sie eine nicht-geheime Instanzbezeichnung pro Runner, speichern Sie diese außerhalb von Git und übermitteln Sie sie bei jeder direkten MCP-Verbindung. Die Instanzbezeichnung ist Attributionsmetadatum, kein Autorisierungsnachweis; Konto- und Tokengrenzen steuern weiterhin den Zugriff. ## Der Abruf liefert einen leeren Speicher zurück. Ein Abruf oder eine Suche ist erfolgreich, liefert jedoch keine relevanten Datensätze, nachdem der Benutzer Kontext gespeichert hat. Der Lesevorgang verwendet ein anderes Konto, Projekt, einen anderen Scope, eine andere Agentengrenze oder einen anderen Speichertyp als der Schreibvorgang, oder der Testdatensatz wurde nie festgeschrieben. Erstellen Sie eine synthetische Testerinnerung, überprüfen Sie Pfad und Speichertyp in der Memory Console und wiederholen Sie den Abruf über dieselbe Konto- oder Mandantengrenze. Verwenden Sie synthetische Prüfdaten; nutzen Sie keine privaten Kundenerinnerungen für Marketplace-Demos. ## Abruf oder Schreibvorgang verwenden den falschen Projekt-Scope. Ein Datensatz ist in einem Projekt sichtbar, in einem anderen jedoch nicht, oder ein Schreibvorgang erscheint unter einem Projekt, das der Operator nicht beabsichtigt hatte. Der Client hat eine Projektkennung aus einer anderen Umgebung wiederverwendet, die Projektgrenze weggelassen oder eine veraltete Kontositzung beibehalten. Wählen Sie das gewünschte Konto und Projekt explizit aus, aktualisieren Sie den Client-Kontext und wiederholen Sie den Vorgang mit einem synthetischen Datensatz. Beheben Sie eine Scope-Diskrepanz niemals durch Erteilen eines weiter gefassten Tokens oder durch Kopieren von Daten zwischen Projekten. ## Dieselbe Erinnerung wird doppelt gespeichert. Ein Wiederholungsversuch oder Reconnect erzeugt doppelte Datensätze statt einer dauerhaften Erinnerung. Der Client hat nach einem Timeout ohne Idempotenzgrenze einen erneuten Versuch gestartet, oder der Erfassungsworkflow schreibt, bevor die erste Antwort bestätigt wurde. Prüfen Sie zuerst den vorhandenen Datensatz und die Quellenzuordnung, und nutzen Sie die Wiederholungsrichtlinie des Clients oder einen stabilen Idempotenzschlüssel vor einem erneuten Schreibversuch. Löschen Sie übereinstimmende Erinnerungen nicht massenhaft, bevor der gewünschte Datensatz und der Kontorahmen bestätigt wurden. ## Der Abrufkontext ist zu groß oder zu klein. Der Agent erhält irrelevanten Kontext, verfehlt die benötigte Entscheidung oder überschreitet das nutzbare Kontextbudget des Hosts. Die Abfrage ist zu weit gefasst, der Scope oder das Zeitfenster fehlt, oder der Aufrufer hat ein für die Aufgabe ungeeignetes Ergebnislimit angefordert. Grenzen Sie die Abfrage mit Projekt-, Agent-, Zeit- oder Themengrenzen ein und fordern Sie zunächst eine kleine relevante Menge an, bevor Sie das Limit erhöhen. Erweitern Sie nicht den Scope und exportieren Sie keine unbeteiligten Erinnerungen, nur um ein Kontextfenster zu füllen. ## Wie lösche oder exportiere ich Speicher? Der Operator muss einen Datensatz entfernen, einen Vergessensvorgang bestätigen oder einen kontobezogenen Export anfordern. Löschen, wiederherstellbares Vergessen, dauerhaftes Löschen und Exportieren sind eigenständige Workflows mit unterschiedlicher Bestätigungs- und Wiederherstellungssemantik. Nutzen Sie zuerst die Memory Console oder Kontoworkflows; falls kein Self-Service-Pfad verfügbar ist, wenden Sie sich an den Support, damit die Anfrage auf das Konto beschränkt bleibt. Exporte und Support-Pakete dürfen keine Token-Hashes, API-Schlüssel, Sitzungsgeheimnisse, Provider-Anmeldedaten oder Daten unbeteiligter Mandanten enthalten. ## Wie widerrufe ich den Zugriff, nachdem ein Client getrennt wurde? Ein Client wurde lokal entfernt, aber der Operator muss dessen OAuth-Genehmigung oder direkte Anmeldedaten ungültig machen. Das Trennen einer Client-Konfiguration widerruft serverseitige Genehmigungen nicht zwangsläufig und rotiert kein direktes Token. Öffnen Sie die Kontosicherheits- oder Client-Steuerung, widerrufen Sie die benannte OAuth-Genehmigung und rotieren Sie den direkten Berechtigungsnachweis, falls dieser exponiert wurde oder ihm nicht mehr vertraut wird. Widerrufen Sie ausschließlich den vorgesehenen Client oder die vorgesehene Genehmigung; veröffentlichen Sie keine alten Tokens, OAuth-Codes oder Sitzungsdetails während der Zugriffsdiagnose. ## Ist XMemo GA, zertifiziert oder im Marketplace gelistet? Ein Eintrag oder Dokument wirft die Frage auf, ob eine funktionierende Konfiguration GA-Status, Zertifizierung oder Marketplace-Genehmigung belegt. Konfigurationsunterstützung, OAuth-Bereitschaft, Pilotnachweise und Marketplace-Genehmigung sind getrennte Aussagen. Behandeln Sie öffentliche Formulierungen als Beta bzw. konfigurationsunterstützt, es sei denn, ein konkretes Marketplace-Genehmigungs- oder Zertifizierungsartefakt liegt vor. Leiten Sie einen GA-, zertifizierten, stabilen oder gelisteten Status nicht allein aus einer funktionierenden Konfiguration ab. ## Welche URL sollte ich verwenden? Ein Nutzer der gehosteten Version ist unsicher, ob er dem öffentlichen Quickstart, dem MCP-Endpunkt oder den Anweisungen für selbst gehostete Entwickler folgen soll. Gehostetes Onboarding sowie selbst gehostete oder ältere Bereitstellungspfade haben unterschiedliche URLs, Anmeldedaten und Datengrenzen. Nutzer des gehosteten Dienstes sollten für MCP-Clients mit https://xmemo.dev/mcp und für die geführte Einrichtung mit https://xmemo.dev/product/docs beginnen. Verwenden Sie für öffentliche Nutzer des gehosteten Dienstes keinesfalls localhost-, Supabase-, Docker- oder selbst gehostete Python-Anleitungen als ersten Schritt. ## Erinnerungen erscheinen unter dem falschen Agenten oder Gerät. Eine Erinnerung wird einem anderen Runner zugeordnet oder erscheint nach einem Client-Update oder Neustart über Geräte hinweg aufgeteilt. Der Client hat seine nicht-geheimen Agent- oder Instanz-Header geändert, oder ein geteilter Berechtigungsnachweis wird von mehreren Runnern verwendet. Überprüfen Sie die nicht-geheimen Agent-/Geräte-Header oder das Client-Profil und speichern Sie die lokale Instanz-ID dauerhaft, statt sie neu zu generieren. Attributionsbezeichnungen erleichtern die Quellprüfung, stellen jedoch keine Sicherheitsgrenze dar; Konto-Anmeldedaten bestimmen weiterhin den Zugriff. ## Ich kann mich nach Befolgen der Schritte immer noch nicht verbinden. Die Verbindung bleibt nicht verfügbar, nachdem der client-spezifische OAuth- oder Direct-Secret-Pfad wiederholt wurde. Das verbleibende Problem kann client-spezifisch, kontospezifisch oder durch eine veraltete Registrierung bzw. Umgebungsgrenze bedingt sein, die lokale Dokumentationen nicht einsehen können. Öffnen Sie eine Supportanfrage mit Client-Namen, Konfigurationspfad, ungefährem Zeitstempel und der Information, ob der Client OAuth oder XMEMO_KEY verwendet. Teilen Sie ausschließlich geschwärzte Diagnosedaten; senden Sie niemals Bearer-Tokens, OAuth-Codes, Cookies oder Speicherinhalte von Kunden.