Erste SchritteStartenSchnellstart

Quickstart

Schnellstart

Verbinden Sie einen Client, speichern Sie nützlichen Kontext, rufen Sie ihn später ab und halten Sie Anmeldedaten aus der öffentlichen Konfiguration heraus.

1. Client und Authentifizierungsmodus wählen

Wählen Sie Ihren Agenten-Client und den bevorzugten Verbindungspfad. Verwenden Sie für Claude Code, Codex und kompatible Agenten das eigenständige Skill-Installationsprogramm mit 'Fragen Sie Ihren Agenten'. Für Clients ohne Skills wie ChatGPT verwenden Sie gehostetes MCP über OAuth. Für direkte und monitorlose Runner wie Cursor oder VS Code verwenden Sie direktes MCP mit XMEMO_KEY. Dedizierte Client-Anleitungen finden Sie unter /docs/mcp/claude-code, /docs/mcp/codex, /docs/connect/openclaw, /docs/mcp/chatgpt, /docs/mcp/cursor und /docs/mcp/copilot.

  • Pfad 1 (Skill): Bitten Sie Ihren Agenten, den eigenständigen XMemo Skill für Claude Code, Codex und OpenClaw (/docs/connect/openclaw) zu installieren.
  • Pfad 2 (OAuth MCP): Gehostetes MCP über OAuth für Clients ohne Skills, einschließlich ChatGPT (/docs/mcp/chatgpt) und Claude Desktop (/docs/mcp/overview).
  • Pfad 3 (Direktes MCP): Direktes Streamable HTTP MCP unter Bezugnahme auf ${XMEMO_KEY} aus Ihrer lokalen Umgebung für Cursor (/docs/mcp/cursor) und VS Code (/docs/mcp/copilot).
  • Authentifizierungsmodi: OAuth (bevorzugt, browserbestätigt) vs. direktes MCP (Umgebungsvariable XMEMO_KEY).
  • Zwischenstatus: Das Auswählen eines Clients und Kopieren der Konfiguration ist ein Zwischenschritt, keine Aktivierung.

2. Client ohne Offenlegung von Tokens konfigurieren

Installieren Sie den eigenständigen Skill oder konfigurieren Sie Ihren Client über den gehosteten MCP-Endpunkt (https://xmemo.dev/mcp). Übergeben Sie bei Skill-Clients Ihrem Agenten den offiziellen Installations-Prompt als primäre Kopieraktion oder führen Sie das kanonische Installationsprogramm manuell aus. Verweisen Sie bei direktem MCP auf ${XMEMO_KEY} aus Ihrer lokalen Umgebung oder Ihrem Secret-Store. Betten Sie niemals unverschlüsselte Bearer-Tokens im Klartext in Client-Konfigurationsdateien oder in die Versionskontrolle ein.

  • Pfad 1 (Fragen Sie Ihren Agenten): Installieren Sie den eigenständigen XMemo Skill in Ihrem Skills-Verzeichnis: Führen Sie das Installationsprogramm von https://xmemo.dev/skill/install (unter Windows: https://xmemo.dev/skill/install.ps1) mit XMEMO_SKILL_DIR auf Ihr Skills-Verzeichnis plus /xmemo-memory aus. Führen Sie den ausgegebenen doctor-Befehl aus, um die Installation zu überprüfen, laden Sie dann Ihre Skills neu und befolgen Sie die Ersteinrichtungsschritte des Skills. Beachten Sie Ihre normalen Sicherheitsprüfungen und verwenden Sie keine erweiterten Berechtigungen.
  • Manueller Ausweichpfad: Führen Sie 'curl -fsSL https://xmemo.dev/skill/install | sh' (Windows PowerShell: 'irm https://xmemo.dev/skill/install.ps1 | iex') mit explizit gesetztem XMEMO_SKILL_DIR aus.
  • OAuth-Clients: Konfigurieren Sie https://xmemo.dev/mcp und genehmigen Sie memory:read und memory:write im Browser.
  • Direktes MCP: Verweisen Sie auf ${XMEMO_KEY} in der Konfiguration; halten Sie das reale Token in Ihrer lokalen Umgebung oder Ihrem Secret-Store.
  • Null Secrets: Konfigurationsdateien dürfen niemals unverschlüsselte Bearer-Tokens enthalten.
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}

