engram

Engram

Un kit de herramientas local de grafo de código estructural y contexto para agentes de IA. Engram indexa entidades de código fuente, relaciones de Git y memoria de proyecto seleccionada, y luego expone contexto enfocado a través de una CLI, hooks de agente, MCP y un panel local autenticado.

Úsalo para encontrar código relevante antes de leer archivos completos, inspeccionar relaciones y llevar errores registrados a una sesión posterior. Lee el código fuente devuelto por una consulta antes de hacer una afirmación sobre el comportamiento: la recuperación del grafo es una ayuda para la investigación.

Inicio rápido

El paquete inspeccionado es engramx 4.5.0 y requiere Node >=20. Este ejemplo de compilación desde el código fuente está inspeccionado desde el código fuente, no ejecutado; no asume una versión publicada actualmente del paquete o extensión.

git clone https://github.com/NickCirv/engram.git
cd engram
git checkout 9fa2a4b74ca8e66560d74d1255c16c43157d32bd
npm install --ignore-scripts
npm run build
export ENGRAM_NO_UPDATE_CHECK=1
node dist/cli.js init ../your-project --no-hook
node dist/cli.js query "authentication" --project ../your-project --budget 2000
node dist/cli.js stats --project ../your-project

Reemplaza ../your-project con un código base que puedas inspeccionar. La indexación escribe el grafo .engram/ del proyecto. La bandera --no-hook es importante: la CLI predeterminada init también instala un hook de Sentinel. Comienza con el grafo, examina la salida y luego decide qué integración habilitar. La compilación incluye el empaquetado de gramáticas; inspecciona los scripts del paquete y las dependencias antes de la instalación.

La consulta devuelve entidades de grafo coincidentes y un recuento estimado de tokens, o un mensaje de no-hay-nodos-coincidentes. Los recuentos dependen del proyecto indexado; no se fabrica ninguna salida de referencia aquí.

Qué está implementado

Flujo de trabajo	Puntos de entrada respaldados por código fuente
Explorar estructura	query, path, gods, callers, callees, impact, stats
Mantener contexto	init, watch, reindex, learn, mistakes
Generar documentos de agente	gen, gen-mdc, gen-aider, gen-windsurfrules, gen-ccs
Inspeccionar integración de hooks	install-hook --dry-run, hook-preview, hook-stats, hook-disable, hook-enable
Servir contexto	server, ui, engram-serve ejecutable MCP
Revisar mediciones	measure, bench, cost, scripts de referencia del paquete
Mantener instalación	doctor, setup --dry-run, update --check, comandos de base de datos/caché/plugins

Estos puntos de entrada están declarados en la CLI fijada. Consulta la ayuda de cada comando antes de una operación de escritura. Los generadores, instaladores de hooks, comandos de caché/base de datos e instalación de plugins pueden modificar el estado local.

Arquitectura

Los mineros de código fuente extraen entidades, referencias, co-cambios de Git e información seleccionada de errores/sesiones. El almacén de grafos persiste SQLite local del proyecto usando sql.js. Las consultas recorren el grafo y renderizan contexto acotado. El resolvedor de proveedores combina fuentes integradas y plugins/proveedores MCP opcionales; las integraciones pueden agregar procesos externos y acceso a red.

La guía de arquitectura e integración mapea estas rutas, documenta la autenticación HTTP y proporciona una configuración MCP local. Los registros de diseño existentes, notas de versión, documentos de integración y el borrador de ECP permanecen enlazados en el inventario de documentación. Conservan contexto histórico y no están todos certificados contra esta revisión.

Privacidad y límites operativos

El grafo central es local, pero no se garantiza que todo el sistema esté libre de red. La CLI tiene comprobaciones de actualización de npm, Context7 puede llamar a un envoltorio externo, y los proveedores MCP/plugins configurados pueden ejecutar sus propios procesos. ENGRAM_NO_UPDATE_CHECK=1 desactiva la ruta de comprobación de actualizaciones; no desactiva cada integración opcional. Revisa los proveedores configurados y el agente que recibe la salida del grafo.

El servidor HTTP se vincula a 127.0.0.1, valida Host/Origin y requiere un token portador o cookie de panel para rutas protegidas. Resuelve un token desde ENGRAM_API_TOKEN o un archivo de token local. Mantén ese token privado y conserva la política de seguridad existente.

Límites y medición

El tamaño del contexto estructural, las reducciones estimadas de tokens, la reproducción de sesiones y la facturación real del proveedor responden preguntas diferentes. Un paquete más pequeño no demuestra por sí mismo igual calidad de respuesta o una factura más baja. Reproduce los puntos de referencia incluidos en tu propia carga de trabajo representativa y rastrea la corrección junto con el costo. Esta revisión de documentación no ejecutó una compilación, suite de pruebas, punto de referencia o sesión de agente.

Desarrollo

npm run build
npm run lint
npm test -- --run

El repositorio contiene fuentes de pruebas unitarias y de integración para almacenamiento de grafos, proveedores, hooks, seguridad HTTP y otros módulos. Su presencia es evidencia de la intención de cobertura de pruebas; los resultados en esta revisión permanecen sin verificar aquí. Consulta la guía de contribución conservada antes de cambiar el comportamiento.

Licencia y autor

Licencia Apache-2.0. La especificación ECP lleva su propia atribución y licencia en su documento fuente; esta reescritura no altera ninguna de las dos.

Nicholas Ashkar · IA aplicada, sistemas y consultoría.

Guías de usuario

El manual de usuario cubre configuración, habilidades, solución de problemas y eliminación. Sentinel explica el comportamiento actual de los hooks y los modos de guardia. Los autores de herramientas pueden usar la guía de integración.