Em um cenário onde o custo de tokens de IA se torna um fator crítico no desenvolvimento de software, uma solução brasileira emerge como resposta eficiente. O CIAM (Context IA Manager) é uma ferramenta open-source desenvolvida em Go que promete reduzir drasticamente o consumo de tokens em workflows que utilizam assistentes como GitHub Copilot, Claude ou similares em editores como VSCode, Cursor e Windsurf, especialmente em projetos Django.
O problema real: tokens consumidos antes da primeira linha de código
A motivação para criar o CIAM surgiu de uma frustração prática. Em projetos Django de médio porte — envolvendo autenticação, integração com Stripe, multi-tenancy e Celery — um padrão desgastante se repetia. Ao iniciar uma conversa com um assistente de IA para implementar um novo endpoint, o processo começava com pedidos sequenciais de arquivos: models.py, serializers.py, urls.py. O desenvolvedor colava arquivo por arquivo, consumindo cerca de 8k tokens de contexto antes mesmo de escrever a primeira linha de código útil. Quando a janela de contexto era excedida, todo o processo precisava ser reiniciado.
O problema se amplificava porque a IA não possuía memória persistente entre sessões. Decisões arquiteturais importantes — como usar UUID como primary key, padrões de response envelope ou configurações específicas de workers Celery (como acks_late=True devido a bugs de idempotência) — eram perdidas. Cada nova sessão começava do zero, elevando custos e reduzindo a eficiência que essas ferramentas prometem entregar.
Arquitetura do CIAM: busca semântica e compressão de contexto
Inspirado pelo projeto th0th (TypeScript/Node.js), que utiliza busca semântica e compressão de contexto para reduzir tokens, o CIAM foi reimplementado do zero em Go com diferenciações estratégicas. A ferramenta é um binário único que não requer Node.js como dependência, oferece consciência nativa da estrutura Django, memória persistente entre projetos e métricas reais de economia de tokens.
A arquitetura opera através de três componentes principais: uma API em Go (que indexa, gera embeddings via Ollama e armazena em SQLite), um servidor MCP (Model Context Protocol) que traduz chamadas do assistente em requisições HTTP, e uma CLI para comandos como indexação, busca e monitoramento.
Indexador com conhecimento específico de Django
Um diferencial crucial é o indexador que categoriza automaticamente os arquivos Django. Em vez de tratar todo código como “genérico”, o CIAM identifica e classifica:
- models.py → chunk_type: model
- views.py → chunk_type: view
- serializers.py → chunk_type: serializer
- urls.py → chunk_type: url
- tasks.py → chunk_type: task
- conftest.py → chunk_type: test
- signals.py → chunk_type: signal
Esta categorização permite buscas filtradas e precisas. O usuário pode, por exemplo, buscar especificamente por modelos relacionados a autenticação, views para envio de email ou tasks com determinadas permissões.
Busca híbrida e indexação incremental
O CIAM implementa uma busca híbrida que combina similaridade vetorial (embeddings) com BM25 (busca por keywords), usando a estratégia Reciprocal Rank Fusion. Isso garante que termos exatos como nomes de classes ou campos sejam encontrados eficientemente, complementando a busca semântica.
A indexação incremental por arquivo resolve um problema comum: re-indexar completamente projetos com 200+ arquivos Python é lento e desperdiça recursos. O CIAM utiliza hash SHA-256 para cada arquivo, comparando com versões anteriores armazenadas. Se o hash não mudou, o arquivo é ignorado no processo de re-embedding, economizando tempo e processamento.
Gestão de conhecimento integrada: ADR, PRD e planos
O CIAM reconhece que código é apenas parte do contexto. As decisões arquiteturais (ADR), requisitos de produto (PRD) e planos de implementação são igualmente cruciales para que a IA compreenda o “porquê” e o “quê” além do “como”. A ferramenta incorpora um sistema de conhecimento diretamente na CLI, permitindo criar e indexar automaticamente esses documentos.
Comandos como ciam prd new "Sistema de billing via Stripe" ou ciam adr new "Fix: race condition no worker de emails" geram documentos estruturados e imediatamente indexados. Quando o assistente precisa implementar uma feature, pode recuperar em uma única chamada o PRD, o plano de execução e o código relevante, entendendo completamente o contexto da tarefa.
Memória persistente entre sessões e projetos
A capacidade de “lembrar” decisões é um dos pilares do CIAM. Com comandos como ciam remember "Usar UUID como PK em todos os models — decidido para facilitar merges entre ambientes" ou ciam remember "Celery workers com acks_late=True — bug de idempotência corrido em março" --type bug, essas informações são armazenadas em um banco separado com embeddings próprio.
Essas memórias são recuperáveis meses depois, em qualquer projeto. Quando o assistente investiga uma decisão sobre UUID, o contexto histórico é fornecido, evitando repetição de debates ou implementações inconsistentes.
Resultados concretos: economia de tokens em números
Os testes práticos demonstram reduções significativas. Em uso inicial pontual (com poucas buscas), a economia chegou a 95%: um projeto estimado em ~29104 tokens teve apenas 1240 tokens servidos à IA. Em uma tarde de uso intenso (25+ chamadas MCP reais), a redução foi de 41%, com ~30821 tokens de projeto tendo ~18315 tokens servidos, economizando ~12506 tokens.
A métrica é conservadora: compara tokens servidos com o tamanho total do índice. Na prática, o benefício real é maior, pois o consumo sem o CIAM cresce linearmente com o número de perguntas, enquanto o índice cresce apenas com o tamanho do projeto. A redução efetiva no dia-a-dia se aproxima de 90%+.
Integração via MCP: 12 ferramentas para o assistente
Quando integrado ao editor via MCP, o assistente ganha acesso a 12 ferramentas especializadas:
- ciam_route: Direciona a intenção do usuário (em linguagem natural) à ferramenta adequada.
- ciam_search: Busca genérica no código indexado.
- ciam_context: Busca e comprime contexto em uma única chamada.
- ciam_django_map: Mapa estrutural do projeto (apps → models → views → urls).
- ciam_adr_search: Recupera decisões arquiteturais.
- ciam_prd_search: Consulta requisitos de produto.
- ciam_plan_search: Acessa planos de implementação.
- ciam_research_search: Pesquisa em documentos externos (artigos, PDFs).
- ciam_decision_context: Ferramenta mais poderosa, que fornece chunks de código, ADRs, PRDs e planos relevantes em um único request.
- ciam_remember: Armazena novas decisões na memória persistente.
- ciam_recall: Recupera memórias de sessões anteriores.
- ciam_compress: Comprime código (mantém assinaturas, remove docstrings).
- ciam_index: Re-indexa o projeto via MCP.
Esta suite transforma o assistente de IA em um agente verdadeiramente contextualizado, com conhecimento profundo e histórico do projeto.
Instalação e uso prático
A implementação é simplificada em três comandos básicos, exigindo apenas Go 1.22+ e Docker como pré-requisitos. Clone o repositório, execute make install para obter o binário CIAM, inicie os serviços com ciam up, e no seu projeto Django utilize ciam init (para auto-detectar o editor e gerar configuração MCP), ciam index . (para indexação inicial) e ciam watch . (para monitoramento e re-indexação automática em background).
A ferramenta é projetada para operação 100% offline, preservando a privacidade do código, e oferece uma dashboard web com estatísticas de economia por projeto.
Para desenvolvedores Django que enfrentam custos crescentes com tokens de IA ou perda de contexto entre sessões, o CIAM apresenta uma solução tangível. A redução de custos, a precisão das respostas e a memória persistente não apenas otimizam o workflow, mas transformam a relação entre o desenvolvedor e o assistente de IA, tornando-o um colaborador verdadeiramente inteligente e autônomo.
O projeto, disponível como open-source, continua evoluindo com planos para suporte a FastAPI e GenericPython, indexação por eventos de filesystem (inotify) e expansão da dashboard. A comunidade é incentivada a testar, reportar melhorias e compartilhar métricas de redução de tokens em seus próprios projetos, contribuindo para uma ferramenta que busca democratizar o uso eficiente de IA no desenvolvimento de software.