3. Verbindung mit schreibgeschützter Prüfung verifizieren

Überprüfen Sie die Verbindung vor dem Schreiben von Daten stets mit einer schreibgeschützten Anfrage. Installation, Authentifizierung und Aktivierung sind getrennte Meilensteine. Führen Sie für den eigenständigen Skill den vom Installationsprogramm ausgegebenen doctor-Befehl aus. Wählen Sie vor dem Anmelden Ihren Anmeldedatenpfad: Bevorzugen Sie die Bereitstellung von XMEMO_KEY aus einem Secret-Store oder verwenden Sie verwaltete Anmeldedaten. Wenn Sie die interaktive Geräteanmeldung mit --allow-plaintext verwenden, beachten Sie, dass dieses Flag die Anmeldedaten unverschlüsselt auf diesem Computer speichert. Überprüfen Sie den Status nach der Authentifizierung. Für MCP-Clients bestätigt get_mcp_identity, dass Ihr Client den Server erreichen kann und Ihr memory:read-Geltungsbereich gültig ist.

  • Skill doctor-Befehl: node scripts/xmemo-skill.mjs doctor --anonymous (prüft Laufzeit und Verbindung).
  • Skill-Anmeldedatenalternativen: Stellen Sie XMEMO_KEY aus einem Secret-Store bereit oder verwenden Sie verwaltete Anmeldedaten.
  • Skill-Geräteanmeldung: node scripts/xmemo-skill.mjs login --allow-plaintext (öffnet Browserüberprüfung; beachten Sie, dass --allow-plaintext die Anmeldedaten unverschlüsselt auf diesem Computer speichert).
  • Skill-Authentifizierungsprüfung: node scripts/xmemo-skill.mjs auth status --verify (bestätigt die Gültigkeit der Anmeldedaten).
  • MCP-Tool: get_mcp_identity() (oder recall mit Limit 1).
  • Berechtigungsschranke: memory:read.
  • Erfolgssignal: Identitäts-Metadaten bestätigen, dass der Server erreichbar und autorisiert ist.
get_mcp_identity()

4. Explizit gekennzeichneten synthetischen Fakt speichern

Zeichnen Sie eine synthetische Projektkonvention auf, um die Schreibfähigkeit unter memory:write zu verifizieren. Geben Sie der Erinnerung einen spezifischen Pfad, damit nachfolgende Abfragen sie innerhalb des Projektbereichs finden können. Verwenden Sie die für Ihre Integrationsfläche korrekte Syntax.

  • Skill-Befehl: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions".
  • MCP-Tool: remember mit explizitem synthetischem Inhalt.
  • Pfadbereich: projects/demo-onboarding/conventions.
  • Erfolgssignal: Der Beleg beginnt mit 'Saved to XMemo.' zusammen mit der zugewiesenen ID und Location.
remember({
  content: "Demo project timestamps use UTC.",
  path: "projects/demo-onboarding/conventions"
})

5. Eine völlig neue Client-Sitzung öffnen

Starten Sie einen neuen Konversationsstrang oder starten Sie Ihren Client neu, um den flüchtigen Kontext im Speicher zu leeren. Dieser zustandslose Übergang stellt sicher, dass Ihr nächster Abruf die serverseitige Persistenz überprüft und nicht nur den lokalen Chatverlauf wiedergibt.

  • Aktion: Schließen oder setzen Sie die aktuelle Chat-Sitzung in Ihrem Client zurück.
  • Kontext-Reset: Der flüchtige Client-Kontext wird gelöscht, um zustandsloses Testen zu garantieren.
  • Persistenzprüfung: Nachfolgende Abfragen fragen den Remote-Speicher direkt ab.

