Frei Chat Index Bot

Frei Chat Index Bot – Hilfe und Befehlsreferenz

Kurz erklärt: Der Frei Chat Index Bot macht freigegebene Matrix-Räume durchsuchbar. Er kombiniert Volltextsuche, tolerante Tippfehlersuche und semantische Ähnlichkeit. Dabei zeigt er ausschließlich Inhalte, die die anfragende Person nach aktueller Mitgliedschaft und historischer Sichtbarkeit sehen darf.

Vor der Veröffentlichung: Ersetze den Platzhalter [BOT-MATRIX-ID] auf dieser Seite durch die Matrix-ID des produktiven Bot-Kontos, zum Beispiel @frei-chat-index:example.org.

Bot-Konto: [BOT-MATRIX-ID]
Befehlspräfix: !fcib
Unterstützte Ausgabesprachen: Deutsch und Englisch
Geeignet für: unverschlüsselte und Ende-zu-Ende-verschlüsselte Matrix-Räume

Inhalt

Schnellstart
Grundlagen und Rollen
Suchen und Suchfilter
Zeitzone und Sprache
Statistiken
Persönlicher Datenschutz
Raumindex verwalten
Unterhaltungen verwalten
Keyword-Sperren
Globale Administration
Datenverarbeitung, Sicherheit und Grenzen
Fehlerbehebung
Kurzreferenz

1. Schnellstart

Im aktuellen Raum suchen

!fcib search Projekt Phoenix

Der Bot durchsucht ausschließlich den Raum, in dem der Befehl gesendet wurde.

Nach einer exakten Wortgruppe suchen

!fcib search "Projekt Phoenix"

Anführungszeichen kennzeichnen eine Phrase. Weitere Suchwörter außerhalb der Anführungszeichen fließen zusätzlich in die Volltext-, Tippfehler- und semantische Suche ein.

Auf eine Person und einen Zeitraum begrenzen

!fcib search -u @alice:example.org after:2026-01-01 before:2026-06-30 --limit 10 Migration

Nachrichten vor und nach einem Treffer anzeigen

!fcib search -C 2 "Projekt Phoenix"

-C 2 zeigt bis zu zwei sichtbare indexierte Nachrichten vor und nach jedem Treffer.

Alle aktuell gemeinsamen Räume durchsuchen

!fcib search-all Migration

Dieser Befehl funktioniert ausschließlich in einem sicher verifizierten Zwei-Personen-Direktchat mit dem Bot.

Verfügbare Hilfe anzeigen

!fcib help

Die eingebaute Hilfe zeigt nur Befehle, die die anfragende Person im aktuellen Raum mit ihren live geprüften Rechten verwenden darf. Einzelne Themen lassen sich beispielsweise mit !fcib help search, !fcib help privacy oder !fcib help index aufrufen.

2. Grundlagen und Rollen

Einladung und Aktivierung

Lade [BOT-MATRIX-ID] in den gewünschten Matrix-Raum ein.
Der Bot prüft die Einladungsrichtlinie. Einladungen können je nach Server-, Raum- und Benutzerfreigabe angenommen oder abgelehnt werden.
Standardmäßig wartet ein neu betretenes Zimmer auf ein ausdrückliches Opt-in.
Der gespeicherte Bot-Raumverwalter aktiviert die Indexierung mit !fcib index enable.
Der Bot veröffentlicht beim Aktivieren einen sichtbaren Datenschutzhinweis. Je nach Konfiguration wird anschließend ein begrenztes Backfill vorhandener, für den Bot sichtbarer Nachrichten gestartet.

Wichtig: Die Einladung allein bedeutet nicht zwingend, dass bereits indexiert wird. Mit !fcib index status lässt sich der aktuelle Zustand prüfen.

Befehlsformat

Alle aktiven Befehle beginnen mit !fcib. Direkte Altformen wie !search, !index oder !help werden nicht ausgeführt. Sie werden auch nicht als normaler Nachrichteninhalt indexiert.

!fcib <Unterbefehl> [Optionen] [Argumente]

Unterbefehle sind nicht von Groß-/Kleinschreibung abhängig. Werte mit Leerzeichen müssen in Anführungszeichen stehen. Matrix-Benutzer-IDs, Raum-IDs und Aliasse müssen vollständig angegeben werden.

Rollen und Berechtigungen

Rolle	Voraussetzung	Typische Rechte
Raummitglied	Aktuell beigetreten und für den Raum autorisiert	Im aktuellen Raum suchen, öffentliche Raumstatistik lesen, Zeitzone verwalten, sichtbare Hilfe abrufen
Matrix-Raumadmin	Konfiguriertes Matrix-Power-Level, standardmäßig mindestens 50	Eine freie oder verwaiste Bot-Raumverwalterrolle mit `index admin claim` übernehmen
Bot-Raumverwalter	Gespeicherte Bot-Rolle und weiterhin ausreichendes live geprüftes Matrix-Power-Level	Index aktivieren, pausieren, fortsetzen, deaktivieren oder löschen; Raum-Keyword-Regeln und Unterhaltungen verwalten
Globaler Bot-Admin	In der Deployment-Konfiguration oder persistent durch einen Root-Admin berechtigt	Globale Datenschutz-, Server-, Konfigurations-, Statistik- und Administrationsfunktionen; globale Befehle nur im verifizierten Bot-DM
Bootstrap-/Root-Admin	Fest in `FREI_CHAT_GLOBAL_ADMINS` konfiguriert	Zusätzliche globale Admins und begrenzte Audit-Prüfer verwalten
Audit-Prüfer	Zeitlich und fachlich begrenzter Audit-Grant	Nur freigegebene Ausschnitte des Befehls-Audits lesen

