Contextful

Contextful

⚠️ Isto está em alpha inicial. A API, os recursos e as integrações não são estáveis. Espere mudanças significativas. Feedback e contribuições são muito bem-vindos!

Gerenciamento de Contexto Local + Mecanismo de Busca + Memória para IA Agêntica.

Contextful é uma camada contextual em tempo de execução e um mecanismo de busca local para agentes, que oferece uma maneira rápida de encontrar, compactar, citar e lembrar o contexto do projeto.

Disponível como uma ferramenta com foco em CLI, com uma ponte de execução MCP e instruções de agente geradas, ele se integra perfeitamente ao Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue e Zed.

Em vez de fazer um agente ler 40 arquivos a cada sessão, o Contextful indexa o projeto uma vez e retorna um pacote de contexto ranqueado, citado e com orçamento de tokens.

Por quê?

O contexto sempre foi um gargalo para a IA agêntica. Modelos com grandes janelas de contexto (por exemplo, 1M de tokens) são:

1. Caros e exigem significativamente mais computação e tempo de processamento.
2. Mais propensos a perder informações-chave à medida que a janela de contexto se enche.
3. A maioria dos projetos tem milhões de linhas de código, mas os agentes só conseguem encaixar um número limitado de tokens por janela de contexto.

A solução atual é fazer o agente adivinhar quais arquivos ler e, em seguida, pagar o custo em tokens para lê-los a cada sessão. Isso é lento, caro e perde informações.

Além disso, os agentes não têm como armazenar ou compartilhar aprendizados entre sessões. Toda vez que começam, esquecem tudo e precisam reler o mesmo contexto novamente.

Comecei a desenvolver o Contextful para manter a janela de contexto menor, permitindo uma recuperação eficiente de conhecimento. Se indexarmos o projeto e retornarmos um pacote de contexto ranqueado, citado e com orçamento de tokens, podemos:

• Uso de tokens 100x mais eficiente: pare de pagar tokens para reler os mesmos arquivos.
• Menos chamadas de ferramentas: um pacote de contexto pode substituir dezenas de chamadas de grep, glob e leitura de arquivos.
• Sem perda de contexto entre sessões: os agentes podem armazenar aprendizados de sessão em um registro de memória com respaldo de evidências.
• Conhecimento de projeto compartilhável: lições e pacotes de contexto sobrevivem à compactação de contexto e a sessões futuras.

Principais Recursos

1. Gerenciamento de Contexto

O armazenamento local padrão é SQLite com busca com suporte a FTS e tabelas de grafo tipadas. A V1 inclui:

• SQLite como armazenamento local padrão.
• Busca lexical/BM25 com FTS5.
• Tabelas de grafo tipadas: nodes, edges, node_props, edge_props.
• Um cache de adjacência quente para relações de grafo comuns.
• Impressões digitais estruturais determinísticas inspiradas em sinais de reclassificação secundária no estilo Code2Vec.

As próximas atualizações de armazenamento são vetores semânticos opcionais por meio de sqlite-vec, LanceDB ou HNSW local, e listas de adjacência compactadas com bitmaps Roaring ou arrays CSR para repositórios maiores.

2. Mecanismo de Busca

O Contextful analisa a consulta, classifica a intenção e combina busca lexical, símbolos, documentos, relações de grafo e acertos de memória para recuperar as evidências certas. O objetivo é uma busca de projeto nível Google para agentes: consultas vagas como "recursos para onboarding de autenticação" devem encontrar o código, os documentos e as lições anteriores certos.

3. Registro de Memória

Os agentes podem armazenar lições, decisões e fatos úteis do projeto, mas não como notas soltas de "lembre disso". Cada memória exige referências de evidência de arquivos, símbolos, commits ou pacotes de contexto anteriores. Quando a evidência muda, o Contextful marca a memória como desatualizada.

4. Execução do Contextful

O Contextful é um servidor MCP, indexador local e um pequeno CLI:

• Servidor MCP: a interface do agente.
• Daemon / observador local: indexação, reconstruções, atualização e benchmarks futuros.
• CLI (cxf): configuração humana, indexação, busca, gravações de memória e testes locais de fumaça.

MCP é a interface certa porque ferramentas, recursos e prompts são exatamente o que o MCP padroniza. O agente pede contexto; o Contextful retorna evidências compactas.

Instalação

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

Execute como um servidor MCP:

npx @inferensys/contextful server

CLI

O binário principal é cxf; contextful também é fornecido como um alias legível.

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

Ferramentas MCP Principais

Mantenha a superfície do agente pequena:

• context_pack(query, budget, scope) - a ferramenta matadora. Retorna um pacote ranqueado, citado e com orçamento de tokens em vez de forçar 40 leituras aleatórias de arquivos.
• search_code(query, mode, filters) - busca poderosa de código, documentos, símbolos e memória.
• trace_path(from, to, edge_types) - travessia de grafo entre arquivos, símbolos, módulos e configuração.
• impact_analysis(symbol_or_file) - dependências reversas e testes prováveis.
• why_changed(symbol_or_file) - evidências atuais mais histórico de git.
• recall_memory(query, scope) - busca de aprendizados de sessão e lições duráveis do projeto.
• write_lesson(claim, evidence_refs, scope) - armazena uma memória com respaldo de evidências.

Configuração do Cliente MCP

Use este comando de servidor stdio em qualquer ferramenta de codificação compatível com MCP:

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

Codex:

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

Fluxo de Agente com Foco em CLI

Use cxf init uma vez por espaço de trabalho. Ele indexa o projeto e escreve .contextful/AGENT_INSTRUCTIONS.md, um guia compacto no estilo de skill que diz aos agentes quando chamar context_pack, quando buscar de forma mais restrita e quando gravações de memória são permitidas.

Use cxf search quando um humano quiser testar o mesmo pacote de evidências que um agente receberá:

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

O servidor MCP continua sendo a interface do agente. O CLI é para configuração, inspeção e testes locais repetíveis.

Privacidade

A V1 é somente local. Ela não chama APIs externas de embeddings, não envia código-fonte, não edita arquivos de origem, não corrige código automaticamente e não instala dependências dentro do espaço de trabalho de destino.

Referências de Evidência

Gravações de memória exigem referências de evidência retornadas pela busca ou por pacotes de contexto:

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

Evidências inválidas ou desatualizadas são rejeitadas ou marcadas como desatualizadas.