Leitfaden für Wissensbasen

Ziel des Benutzers

Verwalten Sie strukturierte Wissensbasen in Ihrem persönlichen oder Team-Arbeitsbereich, erfassen Sie Markdown- und formatierte Dokumente, veröffentlichen Sie verifizierte unveränderliche Revisionen und konfigurieren Sie autonome Agenten so, dass sie zitierte Fakten mit Quellenangabe abrufen.

Verfügbarkeit und Voraussetzungen

Die Erstellung und Prüfung von Wissensbasen ist in der Webkonsole unter https://xmemo.dev/me#knowledge (persönlicher Arbeitsbereich) oder https://xmemo.dev/me?space=<team_id>#knowledge (Team-Arbeitsbereich) verfügbar, sofern Knowledge für Ihr Konto aktiviert ist. Überprüfen Sie vor Beginn die folgenden Voraussetzungen:

• Authentifizierungsanforderung: Eine aktive Benutzersitzung ist erforderlich. Nicht authentifizierte Zugriffe werden auf /login (die Anmeldeseite) umgeleitet.
• Token-Bereiche: Der programmgesteuerte Zugriff erfordert knowledge:read für Suchvorgänge und gezielte Lesezugriffe sowie knowledge:write zum Erstellen oder Bearbeiten von Einträgen.
• Unterstützte Dateiformate: Der Text-/Code-Betrachter im Browser unterstützt .md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml und .toml. Die Dokumentextraktion unterstützt .pdf, .docx, .pptx und .xlsx.
• Drag-and-Drop-Oberfläche: Die Konsole zeigt "Drag & drop files here" mit dem Hinweistext "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)".

1. Wissensbasis in der Webkonsole erstellen

Navigieren Sie in Ihrem Browser zu https://xmemo.dev/me#knowledge. Klicken Sie auf "Create Knowledge Base", um den Erstellungsdialog zu öffnen. Geben Sie "Engineering Runbooks" bei Name und "Operational runbooks and deployment procedures." bei Description ein. Bestätigen Sie die Erstellung, um die aktive Basis zu initialisieren.

# Access personal knowledge workspace
https://xmemo.dev/me#knowledge

# Access team knowledge workspace with explicit space parameter
https://xmemo.dev/me?space=<team_id>#knowledge

2. Synthetischen Wissenseintrag hinzufügen und veröffentlichen

Öffnen Sie die neu erstellte Basis "Engineering Runbooks" und klicken Sie auf "Create Knowledge item", um einen Eintrag aus Markdown oder einer lokalen Datei zu erstellen. Geben Sie den Titel "Deployment Guidelines" ein und fügen Sie die anfänglichen synthetischen Anweisungen ein. Der Eintrag startet mit dem Status "draft":

## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.

3. Entwurfseintrag für den Agentenabruf veröffentlichen

Im Status "draft" bleibt der Eintrag ausschließlich für menschliche Bearbeiter sichtbar. Um ihn für Agenten auffindbar zu machen, klicken Sie auf "Publish". Die Konsole zeigt den Hinweis "Published content becomes eligible for authorized Knowledge search.". Nach der Bestätigung wechselt der Eintrag in den Status "published", wodurch Revision 1 als aktuelle durchsuchbare Revision festgelegt wird.

• Datenschutz für Entwürfe: Entwurfseinträge sind von der Auffindbarkeit und Abfragesuche durch Agenten ausgeschlossen.
• Aktion "Veröffentlichen": Das Veröffentlichen aktualisiert den Status des Eintrags auf "published" und setzt current_revision_id auf Revision 1.
• Unveränderliche Revision: Der kanonische Inhalt, der Hash und die Metadaten von Revision 1 bleiben unveränderlich erhalten.

4. Wissen mit Agentenzitaten abrufen

Autorisierte Agenten in Client-Umgebungen, die search_knowledge bereitstellen (wie cursor-plugin oder ordinary-full), können das veröffentlichte Runbook abfragen. Das Werkzeug liefert gewichtete Auszüge mit expliziten Zitationsreferenzzeigern zurück:

# Query knowledge via standalone Skill CLI
node scripts/xmemo-skill.mjs recall-context --query "production deployments" --include_knowledge true

5. Inhalt aktualisieren und eine neue unveränderliche Revision veröffentlichen

Wenn sich technische Abläufe ändern, öffnen Sie "Deployment Guidelines" und klicken Sie auf "Edit Knowledge item". Aktualisieren Sie den Inhalt, um die neuen betrieblichen Anforderungen widerzuspiegeln. Klicken Sie auf "Save new revision". Die Konsole zeigt an: "Saving content creates an immutable new revision. Metadata changes do not create a revision.":

## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, verified canary health, and automated smoke verification.

Beobachtbares Ergebnis

Überprüfen Sie den veröffentlichten Eintrag und seine Revisionsherkunft in der Webkonsole und über die Agentensuche:

• Konsolen-Badge: Die Karte des Eintrags zeigt das Status-Badge "Published" und verweist auf die aktuell aktive Revision.
• Revisionsverlauf: Das Öffnen von "Revision history" zeigt Revision 2 als aktuelle und Revision 1 als historische Version mit Zeitstempeln und Autorenzuordnung.
• Ergebnis der Agentensuche: Abfragesuchen werten ausschließlich Revision 2 aus. Die historische Revision 1 bleibt über gezielte Lesezugriffe unter Angabe der genauen knowledge_revision_id zugänglich.