Was ist ein „verifizierter Bot-DM“?

Ein verifizierter Bot-DM ist ein Raum mit aktuell genau zwei aktiven Mitgliedern: dem Bot und der anfragenden Person. Sobald der Bot jemals einen dritten Teilnehmer in diesem Raum beobachtet hat, wird der Raum für privilegierte DM-Funktionen konservativ ausgeschlossen. Abhängig von der Installation kann zusätzlich ein Matrix-m.direct-Nachweis verlangt werden.

Antworten und Threads

Ein Befehl innerhalb eines Threads wird im selben Thread beantwortet.
In Räumen mit mehr als zwei aktuell beigetretenen Mitgliedern startet ein nicht verthreadeter Befehl einen neuen Antwort-Thread.
Im Zwei-Personen-DM antwortet der Bot normal im Raum.
Antworten werden als sicherer Klartext ausgegeben. Inhalte aus Nachrichten werden nicht als HTML, Code, SQL, URL oder Anweisung ausgeführt.

3. Suchen und Suchfilter

Suchbefehle

Befehl	Bereich	Voraussetzung
`!fcib search <Anfrage>`	Aktueller Raum	Aktuelle Berechtigung für den Raum
`!fcib find <Anfrage>`	Aktueller Raum	Alias für `search`
`!fcib suche <Anfrage>`	Aktueller Raum	Standardmäßiger deutscher Alias; kann installationsabhängig anders konfiguriert sein
`!fcib search -r <Raum-ID\|Raumalias> <Anfrage>`	Genau ein angegebener Raum	Aus einem verifizierten Bot-DM; anfragende Person muss den Zielraum aktuell durchsuchen dürfen
`!fcib search-all <Anfrage>`	Alle aktuell gemeinsamen, aktiv indexierten Räume	Ausschließlich im verifizierten Bot-DM

Für einen Zielraum wird ausschließlich die Form -r <Raum-ID|Raumalias> akzeptiert. --room, -r=… oder eine unmarkierte Raum-ID sind absichtlich nicht zulässig.

Unterstützte Raum-IDs

Klassisch: !localpart:server.example
Matrix-Raumversion 12: ! gefolgt von 43 Base64url-Zeichen ohne Serverteil
Raumalias: #alias:server.example

Suchfilter

Filter	Bedeutung	Beispiel
`-u @user:server`	Nur Nachrichten dieser Person	`-u @alice:example.org`
`--user @user:server`	Langform von `-u`	`--user @alice:example.org`
`--user=@user:server`	Langform mit Gleichheitszeichen	`--user=@alice:example.org`
`from:@user:server`	Kompakte Absenderform	`from:@alice:example.org`
`after:YYYY-MM-DD`	Ab Beginn dieses lokalen Kalendertags	`after:2026-01-01`
`before:YYYY-MM-DD`	Bis zum Ende dieses lokalen Kalendertags	`before:2026-06-30`
`--limit N` oder `--limit=N`	Maximale Trefferzahl. Standardmäßig 5, im Auslieferungszustand höchstens 20; die Installation kann diese Werte ändern.	`--limit 10`
`-A N` oder `-AN`	Bis zu N sichtbare indexierte Nachrichten nach jedem Treffer	`-A 2` oder `-A2`
`-B N` oder `-BN`	Bis zu N sichtbare indexierte Nachrichten vor jedem Treffer	`-B 2` oder `-B2`
`-C N` oder `-CN`	Bis zu N Nachrichten auf beiden Seiten	`-C 2` oder `-C2`
`"mehrere Wörter"`	Verlangt die angegebene Phrase	`"Projekt Phoenix"`

Standardmäßig sind höchstens fünf Kontextnachrichten je Seite und insgesamt höchstens 100 Kontextnachrichten pro Ausgabe erlaubt. Die konkreten Grenzwerte können pro Installation oder Raum abweichen.

Beispiele

!fcib search Migration
!fcib search "Projekt Phoenix"
!fcib search -u @alice:example.org -C 2 "Projekt Phoenix"
!fcib search after:2026-01-01 before:2026-06-01 --limit 10 Migration
!fcib search -r #projekt:example.org Migration
!fcib search -r !projekt:example.org --limit=8 "Release Planung"
!fcib search-all from:@alice:example.org after:2026-01-01 Datenschutz

Wie Suchergebnisse entstehen

Der Bot kombiniert drei Verfahren:

Volltextsuche für Wörter und Phrasen,
Trigramm-/Tippfehlersuche für ähnlich geschriebene Begriffe,
semantische Suche über mehrsprachige Embeddings für inhaltlich ähnliche Formulierungen.

