Engram

Previne regressão fornecendo dados de Blast Radius para IA com base no seu histórico do git

GitHub
6
Experimente este MCPPatrocinado

Documentação

Engram

O Motor de "Contexto Ausente" para Agentes de IA.

Engram dá ao seu agente de IA o contexto que ele não consegue ver apenas no código.

Embora os LLMs sejam excelentes em analisar os arquivos específicos que você fornece, eles não têm o contexto mais amplo do histórico e das diretrizes do seu repositório. Engram preenche essa lacuna ao revelar dependências ocultas (via histórico do git) e comportamentos exigidos (via intenções de teste) que a IA não teria acesso, perderia ou ignoraria.

Por que Engram?

  • Histórico Temporal: Responde "O que geralmente muda quando este arquivo muda?" para evitar o ciclo de "consertar uma coisa, quebrar outra".
  • Intenção de Teste: Extrai strings de intenção de teste (ex.: "should handle negative balance") para que a IA entenda qual comportamento preservar.
  • Memória Organizacional: Um armazenamento persistente para você ou o LLM registrar restrições arquiteturais não documentadas, garantindo que as lições aprendidas não se percam ao iniciar uma nova conversa.

Feito para Privacidade. Público para Integridade.

  • Local-Primeiro: Todo o processamento acontece no seu hardware local.
  • Zero Telemetria: Não rastreamos seu uso, seu código ou sua identidade.
  • Audite você mesmo: O código-fonte está disponível abaixo.

Exemplo do Mundo Real: O Bug que os Testes Não Conseguem Pegar

Um serviço TypeScript (TransactionExportService) escreve linhas delimitadas por pipe como TXN-001|2024-11-15|250.00|COMPLETED.

Um cron job JavaScript legado (legacy-mainframe-sync.js) os analisa usando índices de array codificados - parts[2] para o valor, parts[3] para o status.

Não há imports entre eles. Sem tipos compartilhados. Nada no código os conecta.

A tarefa: "Adicione um campo currency ao lado do valor."

Sem Engram

O agente de IA atualiza o serviço TypeScript e os testes. O formato de exportação se torna ID|DATE|AMOUNT|CURRENCY|STATUS. Todos os testes passam. O PR é enviado.

O problema: O script legado ainda lê parts[3] esperando um status como COMPLETED - mas agora recebe USD. parseFloat("USD") retorna NaN. O mainframe recebe dados corrompidos. Nada falhou. Nada alertou. Quebra silenciosa em produção.

Com Engram

Antes de escrever qualquer código, o agente chama get_impact_analysis. Engram verifica o histórico do git e retorna:

Risco Crítico (0.99): bin/legacy-mainframe-sync.js — Alterados juntos em 21 de 21 commits (100%)

O agente lê o arquivo sinalizado, encontra o parser posicional e atualiza ambos os arquivos juntos. Mesma funcionalidade, zero quebras.

Após a correção, o agente chama save_project_note:

"O formato da linha de exportação é consumido por bin/legacy-mainframe-sync.js usando índices posicionais codificados. Qualquer alteração na ordem dos campos DEVE ser espelhada lá. Formato atual: ID|DATE|AMOUNT|CURRENCY|STATUS (índices 0-4)."

Agora todo agente futuro recebe esse aviso automaticamente - antes de escrever uma única linha de código.

O Que Ele Faz

1. Grafo Temporal

  • O quê: Minera o histórico do git para encontrar arquivos que são frequentemente commitados junto com o seu arquivo alvo.
  • Por quê: Para revelar dependências ocultas. Se A.ts e B.ts mudaram juntos 40 vezes no último ano, sua IA precisa saber sobre B.ts antes de editar A.ts.

