engram

Engram

Um kit de ferramentas local de grafo de código estrutural e contexto para agentes de IA de codificação. O Engram indexa entidades de código-fonte, relacionamentos Git e memória selecionada de projeto, e então expõe contexto focado por meio de uma CLI, hooks de agente, MCP e um painel local autenticado.

Use-o para encontrar código relevante antes de ler arquivos completos, inspecionar relacionamentos e carregar erros registrados para uma sessão posterior. Leia o código-fonte retornado por uma consulta antes de fazer uma afirmação comportamental: a recuperação por grafo é um auxílio à investigação.

Início rápido

O pacote inspecionado é engramx 4.5.0 e requer Node >=20. Este exemplo de build a partir do código-fonte é inspecionado no código-fonte, não executado; ele não assume um pacote ou versão de extensão atualmente publicado.

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

Substitua ../your-project por um código-fonte que você possa inspecionar. A indexação grava o grafo .engram/ do projeto. A flag --no-hook é importante: a CLI padrão init também instala um hook do Sentinel. Comece com o grafo, examine a saída e então decida qual integração habilitar. O build inclui empacotamento de gramática; inspecione scripts e dependências do pacote antes da instalação.

A consulta retorna entidades de grafo correspondentes e uma estimativa de contagem de tokens, ou uma mensagem de nenhum nó correspondente. As contagens dependem do projeto indexado; nenhuma saída de benchmark é fabricada aqui.

O que está implementado

Fluxo de trabalho	Pontos de entrada baseados no código-fonte
Explorar estrutura	query, path, gods, callers, callees, impact, stats
Manter contexto	init, watch, reindex, learn, mistakes
Gerar documentos de agente	gen, gen-mdc, gen-aider, gen-windsurfrules, gen-ccs
Inspecionar integração de hook	install-hook --dry-run, hook-preview, hook-stats, hook-disable, hook-enable
Servir contexto	server, ui, engram-serve executável MCP
Revisar medições	measure, bench, cost, scripts de benchmark do pacote
Manter instalação	doctor, setup --dry-run, update --check, comandos de banco/cache/plugin

Esses pontos de entrada são declarados na CLI fixada. Consulte a ajuda de cada comando antes de uma operação de escrita. Geradores, instaladores de hook, comandos de cache/banco e instalação de plugins podem modificar o estado local.

Arquitetura

Miners de código-fonte extraem entidades, referências, co-mudança Git e informações selecionadas de erro/sessão. O armazenamento de grafo persiste SQLite local do projeto usando sql.js. Consultas percorrem o grafo e renderizam contexto limitado. O resolvedor de provedores combina fontes integradas e plugins/provedores MCP opcionais; integrações podem adicionar processos externos e acesso à rede.

O guia de arquitetura e integração mapeia esses caminhos, documenta autenticação HTTP e fornece uma configuração MCP local. Registros de design existentes, notas de versão, documentos de integração e o rascunho ECP permanecem vinculados no inventário de documentação. Eles retêm contexto histórico e não são todos certificados contra esta revisão.

Privacidade e limites operacionais

O grafo principal é local, mas todo o sistema não é garantido como livre de rede. A CLI tem verificações de atualização npm, o Context7 pode chamar um wrapper externo, e provedores MCP/plugin configurados podem executar seus próprios processos. ENGRAM_NO_UPDATE_CHECK=1 desativa o caminho de verificação de atualização; ele não desativa toda integração opcional. Revise os provedores configurados e o agente que recebe a saída do grafo.

O servidor HTTP vincula-se a 127.0.0.1, valida Host/Origin e exige um token bearer ou cookie de painel para rotas protegidas. Ele resolve um token de ENGRAM_API_TOKEN ou de um arquivo de token local. Mantenha esse token privado e preserve a política de segurança existente.

Limites e medição

O tamanho do contexto estrutural, reduções estimadas de tokens, reprodução de sessão e cobrança real do provedor respondem a perguntas diferentes. Um pacote menor não demonstra por si só qualidade de resposta igual ou conta menor. Reproduza os benchmarks incluídos em sua própria carga de trabalho representativa e acompanhe a correção junto com o custo. Esta revisão de documentação não executou build, suíte de testes, benchmark ou sessão de agente.

Desenvolvimento

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

O repositório contém fontes de teste de unidade e integração para armazenamento de grafo, provedores, hooks, segurança HTTP e outros módulos. Sua presença é evidência de intenção de cobertura de teste; resultados nesta revisão permanecem não verificados aqui. Consulte o guia de contribuição preservado antes de alterar o comportamento.

Licença e autor

Licença Apache-2.0. A especificação ECP carrega sua própria atribuição e licenciamento em seu documento-fonte; esta reescrita não altera nenhum dos dois.

Nicholas Ashkar · IA aplicada, sistemas e consultoria.

Guias do usuário

O manual do usuário cobre configuração, habilidades, solução de problemas e remoção. O Sentinel explica o comportamento atual do hook e modos de guarda. Autores de ferramentas podem usar o guia de integração.