6. Fakt mit Quellenzuordnung abrufen

Fragen Sie die gespeicherte Konvention aus der neuen Sitzung ab. Die Aktivierung ist streng definiert als das Abschließen des ersten verifizierten Speicherabrufs mit Quellenzuordnung – das Kopieren der Konfiguration oder Prüfen von Code-Snippets ist lediglich ein Zwischenschritt der Einrichtung.

  • Skill-Befehl: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1.
  • MCP-Tool: recall mit der Abfrage 'demo project timestamp format'.
  • Belegformat: Textausgabe beginnend mit '### XMemo Memory Results:', die Reference, Location, optional Created/Updated/Revision und den Inhalt anzeigt.
  • Erfolgssignal: Der erste verifizierte Abruf mit Quellenzuordnung markiert die tatsächliche Aktivierung.
recall({
  query: "demo project timestamp format",
  limit: 1
})

7. Konvention mit update_memory korrigieren

Wenn sich Projektkonventionen weiterentwickeln oder Klarstellungen erfordern, aktualisieren Sie die Erinnerung mit der exakten aktiven Memory-ID oder Referenz, die beim Abruf zurückgegeben wurde. Verwenden Sie für Skill-Clients den update-Befehl. Verwenden Sie für MCP-Clients update_memory. Eine optionale Bereinigung wird vom Benutzer über forget gesteuert.

  • Skill-Befehl: node scripts/xmemo-skill.mjs update --id "mem_01hxyz..." --content "Demo project timestamps use UTC with ISO 8601 formatting.".
  • MCP-Tool: update_memory mit gültiger memory_id.
  • Revisionsverlauf: Ersetzt die vorherige Revision und bewahrt eine unveränderliche Historie.
  • Optionale Bereinigung: Führen Sie zum Löschen 'node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm' (Skill) aus oder rufen Sie forget (MCP) auf.
  • Erfolgssignal: Der Beleg beginnt mit 'XMemo memory updated.' und zeigt Reference sowie Revision.
update_memory({
  memory_id: "mem_01hxyz...",
  content: "Demo project timestamps use UTC with ISO 8601 formatting."
})

Wiederherstellung: Zugriff auf die Zwischenablage verweigert

Wenn Ihr Browser den Zugriff auf die Zwischenablage verweigert oder Berechtigungen blockiert sind, wählen Sie den Text innerhalb des Codeblocks manuell aus und kopieren Sie ihn mit Strg+C (oder Cmd+C). Alle Codeblöcke bieten tabIndex=0 für das Scrollen und Auswählen über die Tastatur.

  • Symptom: Der Browser blockiert das automatische Kopieren in die Zwischenablage oder die Berechtigungsabfrage schlägt fehl.
  • Aktion: Klicken Sie in den Code-Container oder springen Sie mit Tab dorthin und verwenden Sie Strg+C oder Cmd+C.
  • Verifizierung: Die eingefügte Konfiguration stimmt exakt mit dem angezeigten Snippet überein.

Wiederherstellung: Authentifizierung abgelaufen oder unzureichend

Wenn Ihr Client HTTP 401 Unauthorized, HTTP 403 Forbidden oder SetupRequiredMCPError empfängt, ist Ihr Authentifizierungs-Token abgelaufen oder verfügt nicht über die erforderlichen Geltungsbereiche.

  • Symptom: HTTP 401, HTTP 403 oder SetupRequiredMCPError beim Tool-Aufruf.
  • Aktion: Authentifizieren Sie sich erneut über OAuth oder setzen Sie XMEMO_KEY in Ihrer lokalen Umgebung.
  • Verifizierung: Bestätigen Sie, dass das Token sowohl memory:read als auch memory:write gewährt.

Wiederherstellung: Tools im Client nicht sichtbar