Die drei Ranglisten werden zusammengeführt. Semantische Kandidaten unterhalb des konfigurierten Ähnlichkeitsschwellwerts werden verworfen. Passende automatisch erkannte Unterhaltungen können ohne zusätzlichen Suchparameter als Vorschläge erscheinen.

Sichtbarkeit der Treffer

Die aktuelle Matrix-Mitgliedschaft wird vor und nach der Suche erneut geprüft.
Die historische Sichtbarkeit wird für den Zeitpunkt jeder Nachricht ausgewertet.
Bei bearbeiteten Nachrichten müssen Original und gültige Bearbeitung sichtbar sein.
Bei unvollständiger historischer Evidenz wird konservativ weniger angezeigt.
Treffer, Kontext und Unterhaltungsvorschläge unterliegen denselben Zugriffsprüfungen.
Jeder Treffer enthält einen sicheren Ausschnitt und einen Matrix-Permalink.

Grenzen der Suchausgabe

--limit begrenzt Treffer; es gibt derzeit keinen Cursor zum Weiterblättern durch weitere Suchtreffer.
Kontext meint benachbarte indexierte Nachrichten, nicht zwingend die vollständige Matrix-Timeline.
Redigierte, nicht entschlüsselbare, gesperrte oder bereits durch Retention entfernte Events fehlen im Kontext.
Bei sehr großer Ausgabe kann der sichere Ausgabeformatter Kontextzeilen oder weitere Treffer auslassen.

4. Zeitzone und Sprache

Persönliche Zeitzone

Befehl	Funktion
`!fcib timezone`	Zeigt die wirksame persönliche oder standardmäßige Zeitzone.
`!fcib timezone status`	Wie oben.
`!fcib timezone Europe/Berlin`	Speichert eine persönliche IANA-Zeitzone.
`!fcib timezone reset`	Entfernt den persönlichen Wert und verwendet wieder den Bot-Standard.

Die Zeitzone bestimmt die Anzeige von Ergebniszeiten und die lokalen Tagesgrenzen von after: und before:. Matrix stellt keine standardisierte Benutzerzeitzone bereit.

Raumsprache

Befehl	Funktion	Recht
`!fcib language` oder `!fcib language status`	Zeigt Sprache und Quelle des wirksamen Werts.	Autorisiertes Raummitglied
`!fcib language de`	Setzt Deutsch für diesen Raum.	Bot-Raumverwalter mit Power-Level oder globaler Admin
`!fcib language en`	Setzt Englisch für diesen Raum.	Bot-Raumverwalter mit Power-Level oder globaler Admin
`!fcib language reset`	Entfernt den Raumwert und verwendet wieder den Bot-Standard.	Bot-Raumverwalter mit Power-Level oder globaler Admin

5. Statistiken

Für normale Nutzende

Befehl	Ausgabe
`!fcib stats` oder `!fcib stats room`	Indexstatus, Verschlüsselungsstatus sowie Anzahl, erste und letzte der für alle aktuell Beigetretenen historisch sichtbaren Nachrichten im aktuellen Raum.
`!fcib stats user`	Eigene gespeicherte Nachrichten-, Redaktions-, Medien-, Edit-, Raum- und Embedding-Aggregate; nur im verifizierten Bot-DM.

Befehl

Ausgabe

!fcib stats

oder

!fcib stats room

Indexstatus, Verschlüsselungsstatus sowie Anzahl, erste und letzte der für

alle aktuell Beigetretenen

historisch sichtbaren Nachrichten im aktuellen Raum.

!fcib stats user

Eigene gespeicherte Nachrichten-, Redaktions-, Medien-, Edit-, Raum- und Embedding-Aggregate; nur im verifizierten Bot-DM.

Für globale Admins im verifizierten Bot-DM

Befehl	Ausgabe
`!fcib stats global`	Globale Bot-, Index-, Job-, Fehler-, Unterhaltungs- und Sync-Aggregate.
`!fcib stats servers [--page N]`	Serveraggregate, maximal 25 Einträge je Seite.
`!fcib stats rooms --status <STATUS> [--page N]`	Räume mit `pending_opt_in` , `enabled` , `paused` , `disabled` oder `purged` .
`!fcib stats server <SERVER>`	Aggregate eines Matrix-Servers.
`!fcib stats room -r <ROOM-ID>`	Vollständige gespeicherte Aggregate eines Raums.
`!fcib stats user -u <USER-ID>`	Gespeicherte Aggregate eines Benutzers.

Statistikbefehle geben Aggregate und Betriebszustände aus, niemals Nachrichtentexte, Suchbegriffe oder Event-IDs.

6. Persönlicher Datenschutz

Die folgenden Selbstbedienungsbefehle funktionieren nur im verifizierten Bot-DM.

Befehl	Wirkung
`!fcib privacy status`	Zeigt, ob die künftige persönliche Indexierung aktiv oder dauerhaft gesperrt ist.
`!fcib privacy erase-all`	Fordert ein fünf Minuten gültiges Bestätigungstoken an. Nach Bestätigung werden der eigene Absender und die eigenen Nachrichtentexte in allen Bot-Indizes durch `[REDACTED]` ersetzt, Suchableitungen entfernt und künftige Inhalte von der Indexierung ausgeschlossen.
`!fcib forget-me`	Kurzform für `!fcib privacy erase-all` .
`!fcib privacy resume`	Fordert eine zweite Bestätigung an und erlaubt danach wieder die Indexierung künftiger Inhalte.