2. Grafo de Validação

  • O quê: Localiza automaticamente testes relevantes e extrai suas strings de intenção específicas (ex.: it("should validate JWT expiration")).
  • Por quê: Para fornecer diretrizes comportamentais. A IA pode verificar seu plano contra seus requisitos de teste existentes sem precisar ler toda a suíte de testes.
  • Frameworks Suportados:
    • JS/TS: Vitest, Jest, Mocha, Playwright, Cypress (it, test, describe)
    • JVM (Java/Kotlin/Scala): JUnit 4, JUnit 5 (@DisplayName), Kotest, ScalaTest
    • Rust: Nativo #[test]
    • Python: Pytest, Unittest (def test_...)
    • Go: Nativo func Test...

3. Grafo de Conhecimento

  • O quê: Um armazenamento persistente onde o LLM pode salvar/recuperar "memórias" sobre decisões arquiteturais, casos extremos ou peculiaridades do projeto.
  • Por quê: Para preencher a lacuna entre sessões. Se a IA aprender que "Auth requer reinicialização ao alterar a configuração", ela salva essa nota para que o próximo agente de IA também saiba.

Chamadas de Ferramentas

1. get_impact_analysis - Cálculo do raio de impacto para um arquivo alvo

Para um determinado arquivo, retorna os arquivos impactados, suas intenções de teste e quaisquer notas armazenadas.

Exemplo:

{
  "file_path": "src/Auth.ts",
  "repo_root": "/path/to/repo"
}

Retorna:

{
  "summary": "Changing src/Auth.ts may affect 2 files. 1 critical risk, 1 medium risk.\n\n⚠️ Critical Risk (0.89): src/Session.ts\n   Changed together in 48 of 50 commits (96%)\n   Notes: Session requires Redis connection\n\n⚠ High Risk (0.72): src/Auth.test.ts\n   Changed together in 31 of 50 commits (62%)\n   Current test behaviour (may need updating):\n     - should login with valid credentials\n     - should reject invalid password\n     - should handle OAuth callback",
  "formatted_files": [
    {
      "path": "src/Session.ts",
      "risk_level": "Critical",
      "risk_score": 0.89,
      "description": "Changed together in 48 of 50 commits (96%)",
      "memories": ["Session requires Redis connection"]
    },
    {
      "path": "src/Auth.test.ts",
      "risk_level": "High",
      "risk_score": 0.72,
      "description": "Changed together in 31 of 50 commits (62%)",
      "test_intents": [
        "should login with valid credentials",
        "should reject invalid password",
        "should handle OAuth callback"
      ]
    }
  ],
  "coupled_files": [...],
  "commit_count": 50
}

2. save_project_note - Lembrar contexto sobre arquivos

Armazena notas persistentes que aparecem automaticamente em futuras análises de impacto.

Exemplo:

{
  "file_path": "src/Auth.ts",
  "note": "Uses JWT tokens, must validate expiry timestamp",
  "repo_root": "/path/to/repo"
}

3. read_project_notes - Recuperar contexto salvo

Busca notas por conteúdo ou caminho de arquivo, ou lista todo o conhecimento do projeto.

Exemplo:

{
  "query": "Redis",
  "repo_root": "/path/to/repo"
}

Desempenho

Engram é construído para ser invisível até que você precise. Ele usa uma Estratégia de Indexação Adaptativa que respeita sua CPU e escala de projetos paralelos a monorepos massivos.

Benchmark contra o Linux Kernel

Levamos desempenho a sério. Engram é submetido a benchmark contra o repositório Linux Kernel (1,2 milhão+ de commits).

Metas de Desempenho

Repositórios Padrão (A Maioria dos Projetos)

  • Primeira Execução: < 2 segundos (Indexação histórica completa)
  • Execuções Posteriores: < 200ms

Repositórios Massivos (ex.: Linux Kernel)

  • Primeira Execução (por arquivo): < 2 segundos (Indexação filtrada por caminho)
  • Execuções Posteriores: < 200ms

Arquitetura

┌─────────────┐
│ AI Agent    │ ← MCP protocol over stdio
└──────┬──────┘
       │
┌──────▼──────────────┐
│ Node.js Adapter     │ ← TypeScript MCP server
│ (adapter/)          │
└──────┬──────────────┘
       │ spawns & communicates via JSON
