Library of Context

{"type": "text"}# Библиотека контекста

Виртуальная память для контекста ИИ: долговечная вне модели, ограниченная внутри неё.

У модели ИИ конечное собственное окно контекста. Длинные разговоры со временем расширяются, пока старая информация не будет усечена или сжата. Для вызовов, проходящих через её контекстный губернатор, Библиотека сохраняет каждое записанное событие в SQLite и собирает ограниченный запрос к модели из защищённых событий, недавних событий и извлечённых записей.

Представьте окно контекста модели как письменный стол. Библиотека может вместить гораздо больше книг, чем стол, но библиотекарь раскладывает только те книги, которые нужны для текущей задачи. Смена задачи заменяет стол; она не добавляет больше книг поверх.

[!ВАЖНО] Этот проект расширяет адресуемый контекст, а не физический предел окна контекста модели. Он предназначен для локальных прототипов и совместной работы, а не как производственный многопользовательский сервис памяти. См. Статус возможностей для явных границ поддержки.

Чем это отличается от обычного сжатия

Обычное сжатие превращает растущий транскрипт в меньший, с потерями, и может оставить исходные детали вне активного рабочего процесса. Библиотека использует обратимые семантические страницы:

traditional:  growing transcript -> compacted transcript -> continue

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

Исходные события можно просматривать и восстанавливать. Резюме могут стать навигационными помощниками, но им не обязательно быть единственной сохранившейся копией.

Ландшафт связанных работ сравнивает эту конструкцию с методами длинного контекста модели, поиском, сжатием подсказок, сжатием провайдера, памятью агента, контрольными точками и разбиением на страницы во время вывода. Здесь «сжатие» означает меньшее, потенциально с потерями представление продолжения, чьи оригиналы не являются независимо адресуемыми, если другой слой не сохраняет их.

Related MCP server: local-memory-mcp

Возможности

• Контекстный губернатор с операциями жизненного цикла prepare -> model call -> commit.

• Долговечные события потока в SQLite и транзакционный исходящий индекс.

• Ориентированное на токены, ограниченное по событиям кольцо недавних событий для немедленного поведения «читай свой контекст»; слишком большое событие усекается только в конверте модели, а не на диске.

• Ограниченное рабочее кольцо с долговечным исходящим SQLite для переполнения и восстановления после перезапуска.

• Защищённый контекст для инструкций, решений, активных планов и нерешённого состояния.

• Записанные, встроенные и индексированные водяные знаки со статусом очереди.

• Свежие, ограниченные конверты подсказок, заменяющие рост транскрипта.

• Гибридный векторный поиск, SQLite FTS5, важность и недавность.

• Ограниченная по байтам память процесса и необязательные одноразовые локальные горячие уровни Redis.

• Отчёты о замене письменного стола: swapped_in, swapped_out и retained.

• Python, локальный HTTP, CLI и STDIO MCP интерфейсы интеграции.

• Хеширование вложений без зависимостей и необязательный локальный адаптер Ollama.

Губернатор автоматический, когда ваш агент или шлюз модели направляет каждый ход через него. Интеграция только через MCP является кооперативной: хост может использовать инструменты полок и письменного стола, но не может переписать запрос модели, который уже вызвал инструмент, или заменить недокументированный внутренний хук сжатия.

Архитектура с первого взгляда

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

Быстрый старт

Конфигурация по умолчанию требует только Python 3.11 или новее. Redis необязателен.

В 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

В macOS или 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

Быстрый старт проверяет защиту, сборку подсказок, запись событий, индексацию и очистку с временной базой данных. Он не использует Redis, Docker, облачные сервисы или API модели. Продолжите с руководством по установке.

Добавьте это к агенту, который вы уже запускаете

См. Добавьте Библиотеку к вашему агенту для примеров конфигурации Codex, Python и HTTP. После настройки MCP-сервера перезапустите клиент или начните отдельный сеанс; конфигурация не влияет на уже идущий чат.

Запустите автоматически управляемого текстового агента на Python

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"])

Обратный вызов должен отправлять ровно предоставленные messages; он не должен добавлять другой транскрипт или продолжать управляемый провайдером разговор. Встроенный адаптер предназначен только для текста. Структурированные вызовы инструментов, потоки, вложения и мультимодальный контент требуют пользовательского адаптера сериализации.

