Die Library of Context

Virtueller Speicher für KI-Kontext: dauerhaft außerhalb des Modells, begrenzt innerhalb davon.

Ein KI-Modell hat ein endliches natives Kontextfenster. Lange Unterhaltungen dehnen sich schließlich aus, bis alte Informationen abgeschnitten oder komprimiert werden. Für Aufrufe, die über seinen Kontext-Governor geleitet werden, speichert die Library jedes aufgezeichnete Ereignis in SQLite und stellt eine begrenzte Modellanfrage aus geschützten Ereignissen, aktuellen Ereignissen und abgerufenen Datensätzen zusammen.

Stellen Sie sich das Kontextfenster des Modells als Lesetisch vor. Die Library kann weit mehr Bücher aufnehmen als der Tisch, aber der Bibliothekar legt nur die Bücher auf, die für die aktuelle Aufgabe benötigt werden. Ein Aufgabenwechsel ersetzt den Tisch; er stapelt nicht weitere Bücher darauf.

[!IMPORTANT] Dieses Projekt erweitert den adressierbaren Kontext, nicht die physische Kontextfenstergrenze eines Modells. Es ist für lokale Prototypen und Zusammenarbeit gedacht, nicht als produktiver Multi-Tenant-Speicherdienst. Siehe Capability Status für explizite Unterstützungsgrenzen.

Warum sich dies von gewöhnlicher Kompaktierung unterscheidet

Herkömmliche Kompaktierung verwandelt ein wachsendes Transkript in eine kleinere, verlustbehaftete Fortsetzung und kann die ursprünglichen Details außerhalb des aktiven Workflows belassen. Die Library verwendet reversible semantische Paginierung:

traditional:  growing transcript -> compacted transcript -> continue

Library:      durable event log -> bounded recent/protected context
                       |                    + relevant retrieved books
                       +-----------> fresh model request on every turn

Ursprüngliche Ereignisse sind prüfbar und wiederherstellbar. Zusammenfassungen können Navigationshilfen werden, müssen aber nicht die einzige überlebende Kopie sein.

Die Landschaft verwandter Arbeiten vergleicht dieses Design mit Modell-Long-Context-Methoden, Retrieval, Prompt-Kompression, Provider-Kompaktierung, Agentenspeicher, Checkpointing und Inferenz-Laufzeit-Paginierung. Hier bedeutet „Kompaktierung" eine kleinere, potenziell verlustbehaftete Fortsetzungsdarstellung, deren Originale nicht unabhängig adressierbar sind, sofern keine andere Schicht sie aufbewahrt.

Related MCP server: local-memory-mcp

Funktionen

• Ein Kontext-Governor mit prepare -> model call -> commit-Lebenszyklusoperationen.

• Dauerhafte SQLite-Thread-Ereignisse und eine transaktionale Indexierungs-Outbox.

• Ein token-zielgerichteter, ereignisbegrenzter aktueller Ring für unmittelbares Read-Your-Own-Context-Verhalten; ein übermäßig großes Ereignis wird nur im Modell-Envelope gekürzt, nicht auf der Festplatte.

• Ein begrenzter Arbeitsring mit einer dauerhaften SQLite-Outbox für Überlauf und Neustart-Wiederherstellung.

• Geschützter Kontext für Anweisungen, Entscheidungen, aktive Pläne und ungelösten Zustand.

• Aufgezeichnete, eingebettete und indizierte Wasserzeichen mit Warteschlangen-Status.

• Frische, begrenzte Prompt-Envelopes, die das Transkriptwachstum ersetzen.

• Hybrides Vektor-, SQLite-FTS5-, Wichtigkeits- und Aktualitäts-Retrieval.

• Byte-begrenzter Prozess-RAM und optionale wegwerfbare lokale Redis-Hot-Tiers.

• Lese-Tisch-Wechselberichte: swapped_in, swapped_out und retained.

• Python-, lokale HTTP-, CLI- und STDIO-MCP-Integrationsoberflächen.

• Abhängigkeitsfreie Hashing-Embeddings und ein optionaler lokaler Ollama-Adapter.

Der Governor ist automatisch, wenn Ihr Agent oder Modell-Gateway jede Runde durch ihn leitet. Eine reine MCP-Integration ist kooperativ: Der Host kann Shelving- und Lese-Tisch-Werkzeuge verwenden, kann aber die Modellanfrage, die bereits ein Werkzeug aufgerufen hat, nicht umschreiben oder einen undokumentierten internen Kompaktierungs-Hook ersetzen.