Beispiel für den Bestätigungsablauf

!fcib privacy erase-all

# Der Bot antwortet mit einem zeitlich begrenzten Token.
!fcib privacy erase-all confirm <TOKEN>

Nicht rückgängig zu machen: privacy resume stellt bereits redigierte Inhalte nicht wieder her. Es hebt nur die Sperre für neue Inhalte auf.

Event-ID, Raum, Zeit und Relationen bleiben als nicht durchsuchbare Strukturhülle erhalten. Die minimal erforderliche Matrix-ID bleibt in der Opt-out-Liste gespeichert. Mitgliedschaftsintervalle und das befristete Befehls-Audit bleiben aus Sicherheits- und Nachweisgründen getrennt erhalten.

7. Raumindex verwalten

Indexzustände

Status	Neue Inhalte	Suche	Gespeicherte Daten
`pending_opt_in`	Nein	Nein	Raum wartet auf ausdrückliche Aktivierung
`enabled`	Werden indexiert	Aktiv	Index und Ableitungen vorhanden
`paused`	Werden nicht neu indexiert	Vorhandene Daten bleiben suchbar	Bleiben erhalten
`disabled`	Nein	Nein	Bleiben bis zur Löschung erhalten
`purged`	Nein	Nein	Inhaltsindex wurde bereinigt

Status und Raumverwalter

Befehl	Funktion	Recht
`!fcib index status`	Zeigt Indexstatus und Verschlüsselung des aktuellen Raums.	Autorisiertes Mitglied
`!fcib index admin status`	Zeigt den gespeicherten Bot-Raumverwalter und die Zuweisungsquelle.	Autorisiertes Mitglied
`!fcib index admin claim`	Übernimmt eine freie oder verwaiste Bot-Raumverwalterrolle.	Aktueller Matrix-Raumadmin mit ausreichendem Power-Level

Ein vorhandener Raumverwalter kann nur übernommen werden, wenn der Bot zuverlässig feststellt, dass diese Person nicht mehr beigetreten ist oder das erforderliche Power-Level nicht mehr besitzt. Bei unklarer Lage wird die Übernahme abgelehnt.

Indexsteuerung für Bot-Raumverwalter

Befehl	Funktion
`!fcib index enable`	Aktiviert die Indexierung und startet je nach Konfiguration ein begrenztes Backfill.
`!fcib index pause`	Stoppt die Indexierung neuer Inhalte; vorhandene Daten bleiben suchbar.
`!fcib index resume`	Setzt eine pausierte Indexierung fort und plant die Unterhaltungserkennung neu ein.
`!fcib index disable`	Deaktiviert Indexierung und Suche. Daten bleiben gespeichert, bis sie gelöscht oder durch Retention entfernt werden.
`!fcib index delete-room`	Fordert eine zweite Bestätigung an und löscht danach Nachrichten, Suchvektoren, Embeddings und abgeleitete Raumdaten aus dem Bot-Index.
`!fcib index delete-user @user:server`	Löscht nach Bestätigung die Inhalte einer Person aus dem aktuellen Raumindex.

Achtung: delete-room löscht den PostgreSQL-Inhaltsindex des Raums, aber nicht die Originalereignisse auf dem Matrix-Homeserver und nicht selektiv die Olm-/Megolm-Schlüssel im getrennten Crypto-Store.

8. Unterhaltungen verwalten

Der Bot erkennt aus Nachrichten, Antworten, Threads, Zeitabständen, Beteiligten und semantischer Ähnlichkeit automatisch thematische Unterhaltungen. Diese Erkennung ist heuristisch. Bot-Raumverwalter können die abgeleiteten Metadaten korrigieren, ohne Matrix-Originalevents zu verändern.

Lesen und neu berechnen

Befehl	Funktion
`!fcib conversation list [--status STATUS] [--page N]`	Listet sichtbare Unterhaltungen im aktuellen Raum.
`!fcib conversation show <UUID>`	Zeigt sichere Details einer sichtbaren Unterhaltung.
`!fcib conversation events <UUID> [--page N]`	Listet sichtbare zugeordnete Events.
`!fcib conversation history <UUID> [--page N]`	Zeigt nachvollziehbare manuelle Änderungen.
`!fcib conversation status`	Zeigt Erkennungsstatus und offenen Job des aktuellen Raums.
`!fcib conversation rebuild`	Plant eine vollständige Neuberechnung des aktuellen Raums ein.

Erlaubte Statusfilter sind forming, active, dormant, closed, reopened und ignored.

Metadaten und Status bearbeiten

Befehl	Funktion
`!fcib conversation edit <UUID> --title "Titel"`	Setzt einen manuellen Titel, maximal 100 Zeichen.
`!fcib conversation edit <UUID> --description "Text"`	Setzt eine manuelle Beschreibung, maximal 500 Zeichen.
`!fcib conversation edit <UUID> --reset-title`	Entfernt den manuellen Titel.
`!fcib conversation edit <UUID> --reset-description`	Entfernt die manuelle Beschreibung.
`!fcib conversation close <UUID>`	Schließt eine Unterhaltung manuell.
`!fcib conversation reopen <UUID>`	Öffnet eine geschlossene Unterhaltung erneut.
`!fcib conversation ignore <UUID>`	Markiert eine Unterhaltung als zu ignorieren.