Wenn XMemo-Tools nach der Konfiguration nicht in Ihrer Client-Palette erscheinen, enthält die Konfigurationsdatei möglicherweise Syntaxfehler oder der MCP-Verbindungsprozess muss neu gestartet werden.

  • Symptom: Der Client zeigt 0 Tools an oder erkennt den XMemo MCP-Server nicht.
  • Aktion: Prüfen Sie die Client-Entwicklerprotokolle, validieren Sie die JSON-Syntax und starten Sie den Client neu.
  • Verifizierung: Client-Protokolle zeigen eine erfolgreiche MCP-Initialisierung und Tool-Erkennung.

Wiederherstellung: Leere Abrufergebnisse

Wenn der Abruf keine passenden Erinnerungen zurückgibt ('No matching memories found' oder 'No strong memory match'), stellen Sie sicher, dass der Schreibvorgang in Schritt 4 erfolgreich abgeschlossen wurde, und überprüfen Sie Ihren Suchbegriff.

  • Symptom: recall gibt eine Textnachricht zurück, die angibt, dass keine passenden Erinnerungen gefunden wurden.
  • Aktion: Überprüfen Sie die Abfrageschlüsselwörter ('timestamp', 'UTC') und prüfen Sie den Pfadbereich.
  • Verifizierung: Bestätigen Sie vor dem Abruf, dass remember einen Beleg zurückgegeben hat, der mit 'Saved to XMemo' beginnt.

Wiederherstellung: Unbekannte memory ID bei Aktualisierung

Wenn update_memory Ihren Aufruf ablehnt, weil die memory_id unbekannt oder ungültig ist, raten Sie keine Bezeichner.

  • Symptom: update_memory gibt einen Fehler zurück, der besagt, dass die memory_id nicht gefunden wurde.
  • Aktion: Rufen Sie zuerst recall auf, um die aktive Speicher-Referenz abzurufen, und übergeben Sie diese als memory_id.
  • Verifizierung: Übergeben Sie die aktive Speicher-Referenz aus recall an update_memory.

Wiederherstellung: Falsches Installationsziel

