Wissensbasen

Architektur von Basis, Element und Revision

Eine Wissensbasis ist eine sammlungsorientierte Struktur von Referenzdokumenten, Spezifikationen und Runbooks im Eigentümer- oder Team-Geltungsbereich. Sie organisiert technisches Wissen in drei eindeutigen hierarchischen Entitäten:

• Knowledge Base (Wissensbasis): Der Container der obersten Ebene (z. B. "Engineering Runbooks"). Eine Basis besitzt einen Namen, eine Beschreibung, einen Status (active oder archived) und eine Bereichszugehörigkeit (Personal oder Team).
• Knowledge Item (Wissenselement): Ein einzelnes Dokument oder eine Richtlinie innerhalb einer Basis (z. B. "Deployment Guidelines"). Ein Element besitzt einen Titel, einen Locator, einen Status (draft, published oder archived), einen Quelltyp (user_created oder file) und einen current_revision_id-Zeiger.
• Knowledge Revision (Wissensrevision): Ein unveränderlicher Snapshot, der kanonischen Inhalt, die Revisionsnummer, das Inhaltsformat (z. B. Markdown), den Inhalts-Hash, Quellmetadaten und die Herkunft (Provenance) enthält.
• Veröffentlichungslebenszyklus: Ein Element beginnt im Status draft. Nach der Veröffentlichung (published) wird die aktuelle Revision für Agenten auffindbar. Nachfolgende Bearbeitungen erstellen unveränderliche neue Revisionen und rücken den aktuellen Zeiger vor, ohne historische Revisionen zu verändern.

Veröffentlichungsgrenzen und Agenten-Sichtbarkeit

Wissensbasen erzwingen strikte Veröffentlichungsgrenzen zwischen menschlicher Inhaltserstellung und autonomem Agentenabruf. Aufrufer wählen zwischen Suchabfrage (query search) und adressiertem Lesen (addressed read). Suchabfragen schützen die Aktualität, indem sie ausschließlich veröffentlichte Elemente bei ihrer aktuell aktiven Revision auswerten:

• Nur aktive Basen: Archivierte Basen sind von der Auffindung durch Agenten ausgeschlossen. Die Archivierung setzt den Abruf für alle enthaltenen Elemente aus, ohne Inhalte zu zerstören.
• Nur veröffentlichte Elemente: Entwurfselemente (draft) bleiben bis zur expliziten Veröffentlichung für den Autor und die Team-Editoren privat. Agenten können Entwurfselemente in einer Suchabfrage weder entdecken noch zitieren.
• Standardmäßig aktuelle Revision: Eine Suchabfrage wertet ausschließlich die Revision aus, auf die current_revision_id verweist. Ersetzte historische Revisionen können nicht als Suchergebnis erscheinen.
• Adressiertes Lesen: Ein adressiertes Lesen kann eine exakte historische Revision untersuchen, indem knowledge_revision_id zusammen mit knowledge_item_id angegeben wird, wodurch reproduzierbare Zitate erhalten bleiben.

query search       -> active base + published item + current_revision_id
addressed (no pin) -> published item's current revision
addressed (pinned) -> exact immutable revision (e.g. knowledge:<item-id>@<revision-id>)

Abrufmodi: Hybrid, RRF, Semantic und Lexical

Die Suchlaufzeit unterstützt vier Abrufmodi, um lexikalische Präzision und semantisches Verständnis auszubalancieren:

• hybrid (Standard): Lineare Kombination aus normalisierten lexikalischen und semantischen Bewertungen unter Verwendung des Parameters alpha (Standard 0.5). Ein Wert von alpha nahe 1 bevorzugt exakte lexikalische Übereinstimmungen, während alpha nahe 0 konzeptionelle semantische Ähnlichkeit bevorzugt. Fällt auf lexical zurück, wenn Vektorbewertungen nicht verfügbar sind.
• rrf (Reciprocal Rank Fusion): Verschmilzt unabhängige lexikalische und semantische Ranglisten unter Verwendung der Rangkonstante k (Standard 60) und gewährleistet eine ausgewogene Reihenfolge ohne erforderliche Bewertungskalibrierung.
• semantic: Vektorähnlichkeits-Ranking basierend auf Einbettungsdarstellungen, mit Fallback auf lexikalische Übereinstimmung, wenn Einbettungen nicht konfiguriert sind.
• lexical: Normalisierter Token- und Phrasenabgleich, optimiert für exakte Symbole, Funktionsnamen, Fehlercodes und Konfigurationsschlüssel.

Unterstützte Dateitypen und Upload-Pipelines

Wissenselemente können direkt in Markdown verfasst oder über zwei unterschiedliche Erfassungsmechanismen aus lokalen Dateien importiert werden:

• Vom Browser gelesene Text- und Codedateien: Nur-Text- und Codedateien (.md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml, .toml) werden direkt im Browser gelesen und als kanonischer Markdown-Inhalt gespeichert.
• Dokumentextraktions-Pipeline: Formatierte Dokumente (.pdf, .docx, .pptx, .xlsx) werden über die Documents API hochgeladen, durch Textextraktions-Worker verarbeitet und bei erfolgreicher Extraktion als Wissenselemente gesnapshottet.
• Dateigrenzen: Erfassungsgrenzen gelten über Client- und Serverumgebungen hinweg. Für eine zuverlässige Verarbeitung organisieren Sie Wissen in fokussierten, modularen Dokumenten anstatt in monolithischen Dateibergen.

Agenten-Zugriffsoberflächen und Client-Profile

Autorisierte Agenten greifen über dedizierte MCP-Tools und eigenständige Skill-Befehle auf Wissen zu:

• MCP search_knowledge: Dediziertes schreibgeschütztes Suchwerkzeug, das den Token-Geltungsbereich knowledge:read erfordert. Speziell in den Client-Profilen cursor-plugin und ordinary-full offengelegt (config/mcp-documentation-contract.json); nicht in den Profilen chatgpt-public oder generic-public verfügbar.
• MCP recall_context: Schließt automatisch relevante Wissenselemente neben episodischen Erinnerungen ein, wenn Knowledge für Ihr Konto aktiviert ist und das Token knowledge:read enthält.
• Eigenständiger XMemo Skill: Führt recall-context mit expliziter Wissenseinbindung aus: node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true.
• Geltungsbereichserzwingung: Nicht jeder Recall fragt automatisch Knowledge ab; der Abruf erfolgt nur, wenn konfiguriert, durch den Token-Geltungsbereich zulässig und vom aktiven Client-Profil unterstützt.
• REST-Begleitendpunkt: Der authentifizierte Begleitendpunkt POST /api/v1/knowledge/search bietet direkten programmatischen Zugriff auf die Wissenssuche für Backend-Dienste und benutzerdefinierte Werkzeuge.

{
  "type": "knowledge_search",
  "results": [
    {
      "knowledge_item_id": "item_runbook_deploy",
      "knowledge_revision_id": "rev_v2_deploy_runbook",
      "title": "Production Deployment Runbook",
      "content": "Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.",
      "reference": "knowledge:item_runbook_deploy@rev_v2_deploy_runbook",
      "score": 3.84
    }
  ]
}

Teamrollen, Bereiche und Lebenszyklusoperationen

Wissensbasen unterstützen persönliche und kollaborative Arbeitsbereiche mit rollenbasierter Zugriffskontrolle:

• Rollenberechtigungen: Owner und Admin verfügen über Rechte für base:admin und item:write (Erstellen, Archivieren, Aktualisieren und Löschen von Basen und Elementen). Member verfügt über Rechte für item:write (Erstellen, Bearbeiten und Veröffentlichen von Elementen, kann jedoch keine Basen löschen oder archivieren). Viewer verfügt nur über Leserechte.
• Bereichsgrenzen: Der persönliche Bereich (/me#knowledge) ist für den Eigentümer privat. Der Team-Bereich (?space=<team_id>#knowledge) teilt veröffentlichte Dokumentation mit authentifizierten Teammitgliedern.
• Archivierung gegenüber dauerhafter Löschung: Das Archivieren einer Basis setzt den Status auf archived und schließt alle Elemente sofort von Agentenabfragen aus, ermöglicht jedoch eine vollständige Wiederherstellung. Die dauerhafte Löschung zerstört die Basis und alle zugehörigen Revisionen unwiderruflich physisch.

Unterschied zum Projektspeicher

Wissensbasen stellen kuratierte Referenzdokumentation bereit, die unter anderen Garantien als das dialogbasierte Projektgedächtnis arbeitet:

• Wissensbasiselemente: Kuratierte, versionierte Referenzdokumente (wie Runbooks, Entwurfsdokumente und Programmierstandards) mit Multi-Revisionshistorie und exakten Zitierverweisen (knowledge:<item-id>@<revision-id>).
• Projektbezogener Knowledge-/Working-Speicher: Dialogbasierte Gedächtnisdatensätze, die innerhalb eines Projektarbeitsbereichs als dauerhafter Kontext (knowledge) gegenüber vorübergehendem Aufgabenstatus (working memory) kategorisiert sind.
• Unabhängigkeit: Das Entfernen eines Gedächtnisdatensatzes oder das Aufheben der Verknüpfung eines Dokuments mit einem Projekt ändert, archiviert oder löscht die zugrunde liegenden Wissensbasiselemente nicht.

Verfügbarkeit und Laufzeitaktivierung

Die Wissensbasis wird als Kernfunktion dokumentiert, nicht als Preview. Die Verfügbarkeit ist aktiv, wenn Knowledge für Ihr Konto aktiviert ist. Wenn die Backend-Wissenslaufzeit nicht konfiguriert oder deaktiviert ist, geben Anforderungen HTTP 503 mit dem Code knowledge_runtime_disabled zurück. Katalogplanbezeichnungen (wie Zuteilungen der Plus-Stufe) stellen Plankontingente dar und keine Mechanismen zur Laufzeiterzwingung; keine API-Routen erzwingen Planstufen.