Tags und Event-Zuordnungen

Befehl	Funktion
`!fcib conversation tag add <UUID> <TAG>`	Fügt ein manuelles Keyword hinzu.
`!fcib conversation tag remove <UUID> <TAG>`	Entfernt ein manuelles Keyword.
`!fcib conversation tag list <UUID>`	Zeigt manuelle Keywords.
`!fcib conversation tag clear <UUID>`	Entfernt alle manuellen Keywords.
`!fcib conversation event exclude <UUID> <EVENT-ID>`	Trennt ein Event von der automatischen Zuordnung.
`!fcib conversation event include <UUID> <EVENT-ID>`	Hebt einen Ausschluss wieder auf.
`!fcib conversation event delete <UUID> <EVENT-ID> [--reason hate\|spam\|privacy\|other]`	Entfernt ein Event nach zweiter Bestätigung dauerhaft aus dem Bot-Index.

Zusammenführen und teilen

Befehl	Funktion
`!fcib conversation merge <ZIEL-UUID> <QUELL-UUID>`	Führt zwei Unterhaltungen nach Bestätigung dauerhaft zusammen.
`!fcib conversation split <UUID> --at <EVENT-ID>`	Trennt ab dem angegebenen Event nach Bestätigung eine neue Unterhaltung ab.

Manuelle Merge-/Split-Zuordnungen vorhandener Events gewinnen auch bei späteren Rebuilds. Neue Events werden weiterhin heuristisch eingeordnet.

Zusätzliche globale Unterhaltungsbefehle

Globale Admins verwenden diese Befehle ausschließlich im verifizierten Bot-DM:

!fcib conversation list -r <ROOM-ID> [--status STATUS] [--page N]
!fcib conversation show -r <ROOM-ID> <UUID>
!fcib conversation events -r <ROOM-ID> <UUID> [--page N]
!fcib conversation history -r <ROOM-ID> <UUID> [--page N]
!fcib conversation list-all [--server SERVER] [--status STATUS] [--page N]
!fcib conversation status -r <ROOM-ID>
!fcib conversation rebuild -r <ROOM-ID>
!fcib conversation jobs [--status pending|failed] [--page N]
!fcib conversation rebuild-all

rebuild-all benötigt eine zweite Bestätigung.

9. Keyword-Sperren

Keyword-Sperren sind Unicode-normalisierte, nicht von Groß-/Kleinschreibung abhängige wörtliche Teilstrings. Sie sind keine regulären Ausdrücke und kennen keine linguistischen Wortgrenzen. Das Hinzufügen einer Regel verlangt eine zweite Bestätigung und löscht auch bereits gespeicherte passende Klartexte, Edits und optionale Dateinamen-Metadaten samt Suchableitungen.

Aktueller Raum

!fcib index keyword add room "wörtliche Phrase"
!fcib index keyword list room [Seite]
!fcib index keyword remove room <REGEL-UUID>

Erforderlich ist die Bot-Raumverwalterrolle mit aktuellem Matrix-Power-Level.

Bestimmte Person in allen Indizes

!fcib index keyword add user @user:server "wörtliche Phrase"
!fcib index keyword list user @user:server [Seite]
!fcib index keyword remove user @user:server <REGEL-UUID>

Erforderlich sind globale Adminrechte im verifizierten Bot-DM.

Botweit

!fcib index keyword add global "wörtliche Phrase"
!fcib index keyword list global [Seite]
!fcib index keyword remove global <REGEL-UUID>

Erforderlich sind globale Adminrechte im verifizierten Bot-DM. Eine Seite enthält höchstens 25 Regeln.

Keine Wiederherstellung: Das Entfernen einer Keyword-Regel stellt zuvor gelöschte Inhalte nicht automatisch wieder her. Dafür wäre ein ausdrücklich kontrolliertes Backfill nötig.

10. Globale Administration

Alle Befehle dieses Abschnitts werden ausschließlich in einem verifizierten Zwei-Personen-DM mit dem Bot ausgeführt.

Globale Bot-Admins

!fcib admin list [Seite]
!fcib admin status @user:server

Nur Bootstrap-/Root-Admins aus FREI_CHAT_GLOBAL_ADMINS dürfen persistente Adminrechte vergeben oder entziehen:

!fcib admin add @user:server
!fcib admin remove @user:server

Fest konfigurierte Bootstrap-Admins können nicht per Chat entfernt werden. Konfigurierte und persistente globale Admins sind von den Bot-Rate-Limits ausgenommen.

Globale Benutzerlöschung

!fcib index delete-user-all @user:server

Der Befehl löscht nach Bestätigung vorhandene Nachrichten, Edits, Medienmetadaten, Suchvektoren und Embeddings der Person aus allen bekannten Bot-Indizes. Er sperrt künftige Nachrichten nicht. Für eine dauerhafte persönliche Zukunftssperre dient privacy erase-all.

Einladungsserver und Regeln

Standardmäßig werden nur Einladungen vom Heimserver des Bots akzeptiert. Globale Admins können weitere Server freigeben und dort alle Benutzer oder ausschließlich vollständige Regex-Treffer zulassen.