См. Контекстный губернатор для полного протокола.

Интеграция MCP

Для обычного MCP-агента используйте изолированный шаблон проекта и готовые к слиянию инструкции агента в integrations/README.md. Это кооперативная память; она не контролирует собственный транскрипт хоста.

Сырой локальный STDIO-сервер можно проверить с помощью:

python -m library_of_context.mcp_server --no-redis

Пользовательские MCP-шлюзы, владеющие границей вызова модели, могут использовать:

Библиотека предоставляет инструменты полок, поиска, письменного стола, сеансов без состояния и губернатора. Включайте инструменты только для шлюза только в хосте, который отправляет возвращённые messages как полный следующий запрос модели.

Локальный HTTP API

python -m library_of_context --no-redis serve

Эндпоинты губернатора:

Маршруты /books, /library/ingest, /catalog/query и /desk/* предоставляют низкоуровневую библиотеку. Сервер привязывается к loopback и не имеет аутентификации. Не открывайте его напрямую для другой машины.

Иерархия хранения

1. Кольцо недавних событий: упорядоченные события потока, ограниченные количеством событий и целевым количеством токенов. Одно слишком большое событие может оставаться резидентным, чтобы свежий контекст был виден; сборка подсказки усекает его видимую моделью часть до жёсткого бюджета конверта. Это не LRU; порядок разговора важен.

2. Память процесса: ограниченная по байтам LRU для горячих книг и результатов поиска.

3. Локальный Redis: необязательный общий кэш для горячих книг, запросов, столов, TTL и поколений инвалидации.

4. SQLite: авторитетные события, исходящие, текст, метаданные, FTS и векторное хранилище.

Redis одноразовый. Конфигурация локального Redis по умолчанию не является долговечным брокером сообщений и не должна использоваться как поток событий команды.

Бесплатный локальный Redis в Windows

Docker и облачная учётная запись не требуются. Включённый скрипт PowerShell устанавливает службу Redis внутри Ubuntu WSL. Требуются WSL 2, дистрибутив Ubuntu и 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 открывает настроенную базу данных SQLite, проверяя уровни хранения. Пример выше создаёт data/redis-check.sqlite.

Используйте --no-redis везде, если достаточно SQLite плюс память процесса.

Пределы производительности

Сборка подсказок ограничена, а записанные события используют транзакционный исходящий. FTS возвращает ограниченный набор кандидатов, в то время как векторный поиск точно оценивает каждую живую запись в пространстве имён. Поэтому заявления о масштабе для больших каталогов требуют измеренных доказательств и, когда точный путь пересекает объявленный предел, ограниченного адаптера векторного поиска.

Производительность и масштабирование определяет измерения, критерии SLO и контрольные вопросы. Почему эти улучшения? сравнивает более простые альтернативы, триггеры внедрения и контрольные точки доказательств, в то время как Дорожная карта упорядочивает условную работу.

Документация

Помогите сформировать дизайн

Открытые вопросы дизайна включают:

• Какой контекст следует защищать автоматически, и кто может его освобождать?

• Как следует измерять качество поиска для потоков агентов, а не для QA документов?

• Какой локальный адаптер ANN подходит для 100 000–1 000 000 фрагментов?

• Как ветви должны наследовать, заменять и объединять контекст?

• Какие знания безопасно и полезно продвигать из приватного потока в командный каталог?

• Должна ли общая плоскость событий использовать Redis Streams, NATS JetStream или другой брокер?

• Как отзыв ACL должен инвалидировать локальные кеши, не помещая облако в критический путь подсказки?

• Какая политика токен-давления кажется предсказуемой пользователям на разных токенизаторах моделей?

Более полный список — в ROADMAP.md. Приветствуются вопросы, результаты бенчмарков, заметки по дизайну, адаптеры, тесты на сбои и критика.

Вклад

Прочитайте CONTRIBUTING.md, откройте исследовательский вопрос или предложение по дизайну и держите pull request сфокусированным. Проект особенно приветствует воспроизводимые бенчмарки поиска, адаптеры ANN, интеграции токенизаторов, проверки конфиденциальности, тесты очередей и сбоев, а также шлюзы агентных фреймворков.

Лицензия

MIT © участники Library of Context.