PAMPA

Um servidor MCP para busca semântica inteligente e aprendizado automático em bases de código, permitindo que agentes de IA consultem e indexem artefatos de projetos de forma eficiente.

GitHub
30
Experimente este MCPPatrocinado

Documentação

PAMPA – Protocolo para Memória Aumentada de Artefatos de Projeto

Versão 1.12.x · Busca Semântica · Compatível com MCP · Node.js

Agent Rules Kit Logo

Version Downloads License Last Commit Build Status

Dê aos seus agentes de IA uma memória sempre atualizada e consultável de qualquer base de código – com busca semântica inteligente e aprendizado automático – em um único comando npx.

🇪🇸 Versión en Español | 🇺🇸 English Version | 🤖 Agent Version

🌟 Novidades na v1.12 – Busca Avançada e Suporte a Múltiplos Projetos

🎯 Filtros de Busca Escopados – Filtre por path_glob, tags, lang para resultados precisos

🔄 Busca Híbrida – Fusão BM25 + Vetores com combinação de classificação recíproca (ativada por padrão)

🧠 Re-Classificador Cross-Encoder – Re-classificador Transformers.js para ganhos de precisão

👀 Observador de Arquivos – Indexação incremental em tempo real com hash estilo Merkle

📦 Pacotes de Contexto – Escopos de busca reutilizáveis com integração CLI + MCP

🛠️ CLI Multi-Projeto – Aliases --project e --directory para clareza

🏆 Análise de Desempenho – Comparação arquitetural com ferramentas IDE de propósito geral

Principais melhorias:

  • Indexação 40% mais rápida com atualizações incrementais
  • Precisão 60% melhor com busca híbrida + re-classificador
  • Operações multi-projeto 3x mais rápidas com caminhos explícitos
  • Redução de 90% na duplicação de criação de funções com reforço de símbolos
  • Arquitetura especializada para busca semântica de código

🌟 Por que PAMPA?

Agentes de modelos de linguagem de grande escala podem ler milhares de tokens, mas projetos facilmente alcançam milhões de caracteres. Sem uma camada inteligente de recuperação, os agentes:

  • Recriam funções que já existem
  • Nomeiam APIs incorretamente (newUser vs. createUser)
  • Desperdiçam tokens carregando código repetitivo (vendor/, node_modules/...)
  • Falham quando o repositório cresce

O PAMPA resolve isso transformando seu repositório em um grafo de memória semântica de código:

  1. Fragmentação – Cada função/classe torna-se um fragmento atômico
  2. Marcação Semântica – Extração automática de tags semânticas do contexto do código
  3. Incorporação – Fragmentos aprimorados são vetorizados com modelos avançados de incorporação
  4. Aprendizado – O sistema aprende com buscas bem-sucedidas e armazena intenções em cache
  5. Indexação – Vetores + metadados semânticos ficam no SQLite local
  6. Mapa de Código – Um pampa.codemap.json leve é commitado no git para que o contexto acompanhe o repositório
  7. Serviço – Um servidor MCP expõe ferramentas inteligentes de busca e recuperação

Qualquer agente compatível com MCP (Cursor, Claude, etc.) agora pode buscar com linguagem natural, obter respostas instantâneas para padrões aprendidos e permanecer sincronizado – sem escanear toda a árvore.

🤖 Para Agentes de IA e Humanos

🤖 Se você é um agente de IA: Leia o guia de configuração completo para agentes → ou 👤 Se você é humano: Compartilhe o guia de configuração para agentes com seu assistente de IA para configurar o PAMPA automaticamente!

📚 Sumário

🧠 Recursos Semânticos

🏷️ Marcação Semântica Automática

O PAMPA extrai automaticamente tags semânticas do seu código sem nenhum comentário especial:

// File: app/Services/Payment/StripeService.php
function createCheckoutSession() { ... }

Tags automáticas: ["stripe", "service", "payment", "checkout", "session", "create"]

🎯 Busca Direta Baseada em Intenção

O sistema aprende com buscas bem-sucedidas e fornece respostas instantâneas:

# First search (vector search)
"stripe payment session" → 0.9148 similarity

# System automatically learns and caches this pattern
# Next similar searches are instant:
"create stripe session" → instant response (cached)
"stripe checkout session" → instant response (cached)

📈 Sistema de Aprendizado Adaptativo

  • Aprendizado Automático: Salva buscas bem-sucedidas (similaridade >80%) como intenções
  • Normalização de Consultas: Entende variações: "create" = "crear", "session" = "sesion"
  • Reconhecimento de Padrões: Agrupa consultas semelhantes: "[PROVIDER] payment session"