Befehl	Funktion
`!fcib server list [Seite]`	Listet freigegebene Einladungsserver.
`!fcib server status <SERVER>`	Zeigt Freigabe, Modus, Regeln und Revoke-Zustand.
`!fcib server allow <SERVER>`	Erlaubt den Server und hebt einen aktiven Server-Revoke auf.
`!fcib server remove <SERVER>`	Entfernt die normale Freigabe.
`!fcib server mode <SERVER> all\|regex`	Erlaubt alle Benutzer oder ausschließlich Regel-Volltreffer.
`!fcib server rule add <SERVER> '^@support-.*:example\.org$'`	Fügt eine zeitbegrenzt ausgewertete Volltreffer-Regex hinzu.
`!fcib server rule list <SERVER> [Seite]`	Listet Regeln seitenweise.
`!fcib server rule remove <SERVER> <UUID>`	Entfernt eine Regel.
`!fcib server revoke <SERVER>`	Sperrt nach Bestätigung Benutzer und Room-IDs dieses Servers und entfernt zugehörige Indexdaten.
`!fcib server revoke-room <ROOM-ID>`	Sperrt nach Bestätigung genau einen Raum.
`!fcib server purge <SERVER>`	Löscht nach einem Revoke und einer weiteren Bestätigung alle betroffenen Server-Raumindizes und Benutzerbeiträge.
`!fcib server purge-room <ROOM-ID>`	Löscht nach Revoke und Bestätigung genau diesen Raumindex.

Statische Denylists und aktive Revokes haben immer Vorrang. server allow entfernt zwar den aktiven Server-Revoke, stellt aber gelöschte Daten nicht wieder her.

Persistente Bot-Konfiguration

!fcib config global list [Seite]
!fcib config global get <KEY>
!fcib config global set <KEY> <WERT>
!fcib config global reset <KEY>
!fcib config global history [Seite]

!fcib config room list [Seite]
!fcib config room <ROOM-ID> effective
!fcib config room <ROOM-ID> get <KEY>
!fcib config room <ROOM-ID> set <KEY> <WERT>
!fcib config room <ROOM-ID> reset <KEY>
!fcib config room <ROOM-ID> history [Seite]

Priorität der Werte: Raum-Override vor globalem Datenbankwert vor Deployment-Standard. Setzen und Zurücksetzen verlangen ein fünf Minuten gültiges Bestätigungstoken. Boolesche Werte werden als true oder false angegeben.

Typische pro Raum überschreibbare Einstellungen

language, include_notices, store_media_metadata
default_limit, max_limit, max_context_per_side, max_context_messages_total
max_query_chars, max_message_chars
backfill_on_enable, backfill_page_size, backfill_max_events
retention_days, retention_max_events, redaction_audit_days, delete_on_bot_leave
Raumbezogene Befehls- und Suchlimits
Die meisten conversation_*-Erkennungs- und Ausgabelimits außer conversation_workers

Nur global konfigurierbare Einstellungen

auto_join, require_room_opt_in, index_on_join
default_timezone, admin_power_level
Botweite und benutzerbezogene Rate-Limits sowie Suchparallelität
semantic_similarity_threshold_percent, conversation_workers
DM-, Sync-, Entschlüsselungs-, Worker- und Housekeeping-Grenzen
command_audit_retention_days

!fcib config global set retention_days 365
!fcib config room !raum:server set backfill_max_events 5000

Secrets, Datenbankverbindungen, Matrix-Token, Device-/E2EE-Schlüssel und Embedding-Modell-/Providerwechsel sind nicht per Chat konfigurierbar. Einige globale Servicewerte werden erst nach einem kontrollierten Bot-Neustart vollständig wirksam.

Befehls-Audit

!fcib audit list [--room <ROOM-ID>] [--user <USER-ID>]
    [--after <DATUM|ISO-ZEIT>] [--before <DATUM|ISO-ZEIT>]
    [--command <BEFEHL>] [--outcome <STATUS>] [--page N]

Globale Admins sehen alle Einträge einschließlich sicher strukturierter Parameter. Bestätigungstoken werden im Audit redigiert. Delegierte Prüfer sehen nur die Schnittmenge ihrer aktiven Raum-, Akteur- und Zeitfreigaben; Parameter nur, wenn dies ausdrücklich erlaubt wurde.

Nur Bootstrap-/Root-Admins verwalten Grants:

!fcib audit grant @user:server [--room <ROOM-ID>] [--actor <USER-ID>]
    [--after <DATUM|ISO-ZEIT>] [--before <DATUM|ISO-ZEIT>]
    [--expires-hours 1..168] [--parameters]
!fcib audit grants [--user <USER-ID>] [--page N]
!fcib audit revoke <GRANT-ID>

Erteilung und Widerruf benötigen eine zweite Bestätigung. Das interne Bot-Audit ist keine unveränderliche externe Auditspur; bei entsprechenden Anforderungen müssen Homeserver- und Datenbank-Auditing ergänzt werden.

11. Datenverarbeitung, Sicherheit und Grenzen

Was indexiert wird

