codex-lcm

Lokale, verlustfreie Kontextverwaltung für OpenAI Codex CLI.

codex-lcm erfasst Codex-Konversationsereignisse in SQLite, verdichtet älteren Kontext zu einer Hierarchie von Zusammenfassungen, ohne die Quellnachrichten zu löschen, stellt relevanten Kontext beim Start einer Sitzung wieder her und bietet lexikalischen Abruf über einen lokalen MCP-Server.

Bedeutung von „verlustfrei“: Quellinhalte werden nach der konfigurierten Schwärzung von Geheimnissen aufbewahrt. Durchsuchbare Tool-Vorschauen sind begrenzt, während vollständige geschwärzte Tool-Eingaben und -Ausgaben über seitenweise Erweiterung verfügbar bleiben.

Status und Plattform

codex-lcm ist Beta-Software für macOS. Es basiert auf Codex-Hooks und POSIX flock; Windows und Linux werden derzeit nicht unterstützt oder beansprucht.

Related MCP server: ClaudeX

Funktionen

• Live-Erfassung: Benutzeraufforderungen, Assistentenantworten und Tool-Aktivitäten werden über Codex-Hooks erfasst.

• Dauerhafte lokale Speicherung: SQLite im WAL-Modus speichert rohe Nachrichten, strukturierte Nachrichtenteile, Zusammenfassungen und FTS5-Indizes.

• Hierarchische Verdichtung: Ältere Nachrichten werden zu Blattzusammenfassungen; geeignete Zusammenfassungsläufe können zu tieferen DAG-Knoten kondensiert werden. Quellzeilen werden niemals automatisch gelöscht.

• Kontextwiederherstellung: Aktive Zusammenfassungen und die neuesten nicht zusammengefassten Nachrichten werden beim Sitzungsstart innerhalb einer strengen Größenbegrenzung eingefügt.

• Lokaler Abruf: Sechs stdio-MCP-Tools bieten lexikalische Suche, Suche nach aktuellen Sitzungen, Metadatenprüfung und seitenweise Quellenerweiterung.

• Fail-Open-Hooks: Erfassungs- oder Verdichtungsfehler blockieren keinen Codex-Turn.

• Sicherheitskontrollen: Schwärzung von Geheimnissen, Sperren für die Verdichtung pro Sitzung, atomare Nachrichten-/FTS-Schreibvorgänge, Reservierungen für Provider-Aufrufe, Fortschrittsprüfungen und private Standard-Dateiberechtigungen.

Installation aus einem Repository-Checkout

python3 -m venv ~/.codex-lcm/venv
~/.codex-lcm/venv/bin/python -m pip install .
~/.codex-lcm/venv/bin/codex-lcm install
~/.codex-lcm/venv/bin/codex-lcm doctor

Starten Sie Codex nach der Installation neu. Verwenden Sie /hooks in Codex, um die installierten Hooks zu überprüfen und zu vertrauen.

Das Installationsprogramm fügt codex-lcm-Einträge in ~/.codex/hooks.json und ~/.codex/config.toml ein. Es erstellt zeitgestempelte Sicherungskopien, bevor vorhandene Dateien geändert werden. Ein erneutes Ausführen des Installationsprogramms ist idempotent.

Ein Quellcode-Checkout enthält auch scripts/install.sh, das dieselbe isolierte Installation und Verifizierung durchführt.

Optionale LLM-Zusammenfassung

Auf Python 3.11+ hat das Kernpaket keine Abhängigkeiten von Drittanbietern zur Laufzeit. Python 3.10 installiert den Kompatibilitäts-Backport tomli für eine sichere TOML-Konfigurationsbehandlung. Ohne einen LLM-Client verwendet die Verdichtung eine deterministische Kopf-/Schwanz-Kürzung.

Um eine OpenAI-kompatible Zusammenfassung zu aktivieren, installieren Sie die optionale Zusatzfunktion und konfigurieren Sie Anmeldeinformationen:

~/.codex-lcm/venv/bin/python -m pip install ".[llm]"
export CODEX_LCM_API_KEY="..."

OPENAI_API_KEY wird ebenfalls erkannt. Verwenden Sie CODEX_LCM_BASE_URL oder OPENAI_BASE_URL für einen OpenAI-kompatiblen Endpunkt. Die CODEX_LCM_*-Provider-Einstellungen werden als Paar behandelt und haben als Paar Vorrang, sodass ein globaler Schlüssel niemals an einen bereichsbezogenen Endpunkt gesendet wird. Wenn CODEX_LCM_BASE_URL gesetzt ist, konfigurieren Sie auch CODEX_LCM_API_KEY.

CLI

codex-lcm install                       Wire hooks and the MCP server into Codex
codex-lcm uninstall                     Remove codex-lcm wiring and keep stored data
codex-lcm status                        Show database statistics
codex-lcm doctor                        Verify package, database, hooks, and MCP wiring
codex-lcm compact --session <id>        Compact one session synchronously
codex-lcm compact --all                 Compact every recorded session synchronously

Die Deinstallation löscht nicht ~/.codex-lcm/ oder dessen Datenbank.

MCP-Tools

Der Abruf ist lexikalisch, nicht semantisch: In dieser Version gibt es keine Einbettungen oder Vektorähnlichkeitsansprüche.

Konfiguration

Die Konfiguration wird aus Umgebungsvariablen gelesen.

Das Standard-Datenverzeichnis hat den Modus 0700; die Datenbank, WAL-Nebendateien, Sperrdateien und das Verdichtungsprotokoll haben auf POSIX-Systemen den Modus 0600.

Daten- und Sicherheitsgrenzen

• Die Schwärzung erfolgt vor der Persistenz für bekannte API-Schlüssel, Token, Autorisierungsheader, Passwort-/Geheimniszuweisungen, JWTs und PEM-Private-Key-Dateien.

• Git-Remote-URLs mit Anmeldeinformationen werden ohne Benutzerinformationen, Abfrageparameter oder Fragmente gespeichert.

• Die Schwärzung ist eine mehrschichtige Verteidigung, keine Garantie, dass jedes mögliche Geheimnisformat erkannt wird.

• Vollständige geschwärzte Tool-Payloads können weiterhin private Konversations- oder Projektdaten enthalten. Schützen Sie das lokale Konto und die Datenbanksicherungen entsprechend.

• Es werden keine Daten an einen LLM-Provider gesendet, es sei denn, der optionale Client ist installiert und Provider-Anmeldeinformationen oder eine Basis-URL sind konfiguriert.

• Automatische Aufbewahrung und Löschung sind bewusst nicht vorhanden. Die Anwendung verwirft Quellverlauf nicht still.

Entwicklung

Verwenden Sie eine projektlokale Umgebung; Tests benötigen niemals das Live-Codex-Profil oder die Live-Datenbank.

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q
.venv/bin/python tests/smoke_test.py
.venv/bin/python tests/reliability_test.py
.venv/bin/python tests/package_test.py
.venv/bin/ruff check .
.venv/bin/bandit -q -r codex_lcm

Das Paket wird in einem Wegwerf-Home-Verzeichnis und einer virtuellen Umgebung gebaut und installiert. Die Smoke- und Zuverlässigkeitsskripte verwenden ebenfalls temporäre Datenbanken.

Siehe DESIGN.md für das Speichermodell, Invarianten, Hook-Ablauf und Fehlerverhalten.

Lizenz

MIT