🏷️ Comentários @pampa Opcionais (Complementares)

Aprimore a precisão da busca com comentários opcionais no estilo JSDoc:

/**
 * @pampa-tags: stripe-checkout, payment-processing, e-commerce-integration
 * @pampa-intent: create secure stripe checkout session for payments
 * @pampa-description: Main function for handling checkout sessions with validation
 */
async function createStripeCheckoutSession(sessionData) {
	// Your code here...
}

Benefícios:

  • +21% de precisão quando presentes
  • Pontuações perfeitas (1.0) quando a consulta corresponde exatamente à intenção
  • Totalmente opcionais: Código sem comentários funciona automaticamente
  • Retrocompatíveis: Bases de código existentes funcionam sem alterações

📊 Resultados de Desempenho da Busca

Tipo de BuscaSem @pampaCom @pampaMelhoria
Específica de domínio0.73310.8874+21%
Correspondência de intenção~0.61.0000+67%
Busca geral0.6-0.80.8-1.0+32-85%

📝 Linguagens Suportadas

O PAMPA pode indexar e buscar código em várias linguagens prontamente:

  • JavaScript / TypeScript (.js, .ts, .tsx, .jsx)
  • PHP (.php)
  • Python (.py)
  • Go (.go)
  • Java (.java)

🚀 Instalação MCP (Recomendada)

1. Configure seu cliente MCP

Claude Desktop

Adicione à configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
	"mcpServers": {
		"pampa": {
			"command": "npx",
			"args": ["-y", "pampa", "mcp"]
		}
	}
}

Opcional: Adicione "--debug" aos argumentos para registro detalhado: ["-y", "pampa", "mcp", "--debug"]

Cursor

Configure o Cursor criando ou editando o arquivo mcp.json no seu diretório de configuração:

{
	"mcpServers": {
		"pampa": {
			"command": "npx",
			"args": ["-y", "pampa", "mcp"]
		}
	}
}

2. Deixe seu agente de IA lidar com a indexação

Seu agente de IA deve automaticamente:

  • Verificar se o projeto está indexado com get_project_stats
  • Indexar o projeto com index_project se necessário
  • Mantê-lo atualizado com update_project após alterações

Precisa indexar manualmente? Veja a seção Uso Direto via CLI.

3. Instale a regra de uso para seu agente

Adicionalmente, instale esta regra no seu aplicativo para que ele use o PAMPA efetivamente:

Copie o conteúdo de RULE_FOR_PAMPA_MCP.md para as instruções do seu agente ou sistema de IA.

4. Pronto! Seu agente agora pode buscar código

Uma vez configurado, seu agente de IA pode:

🔍 Search: "authentication function"
📄 Get code: Use the SHA from search results
📊 Stats: Get project overview and statistics
🔄 Update: Keep memory synchronized

💻 Uso Direto via CLI

Para uso direto no terminal ou indexação manual de projetos:

Instale a CLI

# Run without installing
npx pampa --help

# Or install globally (requires Node.js 20+)
npm install -g pampa

Indexe ou atualize um projeto

# Index current repository with the best available provider
npx pampa index

# Force the local CPU embedding model (no API keys required)
npx pampa index --provider transformers

# Re-embed after code changes
npx pampa update

# Inspect indexed stats at any time
npx pampa info

A indexação grava .pampa/ (banco de dados SQLite + armazenamento de fragmentos) e pampa.codemap.json. Faça commit do mapa de código no git para que colegas e CI reutilizem os mesmos metadados.

| Comando | Propósito | | ---------------------------------------- | --------------------------------------------------------- | ----- | ------------------------------------------------- | | npx pampa index [path] [--provider X] | Criar ou atualizar o índice completo no caminho fornecido | | npx pampa update [path] [--provider X] | Forçar uma re-varredura completa (útil após grandes refatorações) | | npx pampa watch [path] [--provider X] | Atualizar incrementalmente o índice conforme os arquivos mudam | | npx pampa search <query> | Busca híbrida BM25 + vetores com filtros escopados opcionais | | npx pampa context <list | show | use> | Gerenciar pacotes de contexto reutilizáveis para padrões de busca | | npx pampa mcp | Iniciar o servidor MCP stdio para integrações com editores/agentes |

Busque com filtros escopados e flags de classificação

pampa search suporta os mesmos filtros usados pelos clientes MCP. Combine padrões glob, tags semânticas, filtros de linguagem, substituições de provedor e controles de classificação:

| Flag / opção | Efeito | | -------------------- | -------------------------------------------------------------------- | ---------------- | | --path_glob | Limitar resultados a arquivos correspondentes ("app/Services/**") | | --tags | Filtrar por tags do mapa de código (stripe, checkout) | | --lang | Filtrar por linguagem (php, ts, py) | | --provider | Substituir o provedor de incorporação para a consulta (openai, transformers) | | --reranker | Reordenar os principais resultados com o cross-encoder Transformers (off | transformers) | | --hybrid / --bm25 | Alternar fusão de classificação recíproca ou o estágio candidato BM25 (on | off) | | --symbol_boost | Alternar o reforço de classificação ciente de símbolos que favorece correspondências de assinatura (on | off) | | -k, --limit | Limitar resultados retornados (padrão: 10) |

# Narrow to service files tagged stripe in PHP
npx pampa search "create checkout session" --path_glob "app/Services/**" --tags stripe --lang php

# Use OpenAI embeddings but keep hybrid fusion enabled
npx pampa search "payment intent status" --provider openai --hybrid on --bm25 on

# Reorder top candidates locally
npx pampa search "oauth middleware" --reranker transformers --limit 5

# Disable signature boosts for literal keyword hunts
npx pampa search "token validation" --symbol_boost off

O PAMPA extrai assinaturas de funções e grafos de chamada leves com tree-sitter. Quando os reforços de símbolos estão ativados, consultas que mencionam um método, classe ou um auxiliar diretamente conectado recebem um aumento extra de pontuação.

Quando um pacote de contexto está ativo, a CLI imprime o nome do pacote antes de executar a busca. Qualquer flag explícita substitui os padrões do pacote.

Gerencie pacotes de contexto