Unterstützte Textnachrichten aus unverschlüsselten Räumen
Erfolgreich lokal entschlüsselte Textnachrichten aus E2EE-Räumen
Absender, Zeit, Event-ID, Raumbezug, Reply-/Thread-Relationen und gültige Bearbeitungen
Kanonischer Klartext, Volltextindex, Tippfehlerindex und sensible semantische Embeddings
Optional sichere Medienmetadaten wie Dateiname und MIME-Type, wenn die Installation dies aktiviert hat
Abgeleitete Unterhaltungen, Episoden, Titel, Tags und Zuordnungen
Mitgliedschafts- und History-Visibility-Intervalle, die für historische Berechtigungsprüfungen erforderlich sind

Was nicht als Suchinhalt indexiert wird

Nicht entschlüsselbare E2EE-Events und Ciphertext
Bot-Befehle und Bot-Nachrichten
Reply-Fallback-Zitate
Reactions, Receipts und Typing
Medieninhalte, OCR sowie Audio-/Video-Transkriptionen
Redigierte oder durch Keyword-, Benutzer- oder Raumregeln gesperrte Inhalte

Bearbeitungen und Redactions

Eine Bearbeitung darf nur eine ältere Nachricht derselben Person im selben Raum ersetzen.
Out-of-order eintreffende Bearbeitungen werden vorgemerkt.
Ungültige Bearbeitungen verlieren ihren Inhalt und lösen kein neues Embedding aus.
Eine Redaction entfernt Originaltext, aktuellen Text, Suchvektor und Embedding.
Tombstones verhindern, dass ein später erneut eintreffendes Event ungewollt wieder im Index erscheint.

E2EE

Die Entschlüsselung findet lokal im persistenten Matrix-Crypto-Kontext des Bot-Geräts statt. Ohne passenden Room Key kann ein Event nicht indexiert werden. Historische Vollständigkeit ist daher nicht garantiert, insbesondere für Nachrichten vor dem Beitritt des Bots. Ein Recovery Key stellt Cross-Signing-Vertrauen her, importiert aber nicht automatisch ein vollständiges Matrix-Key-Backup.

Embeddings

Im Standardbetrieb verwendet der Bot lokal das mehrsprachige Modell paraphrase-multilingual-MiniLM-L12-v2 und speichert 384-dimensionale Embeddings. Ein externer OpenAI-kompatibler Embedding-Endpunkt ist technisch möglich, aber standardmäßig deaktiviert und erfordert ein ausdrückliches Doppel-Opt-in. Die konkrete Installation sollte offenlegen, ob Inhalte die lokale Sicherheitsgrenze verlassen.

Aufbewahrung und Löschung

Der Auslieferungsstandard für zeitbasierte Inhaltsaufbewahrung beträgt 365 Tage; globale oder raumbezogene Konfiguration kann abweichen.
Zusätzlich kann die Zahl indexierter Root-Events je Raum begrenzt sein.
Retention wird regelmäßig ausgeführt und ist kein synchrones Insert-Limit.
Das Befehls-Audit hat eine getrennte Aufbewahrungsdauer, im Auslieferungszustand 90 Tage.
Löschbefehle entfernen Bot-Indexdaten, nicht die Originalnachrichten vom Matrix-Homeserver.

Sicherheitsprinzipien

Fail closed: Unvollständige Mitgliedschafts- oder Sichtbarkeitsevidenz erweitert Rechte nicht.
Live-Prüfung: Mitgliedschaft und Berechtigung werden bei jeder sensiblen Anfrage erneut geprüft.
Minimale Ausgabe: Raumname, Trefferzahl und Trefferexistenz bleiben für Unberechtigte verborgen.
Plaintext-Ausgabe: Nachrichtentext wird niemals als ausführbarer Inhalt interpretiert.
Parametrisierte Datenbankabfragen: Suchtext oder Nachrichteninhalt wird nicht als SQL ausgeführt.
Zweite Bestätigung: Destruktive und besonders privilegierte Aktionen verlangen ein Scope-gebundenes, fünf Minuten gültiges Token.
Rate-Limits: Globale, Benutzer-, Befehlsraum-, Such- und Zielraumlimits schützen vor Missbrauch.

Wichtige bekannte Einschränkungen

Der Bot kennt nur Räume, in denen sein eigenes Konto Mitglied ist.
Fehlende historische E2EE-Schlüssel oder serverseitig fehlende Historie können nicht rekonstruiert werden.
Die historische Sichtbarkeit hängt von beobachteten Membership- und History-Visibility-Events ab; fehlende Historie reduziert Treffer.
Die Unterhaltungserkennung ist heuristisch und kann gleichzeitige Themen zusammenfassen oder trennen.
Der erste Sync ohne gespeicherten Checkpoint unterdrückt alte Timeline-Befehle. Ein während dieses Startfensters gesendeter Befehl muss nach der Betriebsbereitschaft erneut gesendet werden.
Die Berechtigungsprüfung ist ein Zeitpunkt-Snapshot in einem verteilten System. Der Bot prüft unmittelbar vor und nach der Suche, kann einen Leave in den wenigen Millisekunden zwischen letzter Prüfung und Versand aber nicht atomar mit dem Homeserver koppeln.
Komplexe HTML-Formatierung und Links aus Nachrichten werden absichtlich zu sicherem Klartext reduziert.
Ein bösartiger oder kompromittierter Homeserver liegt innerhalb der Vertrauensgrenze für Events und Mitgliedschaften.