Wenn das Installationsprogramm Skripte direkt im Stammverzeichnis der Skills Ihres Agenten statt in einem isolierten Skill-Unterverzeichnis gespeichert hat, kann der Agent scripts/xmemo-skill.mjs nicht finden oder lädt rohe Installationsdateien.

  • Symptom: Fehler beim Auffinden von scripts/xmemo-skill.mjs oder Dateien wurden direkt in das Stammverzeichnis der Skills extrahiert.
  • Aktion: Setzen Sie XMEMO_SKILL_DIR explizit auf Ihr Skills-Verzeichnis plus /xmemo-memory (z. B. export XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory").
  • Verifizierung: SKILL.md und scripts/xmemo-skill.mjs befinden sich direkt im Ordner xmemo-memory.

Wiederherstellung: Fehlende Node 22.22.0-Laufzeit

Der eigenständige Skill erfordert Node.js >= 22.22.0. Wenn node fehlt oder eine ältere Version aktiv ist, schlagen doctor und Skill-Operationen fehl.

  • Symptom: 'command not found: node', oder Laufzeitfehler beim Start, oder node -v meldet eine Version unter 22.22.0.
  • Aktion: Installieren oder wechseln Sie mit nvm (nvm install 22.22.0 && nvm use 22.22.0) oder dem Paketmanager Ihres Betriebssystems zu Node.js 22.22.0 oder höher.
  • Verifizierung: Führen Sie 'node -v' aus und bestätigen Sie, dass die Ausgabe v22.22.0 oder höher ist.

Wiederherstellung: Skill-Neuladen erforderlich

Wenn der Skill installiert ist und doctor bestanden wurde, Ihr Agent jedoch in seiner aktiven Sitzung keine XMemo-Tools oder -Operationen auflistet, muss der speicherinterne Skills-Cache des Agenten neu geladen werden.

  • Symptom: Der Agent meldet nach der Installation keine Kenntnis von XMemo-Skills.
  • Aktion: Starten Sie die Agentensitzung neu, um die im Arbeitsspeicher befindlichen Skills neu zu laden.
  • Verifizierung: Fragen Sie den Agenten 'what skills are available?' und prüfen Sie, ob xmemo-memory aufgeführt ist.

Wiederherstellung: Unterbrochene Anmeldung

Wenn die Geräteanmeldung unterbrochen wurde, das Zeitlimit abgelaufen ist oder das Fenster vor der Eingabe des Verifizierungscodes geschlossen wurde, werden keine Anmeldedaten auf die Festplatte geschrieben.

  • Symptom: Der Browser wurde vor der Genehmigung geschlossen, der Einmalcode ist abgelaufen oder 'auth status --verify' meldet auth_valid: false.
  • Aktion: Wenn Sie kein Secret-Store XMEMO_KEY oder verwaltete Anmeldedaten verwenden, führen Sie 'node scripts/xmemo-skill.mjs login --allow-plaintext' erneut aus (wodurch die Anmeldedaten unverschlüsselt auf diesem Computer gespeichert werden), öffnen Sie die angezeigte URL und geben Sie den Code vor Ablauf ein.
  • Verifizierung: Führen Sie 'node scripts/xmemo-skill.mjs auth status --verify' aus und bestätigen Sie 'status: ok' mit 'auth_valid: true'.

Schnellstart für gehostetes XMemo

Beginnen Sie mit dem verwalteten XMemo-Dienst und einem dieser Verbindungspfade. Selbstgehostete, Docker-, Supabase- und Python-Paket-Einrichtungen sind Entwicklerreferenzen und nicht der primäre Weg für Nutzer des gehosteten Dienstes.

Ihren Agenten fragen

Fügen Sie dies in einen Agenten ein, dem Sie vertrauen, dass er seine üblichen Sicherheitsprüfungen durchführt.

Installieren Sie den eigenständigen XMemo Skill in Ihr Skills-Verzeichnis: Führen Sie das Installationsprogramm von https://xmemo.dev/skill/install (unter Windows https://xmemo.dev/skill/install.ps1) aus, wobei XMEMO_SKILL_DIR auf Ihr Skills-Verzeichnis plus /xmemo-memory gesetzt ist. Führen Sie den ausgegebenen Befehl doctor aus, um die Installation zu überprüfen, laden Sie dann Ihre Skills neu und folgen Sie den Erstausführungsschritten des Skills. Befolgen Sie Ihre normalen Sicherheitsüberprüfungen und verwenden Sie keine erhöhten Rechte.

OAuth-Clients

Verwenden Sie diesen Pfad für ChatGPT, OpenAI-App-Reviews, VS Code und GitHub Copilot, wenn der Host OAuth unterstützt. Fügen Sie die gehostete MCP-URL hinzu, genehmigen Sie memory:read und memory:write und fügen Sie XMEMO_KEY nicht in die Client-Konfiguration ein.

MCP URL: https://xmemo.dev/mcp
Scopes: memory:read memory:write

Direktes MCP mit XMEMO_KEY

Verwenden Sie diesen Pfad nur für Clients oder Headless-Runner, die OAuth nicht abschließen können. Speichern Sie XMEMO_KEY in der lokalen Umgebung oder im Secret-Store, behalten Sie die gehostete MCP-URL in der Konfiguration und fügen Sie das echte Token niemals in öffentliche Dokumente oder Chats ein.

MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID

Kontosteuerung

Nutzen Sie nach der ersten Verbindung den Kontozugang, um zu überprüfen, was gespeichert wurde, die Agentenzuordnung einzusehen und Lösch-/Export- oder Support-Pfade zu finden, bevor Sie ein Pilotprojekt ausweiten.

Account entry: https://xmemo.dev/login

Quelle: Gehosteter Schnellstart