Armazene pacotes JSON em .pampa/contextpacks/*.json para capturar padrões reutilizáveis:

// .pampa/contextpacks/stripe-backend.json
{
	"name": "Stripe Backend",
	"description": "Scopes searches to the Stripe service layer",
	"path_glob": ["app/Services/**"],
	"tags": ["stripe"],
	"lang": ["php"],
	"reranker": "transformers",
	"hybrid": "off"
}

# List packs and highlight the active one
npx pampa context list

# Inspect the full JSON definition
npx pampa context show stripe-backend

# Activate scoped defaults (flags still win if provided explicitly)
npx pampa context use stripe-backend

# Clear the active pack (use "none" or "clear")
npx pampa context use clear

Dica MCP: A ferramenta MCP use_context_pack espelha a CLI. Agentes podem alternar pacotes no meio da sessão e toda chamada subsequente de search_code herda esses padrões até serem limpos.

Observe e re-indexe incrementalmente

# Watch the repository with a 750 ms debounce and local embeddings
npx pampa watch --provider transformers --debounce 750

O observador agrupa eventos do sistema de arquivos, reutiliza o armazenamento de hash Merkle em .pampa/merkle.json e apenas re-incorpora arquivos modificados. Pressione Ctrl+C para parar.

Execute o harness de benchmark sintético

npm run bench

O harness semeia um corpus determinístico Laravel + TypeScript e imprime uma tabela resumo com Precision@1, MRR@5 e nDCG@10 para os modos Base, Híbrido e Híbrido+Cross-Encoder. Personalize cenários via flags ou variáveis de ambiente:

  • npm run bench -- --hybrid=off – executar avaliação apenas vetorial
  • npm run bench -- --reranker=transformers – forçar o cross-encoder
  • PAMPA_BENCH_MODES=base,hybrid npm run bench – limitar a modos específicos
  • PAMPA_BENCH_BM25=off npm run bench – desabilitar geração de candidatos BM25

Execuções de benchmark nunca baixam modelos externos quando PAMPA_MOCK_RERANKER_TESTS=1 (ativado por padrão dentro do harness).

Um exemplo completo de pacote de contexto ponta a ponta está em examples/contextpacks/stripe-backend.json.

🧠 Provedores de Incorporação

O PAMPA suporta múltiplos provedores para gerar incorporações de código:

ProvedorCustoPrivacidadeInstalação
Transformers.js🟢 Gratuito🟢 Totalnpm install @xenova/transformers
Ollama🟢 Gratuito🟢 TotalInstalar Ollama + npm install ollama
OpenAI🔴 ~$0.10/1000 funções🔴 NenhumaDefina OPENAI_API_KEY
Cohere🟡 ~$0.05/1000 funções🔴 NenhumaDefina COHERE_API_KEY + npm install cohere-ai

Recomendação: Use Transformers.js para desenvolvimento pessoal (gratuito e privado) ou OpenAI para máxima qualidade.

🏆 Análise de Desempenho

O PAMPA v1.12 usa uma arquitetura especializada para busca semântica de código com resultados mensuráveis.

📊 Métricas de Desempenho

Resultados do Benchmark Sintético:

| Setting    | P@1   | MRR@5 | nDCG@10 |
| ---------- | ----- | ----- | ------- |
| Base       | 0.750 | 0.833 | 0.863   |
| Hybrid     | 0.875 | 0.917 | 0.934   |
| Hybrid+CE  | 1.000 | 0.958 | 0.967   |

🎯 Exemplos de Busca

# Search for authentication functions
pampa search "user authentication"
→ AuthController::login, UserService::authenticate, etc.

# Search for payment processing
pampa search "payment processing"
→ PaymentService::process, CheckoutController::create, etc.

# Search with specific filters
pampa search "database operations" --lang php --path_glob "app/Models/**"
→ UserModel::save, OrderModel::find, etc.

📈 Leia a Análise Completa →

🚀 Vantagens Arquiteturais

  1. Indexação Especializada - Índice persistente com granularidade em nível de função
  2. Busca Híbrida - Combinação de BM25 + Vetor + reclassificação por cross-encoder
  3. Consciência de Código - Reforço de símbolos, análise AST, assinaturas de funções
  4. Multi-Projeto - Suporte nativo para contexto entre diferentes bases de código

Resultado: Arquitetura otimizada para busca semântica de código com métricas verificáveis.

🏗️ Arquitetura

┌──────────── Repo (git) ─────────-──┐
│ app/… src/… package.json etc.      │
│ pampa.codemap.json                 │
│ .pampa/chunks/*.gz(.enc)          │
│ .pampa/pampa.db (SQLite)           │
└────────────────────────────────────┘
          ▲       ▲
          │ write │ read
┌─────────┴─────────┐   │
│ indexer.js        │   │
│ (pampa index)     │   │
└─────────▲─────────┘   │
          │ store       │ vector query
┌─────────┴──────────┐  │ gz fetch
│ SQLite (local)     │  │
└─────────▲──────────┘  │
          │ read        │
┌─────────┴──────────┐  │
│ mcp-server.js      │◄─┘
│ (pampa mcp)        │
└────────────────────┘

Componentes Principais

CamadaFunçãoTecnologia
IndexadorDivide o código em blocos semânticos, gera embeddings, escreve codemap e SQLitetree-sitter, openai@v4, sqlite3
CodemapJSON amigável ao Git com {file, symbol, sha, lang} por blocoPlain JSON
Diretório de blocosCorpos de código .gz (ou .gz.enc quando criptografado) (carregamento preguiçoso)gzip → AES-256-GCM quando habilitado
SQLiteArmazena vetores e metadadossqlite3
Servidor MCPExpõe ferramentas e recursos sobre o protocolo MCP padrão@modelcontextprotocol/sdk
RegistroRegistro de depuração e erros no diretório do projetoLogs baseados em arquivo

🔧 Ferramentas MCP Disponíveis

O servidor MCP expõe estas ferramentas que os agentes podem usar:

search_code

Busque código semanticamente no projeto indexado.

  • Parâmetros:
    • query (string) - Consulta de busca semântica (ex.: "função de autenticação", "tratamento de erros")
    • limit (número, opcional) - Número máximo de resultados a retornar (padrão: 10)
    • provider (string, opcional) - Provedor de embeddings (padrão: "auto")
    • path (string, opcional) - Caminho do diretório PROJECT ROOT onde o banco de dados PAMPA está localizado
  • Localização do Banco de Dados: {path}/.pampa/pampa.db
  • Retorna: Lista de blocos de código correspondentes com pontuações de similaridade e SHAs

get_code_chunk

Obtenha o código completo de um bloco específico.

  • Parâmetros:
    • sha (string) - SHA do bloco de código a recuperar (obtido dos resultados de search_code)
    • path (string, opcional) - Caminho do diretório PROJECT ROOT (mesmo usado em search_code)
  • Localização do Bloco: {path}/.pampa/chunks/{sha}.gz ou {sha}.gz.enc
  • Retorna: Código-fonte completo

index_project

Indexe um projeto a partir do agente.

  • Parâmetros:
    • path (string, opcional) - Caminho do diretório PROJECT ROOT para indexar (criará o subdiretório .pampa/ aqui)
    • provider (string, opcional) - Provedor de embeddings (padrão: "auto")
  • Cria:
    • {path}/.pampa/pampa.db (banco de dados SQLite com embeddings)
    • {path}/.pampa/chunks/ (blocos de código comprimidos)
    • {path}/pampa.codemap.json (índice leve para controle de versão)
  • Efeito: Atualiza o banco de dados e o codemap

update_project

🔄 CRÍTICO: Use esta ferramenta com frequência para manter sua memória de IA atualizada!

Atualize o índice do projeto após alterações de código (ferramenta de fluxo de trabalho recomendada).

  • Parâmetros:
    • path (string, opcional) - Caminho do diretório PROJECT ROOT para atualizar (mesmo usado em index_project)
    • provider (string, opcional) - Provedor de embeddings (padrão: "auto")
  • Atualiza:
    • Re-verifica todos os arquivos em busca de alterações
    • Atualiza embeddings para funções modificadas
    • Remove funções excluídas do banco de dados
    • Adiciona novas funções ao banco de dados
  • Quando usar:
    • ✅ No início das sessões de desenvolvimento
    • ✅ Após criar novas funções
    • ✅ Após modificar funções existentes
    • ✅ Após excluir funções
    • ✅ Antes de tarefas importantes de análise de código
    • ✅ Após refatorar código
  • Efeito: Mantém a memória de código do seu agente de IA sincronizada com o estado atual

get_project_stats

Obtenha estatísticas do projeto indexado.

  • Parâmetros:
    • path (string, opcional) - Caminho do diretório PROJECT ROOT onde o banco de dados PAMPA está localizado
  • Localização do Banco de Dados: {path}/.pampa/pampa.db
  • Retorna: Estatísticas por linguagem e arquivo

📊 Recursos MCP Disponíveis

pampa://codemap

Acesso ao mapa de código completo do projeto.

pampa://overview

Resumo das principais funções do projeto.

🎯 Prompts MCP Disponíveis

analyze_code

Modelo para analisar código encontrado com foco específico.

find_similar_functions

Modelo para encontrar funções semelhantes existentes.

🔍 Como Funciona a Recuperação

  • Busca vetorial – Similaridade de cosseno com embeddings avançados de alta dimensão
  • Fallback de resumo – Se um agente enviar uma consulta vazia, o PAMPA retorna resumos de alto nível para que o agente entenda o território
  • Granularidade de bloco – Padrão = função/método/classe. Ajustável por linguagem

📝 Decisões de Design

  • Somente Node → Desenvolvedores executam tudo via npx, sem Python, sem Docker
  • SQLite em vez de HelixDB → Um banco de dados local para vetores e relações, sem dependências externas
  • Codemap versionado → O contexto viaja com o repositório → clonagem funciona offline
  • Granularidade de bloco → Padrão = função/método/classe. Ajustável por linguagem
  • Somente leitura por padrão → O servidor expõe apenas métodos de leitura. A escrita é feita via CLI

🧩 Estendendo o PAMPA

IdeiaDica
Mais linguagensInstale a gramática tree-sitter e adicione-a a LANG_RULES
Embeddings personalizadosExporte OPENAI_API_KEY ou troque OpenAI por qualquer provedor que retorne vector: number[]
SegurançaExecute atrás de um proxy reverso com autenticação
Plugin VS CodeAponte um cliente MCP WebView para o seu servidor local

🔐 Criptografando o Armazenamento de Blocos

O PAMPA pode criptografar corpos de blocos em repouso usando AES-256-GCM. Configure assim:

  1. Exporte uma chave de 32 bytes em formato base64 ou hexadecimal:

    export PAMPA_ENCRYPTION_KEY="$(openssl rand -base64 32)"

  2. Indexe com criptografia habilitada (ignora gravações em texto simples mesmo se arquivos obsoletos existirem):

    npx pampa index --encrypt on

    Sem --encrypt, o PAMPA criptografa automaticamente quando a chave de ambiente está presente. Use --encrypt off para forçar texto simples (ex.: para depuração).

  3. Todos os novos blocos são armazenados como .gz.enc e exigem a mesma chave para recuperação de blocos via CLI ou MCP. Chaves ausentes ou corrompidas geram erros claros em vez de vazar dados.

Arquivos de texto simples existentes permanecem legíveis, então você pode habilitar a criptografia incrementalmente ou rotacionar chaves reindexando.

🤝 Contribuindo

  1. Fork → crie um branch de recurso (feat/...)
  2. Execute npm test (em breve) e npx pampa index antes do PR
  3. Abra um PR com contexto: porquê + capturas de tela/logs

Todas as discussões em GitHub Issues.

📜 Licença

MIT – faça o que quiser, apenas mantenha os direitos autorais.

Feliz hacking! 💙

🇦🇷 Feito com ❤️ na Argentina | 🇦🇷 Hecho con ❤️ en Argentina