Contextful

Contextful

⚠️ Esto está en alfa temprana. La API, las funciones y las integraciones no son estables. Espera cambios disruptivos. ¡Los comentarios y las contribuciones son muy bienvenidos!

Gestión de contexto local + motor de búsqueda + memoria para IA agéntica.

Contextful es una capa contextual en tiempo de ejecución y un motor de búsqueda local para agentes que les ofrece una forma rápida de encontrar, comprimir, citar y recordar el contexto del proyecto.

Disponible como herramienta CLI-first con un puente de ejecución MCP e instrucciones de agente generadas, se integra sin problemas con Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue y Zed.

En lugar de hacer que un agente lea 40 archivos en cada sesión, Contextful indexa el proyecto una vez y devuelve un paquete de contexto clasificado, citado y con presupuesto de tokens.

¿Por qué?

El contexto siempre ha sido un cuello de botella para la IA agéntica. Los modelos con ventanas de contexto grandes (por ejemplo, 1M de tokens) son:

1. Costosos y requieren significativamente más cómputo y tiempo de procesamiento.
2. Más propensos a perder información clave a medida que se llena la ventana de contexto.
3. La mayoría de los proyectos tienen millones de líneas de código, pero los agentes solo pueden caber en tokens limitados por ventana de contexto.

La solución actual es hacer que el agente adivine qué archivos leer y luego pagar el costo de tokens para leerlos en cada sesión. Esto es lento, costoso y con pérdidas.

Aparte de esto, los agentes no tienen forma de almacenar o compartir aprendizajes entre sesiones. Cada vez que comienzan, olvidan todo y tienen que volver a leer el mismo contexto.

Empecé a desarrollar Contextful para mantener la ventana de contexto más pequeña habilitando una recuperación eficiente de conocimiento. Si indexamos el proyecto y devolvemos un paquete de contexto clasificado, citado y con presupuesto de tokens, podemos:

• Uso de tokens 100 veces más eficiente: dejar de pagar tokens para volver a leer los mismos archivos.
• Menos llamadas a herramientas: un paquete de contexto puede reemplazar docenas de llamadas a grep, glob y lectura de archivos.
• Sin pérdida de contexto entre sesiones: los agentes pueden almacenar aprendizajes de sesión en un libro de memoria respaldado por evidencia.
• Conocimiento del proyecto compartible: las lecciones y los paquetes de contexto sobreviven a la compactación de contexto y a sesiones futuras.

Características clave

1. Gestión de contexto

El almacén local predeterminado es SQLite con búsqueda respaldada por FTS y tablas de grafo tipadas. V1 incluye:

• SQLite como almacén local predeterminado.
• Búsqueda léxica/BM25 con FTS5.
• Tablas de grafo tipadas: nodes, edges, node_props, edge_props.
• Una caché de adyacencia activa para relaciones de grafo comunes.
• Huellas estructurales deterministas inspiradas en señales de reordenamiento secundario estilo Code2Vec.

Las próximas mejoras de almacenamiento son vectores semánticos opcionales mediante sqlite-vec, LanceDB o HNSW local, y listas de adyacencia comprimidas con mapas de bits Roaring o arreglos CSR para repositorios más grandes.

2. Motor de búsqueda

Contextful analiza la consulta, clasifica la intención y combina búsqueda léxica, símbolos, documentos, relaciones de grafo y coincidencias de memoria para recuperar la evidencia correcta. El objetivo es una búsqueda de proyectos a nivel de Google para agentes: consultas vagas como "recursos para la incorporación de autenticación" deberían aterrizar en el código, los documentos y las lecciones previas correctos.

3. Libro de memoria

Los agentes pueden almacenar lecciones, decisiones y datos útiles del proyecto, pero no como notas sueltas de "recuerda esto". Cada memoria requiere referencias de evidencia de archivos, símbolos, commits o paquetes de contexto previos. Cuando la evidencia cambia, Contextful marca la memoria como obsoleta.

4. Ejecución de Contextful

Contextful es un servidor MCP, un indexador local y un pequeño CLI:

• Servidor MCP: la interfaz del agente.
• Demonio / observador local: indexación, reconstrucciones, frescura y benchmarks futuros.
• CLI (cxf): configuración humana, indexación, búsqueda, escrituras de memoria y pruebas de humo locales.

MCP es la interfaz correcta porque las herramientas, los recursos y los prompts son exactamente lo que MCP estandariza. El agente solicita contexto; Contextful devuelve evidencia compacta.

Instalación

npx @inferensys/contextful init --workspace .
npx @inferensys/contextful search "where is user auth handled" --workspace . --budget 2000

Ejecutar como servidor MCP:

npx @inferensys/contextful server

CLI

El binario principal es cxf; contextful también se proporciona como un alias legible.

cxf init --workspace <path>
cxf index --workspace <path> [--watch]
cxf daemon --workspace <path>
cxf search "<query>" --workspace <path> --budget 2000 --json
cxf memory add --workspace <path> --claim <text> --evidence <ref>
cxf server

Herramientas MCP principales

Mantén la superficie del agente pequeña:

• context_pack(query, budget, scope) - la herramienta estrella. Devuelve un paquete clasificado, citado y con presupuesto de tokens en lugar de forzar 40 lecturas aleatorias de archivos.
• search_code(query, mode, filters) - potente búsqueda de código, documentos, símbolos y memoria.
• trace_path(from, to, edge_types) - recorrido de grafo a través de archivos, símbolos, módulos y configuración.
• impact_analysis(symbol_or_file) - dependencias inversas y pruebas probables.
• why_changed(symbol_or_file) - evidencia actual más historial de git.
• recall_memory(query, scope) - buscar aprendizajes de sesión y lecciones duraderas del proyecto.
• write_lesson(claim, evidence_refs, scope) - almacenar una memoria respaldada por evidencia.

Configuración del cliente MCP

Usa este comando de servidor stdio en cualquier herramienta de codificación compatible con MCP:

{
  "mcpServers": {
    "contextful": {
      "command": "npx",
      "args": ["-y", "@inferensys/contextful", "server"]
    }
  }
}

Codex:

codex mcp add contextful -- npx -y @inferensys/contextful server

Flujo de agente CLI-first

Usa cxf init una vez por espacio de trabajo. Indexa el proyecto y escribe .contextful/AGENT_INSTRUCTIONS.md, una guía compacta estilo skill que indica a los agentes cuándo llamar a context_pack, cuándo buscar de forma más específica y cuándo se permiten escrituras de memoria.

Usa cxf search cuando una persona quiera probar el mismo paquete de evidencia que recibirá un agente:

cxf search "how does auth load user profiles?" --workspace . --budget 2000

El servidor MCP sigue siendo la interfaz del agente. El CLI es para configuración, inspección y pruebas locales repetibles.

Privacidad

V1 es solo local. No llama a APIs de embeddings externas, no sube código fuente, no edita archivos fuente, no corrige código automáticamente ni instala dependencias dentro del espacio de trabajo objetivo.

Referencias de evidencia

Las escrituras de memoria requieren referencias de evidencia devueltas por la búsqueda o los paquetes de contexto:

• file:src/auth.ts:10-40
• symbol:src/auth.ts#AuthService:12
• pack:ctx_...

La evidencia inválida u obsoleta se rechaza o se marca como obsoleta.