┌──────▼──────────────┐
│ Rust Core Binary    │ ← Fast git indexing + SQLite
│ (core/)             │
└──────┬──────────────┘
       │ reads
┌──────▼──────────────┐
│ .engram/engram.db   │ ← Persistent SQLite database
└─────────────────────┘

Por Dentro

  • Estratégia Adaptativa: Engram detecta automaticamente o tamanho do repositório. Para repositórios pequenos, indexa tudo. Para repositórios massivos, alterna para uma estratégia filtrada por caminho para evitar bloquear o agente.
  • Baixa Pegada: Sem daemons pesados em segundo plano. A indexação acontece sob demanda dentro de orçamentos de tempo rigorosos, utilizando rusqlite e modo WAL para concorrência de alto rendimento.
  • Filtragem Inteligente: Ignora automaticamente ruídos como lockfiles, ativos binários e código gerado automaticamente para manter o sinal alto.

Configuração

Engram é um servidor MCP e funciona com qualquer cliente compatível com MCP.

Claude Code

claude mcp add --scope user --transport stdio engram -- npx -y @spectra-g/engram-adapter

Cursor

Configurações > Geral > Servidores MCP > Adicionar Novo Servidor MCP:

  • Nome: engram
  • Tipo: command
  • Comando: npx -y @spectra-g/engram-adapter

Instrução de Sistema (Recomendado)

Para garantir que sua IA use Engram de forma eficaz, adicione isto às regras do seu projeto (.cursorrules ou CLAUDE.md).

## Engram Workflow Policy
You have access to a tool called `engram` (specifically `get_impact_analysis` and `save_project_note`).
You MUST follow this strictly sequential workflow for EVERY code modification request:

### Phase 1: Analysis (MANDATORY START)
1.  **Blast Radius Check**: Before reading code or proposing changes, you MUST call `get_impact_analysis` on the target file(s).
2.  **Context Loading**:
    *   **Coupling**: If "High" or "Critical" risk files are returned, evaluate if they are *functionally related*.
        *   *Action:* Read the file (`read_file`) if it poses a logical regression risk.
        *   *Ignore:* Skip files that appear coincidental (e.g., lockfiles, gitignore, bulk formatting updates).
    *   **Memories**: Pay close attention to any "Memories" returned in the analysis summary.
    *   **Tests**: If `test_intents` are present, treat them as strict behavioural constraints. If absent, proceed with standard code analysis.

### Phase 2: Execution
3.  **Fix/Refactor**: Proceed with the code changes. Update tests if the behaviour is intentionally changing.

### Phase 3: Knowledge Capture (MANDATORY END)
4.  **Save Learnings**: Before finishing, ask: *"Would a future developer be **surprised** by something I discovered?"*
    *   **IF YES** (Hidden dependencies, non-obvious bugs, env quirks): You MUST use `save_project_note`.
    *   **IF NO** (Typos, standard refactors, documented behaviour): Do NOT save a note.

Desenvolvimento e Benchmarking

Compilar a partir do Código-Fonte

Requer Rust (1.70+) e Node.js (18+).

npm run build:all    # Build Rust core + TypeScript adapter
npm run test:all     # Run standard test suite

Benchmarking de Desempenho

Para verificar o desempenho contra o kernel Linux (requer um clone local de linux como diretório irmão):

# 1. Clone linux kernel to ../linux
# 2. Run the ignored performance tests
npm run test:all-local

Contribuindo

Aceitamos relatórios de bugs e correções da comunidade. Observe que, ao contribuir para este repositório, você concede à spectra-g uma licença perpétua e irrevogável para incluir suas alterações tanto no código-fonte público quanto nas versões licenciadas comercialmente do software.

Licença

Este projeto é licenciado sob a PolyForm Noncommercial License 1.0.0.

  • Pessoal/Sem Fins Lucrativos: Uso gratuito.
  • Uso Comercial: Requer uma licença comercial.

Ver Licença | Comprar Licença Comercial