La Biblioteca de Contexto

Memoria virtual para el contexto de IA: duradera fuera del modelo, limitada dentro de él.

Un modelo de IA tiene una ventana de contexto nativa finita. Las conversaciones largas eventualmente se expanden hasta que la información antigua se trunca o compacta. Para las llamadas enrutadas a través de su gobernador de contexto, la Biblioteca almacena cada evento registrado en SQLite y ensambla una solicitud de modelo limitada a partir de eventos protegidos, eventos recientes y registros recuperados.

Piense en la ventana de contexto del modelo como un escritorio de lectura. La Biblioteca puede contener muchos más libros que el escritorio, pero el bibliotecario coloca solo los libros necesarios para la tarea actual. Cambiar la tarea reemplaza el escritorio; no apila más libros encima.

[!IMPORTANTE] Este proyecto expande el contexto direccionable, no el límite físico de la ventana de contexto de un modelo. Está destinado a prototipos locales y colaboración, no como un servicio de memoria multiinquilino de producción. Consulte Estado de capacidades para conocer los límites de soporte explícitos.

Por qué esto es diferente de la compactación ordinaria

La compactación convencional convierte una transcripción creciente en una continuación más pequeña y con pérdidas y puede dejar los detalles originales fuera del flujo de trabajo activo. La Biblioteca utiliza paginación semántica reversible:

traditional:  growing transcript -> compacted transcript -> continue

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

Los eventos originales son inspeccionables y recuperables. Los resúmenes pueden convertirse en ayudas de navegación, pero no necesitan ser la única copia superviviente.

El panorama de trabajos relacionados compara este diseño con métodos de contexto largo de modelos, recuperación, compresión de indicaciones, compactación de proveedores, memoria de agentes, puntos de control y paginación en tiempo de inferencia. Aquí, "compactación" significa una representación de continuación más pequeña y potencialmente con pérdidas cuyos originales no son direccionables de forma independiente a menos que otra capa los retenga.

Related MCP server: local-memory-mcp

Capacidades

• Un gobernador de contexto con operaciones de ciclo de vida prepare -> llamada al modelo -> commit.

• Eventos de hilo SQLite duraderos y una bandeja de salida de indexación transaccional.

• Un anillo reciente limitado por tokens y eventos para un comportamiento inmediato de lectura del propio contexto; un evento sobredimensionado se trunca solo en el sobre del modelo, no en disco.

• Un anillo de trabajo limitado con una bandeja de salida SQLite duradera para desbordamiento y recuperación de reinicio.

• Contexto protegido para instrucciones, decisiones, planes activos y estado no resuelto.

• Marcas de agua registradas, incrustadas e indexadas con estado de salud de la cola.

• Sobres de indicaciones frescos y limitados que reemplazan el crecimiento de la transcripción.

• Recuperación híbrida por vectores, FTS5 de SQLite, importancia y recencia.

• RAM de proceso limitada por bytes y niveles de caché locales Redis desechables opcionales.

• Informes de intercambio de escritorio de lectura: swapped_in, swapped_out y retained.

• Superficies de integración Python, HTTP local, CLI y STDIO MCP.

• Incrustaciones hash sin dependencias y un adaptador local opcional de Ollama.

El gobernador es automático cuando su agente o puerta de enlace de modelo enruta cada turno a través de él. Una integración solo MCP es cooperativa: el host puede usar herramientas de estantería y escritorio de lectura, pero no puede reescribir la solicitud de modelo que ya invocó una herramienta ni reemplazar un gancho de compactación interno no documentado.

Arquitectura de un vistazo

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

Inicio rápido

La configuración predeterminada solo requiere Python 3.11 o superior. Redis es opcional.

En 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

En macOS o 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

El inicio rápido ejercita la protección, el ensamblaje de indicaciones, el registro de eventos, la indexación y la limpieza con una base de datos temporal. No usa Redis, Docker, servicio en la nube ni API de modelo. Continúe con la guía de instalación.