Architektur auf einen Blick

flowchart LR
    U[User or tool event] --> A[Durable SQLite append]
    A --> E[(Thread event log)]
    A --> O[(Transactional outbox)]
    A --> R[Recent context ring]
    O --> W[Bounded work ring]
    W --> I[Embed and index workers]
    I --> S[(SQLite library and FTS)]
    I --> C[RAM and optional Redis cache]
    R --> G[Context governor]
    S --> G
    P[Protected context] --> G
    G --> D[Bounded reading desk]
    D --> M[Native model context]
    M --> X[Assistant response]
    X --> A

Schnellstart

Die Standardkonfiguration erfordert nur Python 3.11 oder neuer. Redis ist optional.

Unter Windows PowerShell:

git clone https://github.com/hwillGIT/library-of-context.git
cd library-of-context
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m library_of_context quickstart

Unter macOS oder Linux:

git clone https://github.com/hwillGIT/library-of-context.git
cd library-of-context
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m library_of_context quickstart

Der Schnellstart übt Schutz, Prompt-Zusammenstellung, Ereignisaufzeichnung, Indizierung und Bereinigung mit einer temporären Datenbank. Er verwendet kein Redis, Docker, keinen Cloud-Dienst und keine Modell-API. Fahren Sie mit dem Installationsleitfaden fort.

Fügen Sie es einem Agenten hinzu, den Sie bereits ausführen

Siehe Fügen Sie die Library Ihrem Agenten hinzu für Codex-, Python- und HTTP-Konfigurationsbeispiele. Starten Sie nach der MCP-Serverkonfiguration den Client neu oder beginnen Sie eine separate Sitzung; die Konfiguration wirkt sich nicht auf einen bereits laufenden Chat aus.

Ausführen eines automatisch verwalteten Python-Textagenten

from library_of_context import GovernedTextAgent, LibraryOfContext


def call_my_model(messages: list[dict[str, str]]) -> str:
    return my_model_client.generate(messages=messages)


with LibraryOfContext("data/library.sqlite", redis_url="") as library:
    with library.open_context_governor(
        "agent-thread-42",
        token_budget=12_000,
        recent_token_budget=4_000,
        protected_token_budget=2_000,
    ) as context:
        context.protect(
            "Production changes require a canary wave.",
            label="deployment-policy",
        )

        agent = GovernedTextAgent(
            context,
            call_my_model,
            system_prompt="Work carefully and cite retrieved project evidence.",
        )
        response = agent.turn(
            "Diagnose the deployment failure.",
            turn_id="request-0001",
        )
        context.flush(timeout=5)
        print(context.status()["watermarks"])

Der Callback muss genau die gelieferten messages senden; er darf kein weiteres Transkript anhängen oder eine vom Anbieter verwaltete Unterhaltung fortsetzen. Der eingebaute Adapter ist nur für Text. Strukturierte Tool-Aufrufe, Streams, Anhänge und multimodale Inhalte benötigen einen benutzerdefinierten Serialisierungsadapter.

Siehe Context Governor für das vollständige Protokoll.

MCP-Integration

Für einen normalen MCP-Agenten verwenden Sie die projektisolierte Vorlage und die bereiten Agentenanweisungen in integrations/README.md. Dies ist kooperativer Speicher; es steuert nicht das native Transkript des Hosts.

Der rohe lokale STDIO-Server kann mit folgendem Befehl untersucht werden:

python -m library_of_context.mcp_server --no-redis

Benutzerdefinierte MCP-Gateways, die die Modellaufrufgrenze besitzen, können Folgendes verwenden:

Die Library stellt Shelving-, Retrieval-, Lese-Tisch-, zustandslose Sitzungs- und Governor-Werkzeuge bereit. Aktivieren Sie Gateway-only-Werkzeuge nur in einem Host, der die zurückgegebenen messages als vollständige nächste Modellanfrage sendet.

Lokale HTTP-API

python -m library_of_context --no-redis serve

Die Governor-Endpunkte sind:

Die Routen /books, /library/ingest, /catalog/query und /desk/* legen die Bibliothek auf niedrigerer Ebene offen. Der Server bindet an Loopback und hat keine Authentifizierung. Setzen Sie ihn nicht direkt einer anderen Maschine aus.

Speicherhierarchie

1. Aktueller Ring: Pro-Thread geordnete Ereignisse, begrenzt durch Ereignisanzahl und ein geschätztes Token-Ziel. Ein übermäßig großes Ereignis kann resident bleiben, damit frischer Kontext sichtbar ist; die Prompt-Zusammenstellung kürzt seine modellsichtbare Ansicht auf das harte Envelope-Budget. Dies ist kein LRU; die Gesprächsreihenfolge ist wichtig.

2. Prozess-RAM: Byte-begrenzter LRU für heiße Bücher und Retrieval-Ergebnisse.

3. Lokales Redis: Optionaler gemeinsamer Cache für heiße Bücher, Abfragen, Tische, TTLs und Invalidierungsgenerationen.

4. SQLite: Maßgebliche Ereignisse, Outbox, Text, Metadaten, FTS und Vektorspeicher.

Redis ist wegwerfbar. Die standardmäßige lokale Redis-Konfiguration ist kein dauerhafter Nachrichtenbroker und sollte nicht als Team-Ereignisstrom verwendet werden.

Kostenloses lokales Redis unter Windows

Docker und ein Cloud-Konto sind nicht erforderlich. Das enthaltene PowerShell-Skript installiert einen Redis-Dienst in Ubuntu WSL. Es erfordert WSL 2, eine Ubuntu-Distribution und systemd:

powershell -ExecutionPolicy Bypass -File .\scripts\install-local-redis.ps1
.\.venv\Scripts\python.exe -m library_of_context --db data/redis-check.sqlite doctor

doctor öffnet die konfigurierte SQLite-Datenbank, während es die Speicher-Tiers prüft. Das obige Beispiel erstellt data/redis-check.sqlite.

Verwenden Sie überall --no-redis, wenn SQLite plus Prozess-RAM ausreicht.

Leistungsgrenzen

Die Prompt-Zusammenstellung ist begrenzt, und aufgezeichnete Ereignisse verwenden eine transaktionale Outbox. FTS gibt eine begrenzte Kandidatenmenge zurück, während Vektor-Retrieval jeden Live-Datensatz in einem Namespace exakt bewertet. Großkatalog-Skalierungsansprüche erfordern daher gemessene Belege und, wenn der exakte Pfad eine deklarierte Grenze überschreitet, einen begrenzten Vektor-Suchadapter.

Performance and Scaling definiert Messungen, SLO-Kriterien und Benchmark-Fragen. Why These Improvements? vergleicht einfachere Alternativen, Einführungsauslöser und Beleg-Gates, während der Roadmap bedingte Arbeiten sequenziert.

Dokumentation

Helfen Sie mit, das Design zu gestalten

Offene Designfragen umfassen:

• Welcher Kontext sollte automatisch geschützt werden, und wer darf ihn freigeben?

• Wie sollte die Retrieval-Qualität für Agent-Threads statt für Dokument-QA gemessen werden?

• Was ist der richtige lokale ANN-Adapter für 100.000 bis 1.000.000 Chunks?

• Wie sollten Branches Kontext erben, ersetzen und zusammenführen?

• Welches Wissen ist sicher und nützlich, um es von einem privaten Thread in einen Team-Katalog zu überführen?

• Sollte die gemeinsame Ereignisebene Redis Streams, NATS JetStream oder einen anderen Broker verwenden?

• Wie sollte der ACL-Widerruf lokale Caches ungültig machen, ohne die Cloud in den kritischen Pfad des Prompts einzubeziehen?

• Welche Token-Druck-Richtlinie wirkt für Benutzer über verschiedene Modell-Tokenizer hinweg vorhersehbar?

Die längere Liste befindet sich in ROADMAP.md. Fragen, Benchmark-Ergebnisse, Design-Notizen, Adapter, Fehlertests und Kritiken sind willkommen.

Mitwirken

Lesen Sie CONTRIBUTING.md, eröffnen Sie eine Forschungsfrage oder einen Designvorschlag, und halten Sie Pull-Requests fokussiert. Das Projekt begrüßt insbesondere reproduzierbare Retrieval-Benchmarks, ANN-Adapter, Tokenizer-Integrationen, Datenschutzprüfungen, Queue- und Absturztests sowie Agent-Framework-Gateways.

Lizenz

MIT © Library of Context Mitwirkende.