12. Fehlerbehebung

Symptom oder Meldung	Wahrscheinliche Ursache	Lösung
Der Bot reagiert nicht auf `!search` .	Direkte Altbefehle sind deaktiviert.	`!fcib search …` verwenden.
„Nicht erlaubt. Mitgliedschaft, Raumtyp und Berechtigung wurden live geprüft.“	Fehlende Mitgliedschaft, falsche Rolle, zu niedriges Power-Level oder ein Befehl wurde außerhalb des erlaubten DM-/Raumkontexts ausgeführt.	Mitgliedschaft und Rolle prüfen; globale Befehle im verifizierten Bot-DM ausführen.
„… kein sicher verifizierter Bot-DM“	Der Raum hat nicht exakt Bot und anfragende Person als aktive Mitglieder oder der Bot hat früher einen Dritten beobachtet.	Einen neuen echten Zwei-Personen-DM mit dem Bot anlegen; bei strikter Installation auch die Direktchat-Markierung prüfen.
„Keine sichtbaren Treffer gefunden.“	Kein Treffer, Index nicht aktiv, Inhalt außerhalb der Retention, fehlende historische Sichtbarkeit oder fehlender E2EE-Key.	`!fcib index status` prüfen, Suchfilter lockern und gegebenenfalls den Raumadmin oder Bot-Operator kontaktieren.
Bestätigungstoken ist ungültig oder abgelaufen.	Token ist älter als fünf Minuten, stammt aus einem anderen Raum/Scope oder Argumente wurden verändert.	Ausgangsbefehl erneut senden und die vom Bot ausgegebene Bestätigungszeile unverändert verwenden.
„Zu viele Befehle.“	Ein persistentes Rate-Limit wurde erreicht.	Bis zum ausgegebenen UTC-Zeitpunkt warten. `search-all` zählt standardmäßig stärker als eine Raumsuche.
Datumsfilter wirken um einen Tag verschoben.	Falsche persönliche oder standardmäßige Zeitzone.	`!fcib timezone status` prüfen und beispielsweise `!fcib timezone Europe/Berlin` setzen.
Historische verschlüsselte Nachrichten fehlen.	Der Bot besitzt die konkrete Megolm-Session nicht oder durfte das Event nicht sehen.	Gerätevertrauen und Key-Sharing durch den Operator prüfen. Vor dem Bot-Beitritt besteht keine Vollständigkeitsgarantie.
`index admin claim` wird abgelehnt.	Der gespeicherte Verwalter ist weiterhin berechtigt oder sein Zustand konnte nicht zuverlässig geprüft werden.	Power-Level und Mitgliedschaft prüfen; bei unklarem State später erneut versuchen.
Der Bot kann in einem E2EE-Raum nicht antworten.	Mindestens ein Raumgerät erfüllt möglicherweise die konfigurierte Vertrauensschwelle für sichere Ausgaben nicht.	Geräte verifizieren und den Befehl erneut senden.
„Interner Datenbankfehler“ oder „Interner Verarbeitungsfehler“	Ein sicher abgegrenzter interner Fehler ist aufgetreten.	Bot-Operator mit Zeitpunkt, Raum und ausgeführtem Befehl informieren; keine Secrets oder Bestätigungstoken weitergeben.

13. Kurzreferenz

Normale Nutzung

!fcib help [THEMA]
!fcib search <ANFRAGE>
!fcib find <ANFRAGE>
!fcib search -r <ROOM-ID|RAUMALIAS> <ANFRAGE>
!fcib search-all <ANFRAGE>
!fcib timezone status|reset|<IANA-ZEITZONE>
!fcib language status
!fcib stats room
!fcib stats user
!fcib privacy status|erase-all|resume
!fcib forget-me
!fcib index status
!fcib index admin status

Bot-Raumverwalter

!fcib index enable|pause|resume|disable
!fcib index delete-room
!fcib index delete-user @user:server
!fcib index keyword add|list|remove room …
!fcib language en|de|reset
!fcib conversation …

Globale Administration im Bot-DM

!fcib admin …
!fcib audit …
!fcib config global …
!fcib config room …
!fcib server …
!fcib stats global|servers|rooms|server|room|user …
!fcib index delete-user-all @user:server
!fcib index keyword add|list|remove user|global …
!fcib conversation list-all|jobs|rebuild-all …

Hilfethemen im Bot

!fcib help help
!fcib help search
!fcib help timezone
!fcib help language
!fcib help stats
!fcib help index
!fcib help privacy
!fcib help keywords
!fcib help conversations
!fcib help admins
!fcib help servers
!fcib help config
!fcib help audit
!fcib help security

Diese Hilfeseite beschreibt den Funktionsumfang des Frei Chat Index Bot auf Basis des Projektstands vom 20. Juli 2026. Wirksame Grenzwerte, Sprache, Aufbewahrung und aktivierte Funktionen können durch die konkrete Installation abweichen. Im Zweifel zeigt !fcib help die aktuell verfügbaren Befehle und !fcib config … get|effective die wirksame Konfiguration.