Añádelo a un agente que ya ejecutes

Consulte Añade la Biblioteca a tu agente para ejemplos de configuración de Codex, Python y HTTP. Después de la configuración del servidor MCP, reinicie el cliente o comience una sesión separada; la configuración no afecta a un chat ya en curso.

Ejecutar un agente de texto Python gobernado automáticamente

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

La devolución de llamada debe enviar exactamente los messages suministrados; no debe añadir otra transcripción ni continuar una conversación gestionada por el proveedor. El adaptador integrado es solo de texto. Las llamadas a herramientas estructuradas, flujos, adjuntos y contenido multimodal necesitan un adaptador de serialización personalizado.

Consulte Gobernador de contexto para el protocolo completo.

Integración MCP

Para un agente MCP normal, use la plantilla aislada del proyecto y las instrucciones de agente listas para fusionar en integrations/README.md. Esto es memoria cooperativa; no controla la transcripción nativa del host.

El servidor STDIO local sin procesar se puede inspeccionar con:

python -m library_of_context.mcp_server --no-redis

Las puertas de enlace MCP personalizadas que poseen el límite de llamada al modelo pueden usar:

La Biblioteca expone herramientas de estantería, recuperación, escritorio de lectura, sesión sin estado y gobernador. Habilite las herramientas solo de puerta de enlace únicamente en un host que envíe los messages devueltos como la siguiente solicitud de modelo completa.

API HTTP local

python -m library_of_context --no-redis serve

Los endpoints del gobernador son:

Las rutas /books, /library/ingest, /catalog/query y /desk/* exponen la biblioteca de nivel inferior. El servidor se vincula a loopback y no tiene autenticación. No lo exponga directamente a otra máquina.

Jerarquía de almacenamiento

1. Anillo reciente: eventos ordenados por hilo, limitados por número de eventos y un objetivo de tokens estimado. Un evento sobredimensionado puede permanecer residente para que el contexto fresco sea visible; el ensamblaje de indicaciones trunca su vista visible al modelo al presupuesto duro del sobre. Esto no es un LRU; el orden de la conversación importa.

2. RAM de proceso: LRU limitado por bytes para libros calientes y resultados de recuperación.

3. Redis local: caché compartida opcional para libros calientes, consultas, escritorios, TTL y generaciones de invalidación.

4. SQLite: eventos autoritativos, bandeja de salida, texto, metadatos, FTS y almacenamiento vectorial.

Redis es desechable. La configuración local de Redis predeterminada no es un corredor de mensajes duradero y no debe usarse como el flujo de eventos del equipo.

Redis local gratuito en Windows

No se requieren Docker ni una cuenta en la nube. El script de PowerShell incluido instala un servicio de Redis dentro de Ubuntu WSL. Requiere WSL 2, una distribución de Ubuntu y 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 abre la base de datos SQLite configurada mientras verifica los niveles de almacenamiento. El ejemplo anterior crea data/redis-check.sqlite.

Use --no-redis en todas partes si SQLite más RAM de proceso es suficiente.

Límites de rendimiento

El ensamblaje de indicaciones está limitado y los eventos registrados usan una bandeja de salida transaccional. FTS devuelve un conjunto de candidatos limitado, mientras que la recuperación vectorial puntúa exactamente cada registro vivo en un espacio de nombres. Las afirmaciones de escala de catálogos grandes requieren evidencia medida y, cuando la ruta exacta cruza un límite declarado, un adaptador de búsqueda vectorial limitado.

Rendimiento y escalado define mediciones, criterios de SLO y preguntas de referencia. ¿Por qué estas mejoras? compara alternativas más simples, desencadenantes de adopción y puertas de evidencia, mientras que la Hoja de ruta secuencia el trabajo condicional.

Documentación

Ayuda a dar forma al diseño

Las preguntas de diseño abiertas incluyen:

• ¿Qué contexto debería protegerse automáticamente y quién puede liberarlo?

• ¿Cómo debería medirse la calidad de la recuperación para hilos de agentes en lugar de QA de documentos?

• ¿Cuál es el adaptador ANN local adecuado para entre 100 000 y 1 000 000 de fragmentos?

• ¿Cómo deberían las ramas heredar, sustituir y fusionar el contexto?

• ¿Qué conocimiento es seguro y útil promover de un hilo privado a un catálogo de equipo?

• ¿Debería el plano de eventos compartido usar Redis Streams, NATS JetStream u otro broker?

• ¿Cómo debería la revocación de ACL invalidar las cachés locales sin poner la nube en la ruta crítica del prompt?

• ¿Qué política de presión de tokens resulta predecible para los usuarios en distintos tokenizadores de modelos?

La lista más extensa está en ROADMAP.md. Se aceptan preguntas, resultados de benchmarks, notas de diseño, adaptadores, pruebas de fallos y críticas.

Contribuciones

Lee CONTRIBUTING.md, abre una pregunta de investigación o propuesta de diseño, y mantén las pull requests enfocadas. El proyecto da la bienvenida especialmente a los benchmarks de recuperación reproducibles, adaptadores ANN, integraciones de tokenizadores, revisiones de privacidad, pruebas de colas y fallos, y pasarelas de frameworks de agentes.

Licencia

MIT © colaboradores de Library of Context.| Documento | Propósito | | ---------------------------------------------------------- | --------------------------------------------------------------------- | | Arquitectura | Invariantes, niveles, consistencia y evolución | | Trabajo relacionado y panorama de diseño | Comparación de fuentes primarias con enfoques adyacentes de contexto y memoria | | Gobernador de contexto | Protocolo de preparación/confirmación y comportamiento ante fallos | | Estado de capacidades | Límites implementados, experimentales, planificados y no admitidos | | Explicador del sistema | Recorrido visual didáctico | | Rendimiento y escalado | Evidencia de auditoría, NFRs y umbrales de benchmark | | ¿Por qué estas mejoras? | Justificación, contraargumentos, alternativas y desencadenantes de adopción | | Arquitectura de equipo | Colaboración local-primero y diseño de promoción | | Hoja de ruta | Hitos y preguntas de investigación abiertas | | Plantilla de informe de decisión | Formato obligatorio de «por qué / por qué no / evidencia» para propuestas importantes | | Contribuciones | Flujo de trabajo de desarrollo y áreas de contribución | | Seguridad | Modelo de amenazas e informe de vulnerabilidades |

Ayuda a dar forma al diseño

Las preguntas de diseño abiertas incluyen:

• ¿Qué contexto debería protegerse automáticamente y quién puede liberarlo?

• ¿Cómo debería medirse la calidad de la recuperación para hilos de agentes en lugar de QA de documentos?

• ¿Cuál es el adaptador ANN local adecuado para entre 100 000 y 1 000 000 de fragmentos?

• ¿Cómo deberían las ramas heredar, sustituir y fusionar el contexto?

• ¿Qué conocimiento es seguro y útil promover de un hilo privado a un catálogo de equipo?

• ¿Debería el plano de eventos compartido usar Redis Streams, NATS JetStream u otro broker?

• ¿Cómo debería la revocación de ACL invalidar las cachés locales sin poner la nube en la ruta crítica del prompt?

• ¿Qué política de presión de tokens resulta predecible para los usuarios en distintos tokenizadores de modelos?

La lista más extensa está en ROADMAP.md. Se aceptan preguntas, resultados de benchmarks, notas de diseño, adaptadores, pruebas de fallos y críticas.

Contribuciones

Lee CONTRIBUTING.md, abre una pregunta de investigación o propuesta de diseño, y mantén las pull requests enfocadas. El proyecto da la bienvenida especialmente a los benchmarks de recuperación reproducibles, adaptadores ANN, integraciones de tokenizadores, revisiones de privacidad, pruebas de colas y fallos, y pasarelas de frameworks de agentes.

Licencia

MIT © colaboradores de Library of Context.