Worauf Agenten zugreifen können

Wissensbasen setzen strenge Zugriffs- und Sichtbarkeitsgrenzen für die Agentenintegration durch:

• Nur veröffentlichte Einträge: Agenten können nicht auf Entwürfe zugreifen. Abfragesuchen werten ausschließlich veröffentlichte Einträge in aktiven Basen aus.
• Grenze der aktuellen Revision: Die Abfragesuche löst automatisch auf current_revision_id auf. Ersetzte Revisionen können nicht in den Suchergebnissen erscheinen.
• Profilverfügbarkeit: Das schreibgeschützte MCP-Werkzeug search_knowledge ist ausschließlich in den Client-Profilen cursor-plugin und ordinary-full verfügbar (config/mcp-documentation-contract.json). Andere Client-Profile verwenden recall_context, das Knowledge bei Aktivierung und Autorisierung automatisch einbezieht.
• Recall-Verhalten: MCP recall_context schließt Knowledge automatisch ein, wenn Knowledge für Ihr Konto aktiviert ist und das Token knowledge:read enthält. Nicht jedes recall durchsucht Knowledge.

Freigabe- und Speichergrenzen

Wissensbasen wahren eine strikte Bereichsisolation und administrative Rollengrenzen:

• Persönlicher Bereich im Vergleich zum Team-Bereich: Persönliche Basen (/me#knowledge) sind privat für das Konto. Team-Basen (?space=<team_id>#knowledge) erzwingen den rollenbasierten Zugriff des Teams (routes/knowledge.py:129-134).
• Rollenberechtigungen: Owner und Admin verfügen über die Rechte base:admin und item:write (Erstellen, Archivieren, Aktualisieren und Löschen von Basen und Einträgen). Member besitzt item:write-Rechte (Erstellen, Bearbeiten und Veröffentlichen von Einträgen). Viewer besitzt ausschließlich Leserechte.
• Archivierung im Vergleich zum endgültigen Löschen: Durch das Archivieren ("Are you sure you want to archive knowledge base '<name>'? Archived bases will no longer be retrieved by agents.") wird der Abruf ohne Datenverlust ausgesetzt. Beim endgültigen Löschen ("Are you sure you want to permanently delete knowledge base '<name>' and all its items? This action cannot be undone.") werden die Daten physisch entfernt.
• Unabhängigkeit des Projektspeichers: Wissensbasen arbeiten unabhängig von den Arbeitsspeicher- und Wissensspeicher-Partitionen von Projekten. Das Aufheben der Verknüpfung einer Erinnerung mit einem Projekt berührt keine Dokumente der Wissensbasis.

Fehlerbehebung

Beheben Sie häufige Probleme beim Zugriff auf Wissensbasen und bei der Extraktion mithilfe der folgenden Diagnoseschritte:

• Dokumentextraktion läuft: Warten Sie beim Hochladen von Dokumenten im Format .pdf, .docx, .pptx oder .xlsx, solange die Meldung angezeigt wird: "Extraction is still in progress. Try again when it succeeds.".
• Dokumentextraktion fehlgeschlagen: Wenn die Verarbeitung fehlschlägt, zeigt die Konsole an: "Extraction failed. Retry the Document from its existing Document surface first.". Überprüfen Sie die Dateiintegrität oder laden Sie einfachen Markdown-Text hoch.
• Eintrag in der Agentenabfrage nicht zurückgegeben: Vergewissern Sie sich, dass der Status des Eintrags "Published" lautet (nicht "draft"), dass die Basis aktiv ist (nicht archiviert) und dass das Client-Token den Bereich knowledge:read enthält.
• Konflikt durch gleichzeitige Aktualisierung: Wenn ein anderer Benutzer oder Agent den Eintrag aktualisiert hat, während Ihre Bearbeitung geöffnet war, zeigt die Konsole an: "This Knowledge item changed elsewhere. Refresh it and try again.". Aktualisieren Sie die Seite und wenden Sie die Änderungen erneut an.
• Auswahl des Suchmodus: Wenn exakte Runbook-Symbole oder Konfigurationsschlüssel bei der hybriden Suche nicht gefunden werden, wechseln Sie in den lexikalischen Modus (mode="lexical") für einen exakten Token-Abgleich.

Verwandte Referenzen

Informieren Sie sich weiter über Konzepte von Wissensbasen, zugehörige Werkzeuge und die Arbeitsbereichsverwaltung:

• Konzepte: Wissensbasen (/docs/concepts/knowledge-bases) — Architekturmodell, Revisions-DAG und Abrufmodi.
• Werkzeuge: search_knowledge (/docs/tools/search-knowledge) — Werkzeugreferenz für gezielte Lesezugriffe und Suchparameter.
• Werkzeuge: recall_context (/docs/tools/recall-context) — Kontextbündelungswerkzeug mit automatischem Knowledge-Abruf.
• Leitfäden: Memory Console (/docs/guides/memory-console) — Vollständiger Navigationsleitfaden für die Webkonsole.
• Konzepte: Herkunft und Zuordnung (/docs/concepts/provenance-attribution) — Zitationsumschläge und Autorenzuordnung.