PAMPA

Un servidor MCP para búsqueda semántica inteligente y aprendizaje automático dentro de bases de código, que permite a los agentes de IA consultar e indexar artefactos de proyectos de manera eficiente.

GitHub
30
Prueba este MCPPatrocinado

Documentación

PAMPA – Protocolo de Memoria Aumentada para Artefactos de Proyecto

Versión 1.12.x · Búsqueda Semántica · Compatible con MCP · Node.js

Agent Rules Kit Logo

Version Downloads License Last Commit Build Status

Dale a tus agentes de IA una memoria siempre actualizada y consultable de cualquier base de código – con búsqueda semántica inteligente y aprendizaje automático – en un solo comando npx.

🇪🇸 Versión en Español | 🇺🇸 Versión en Inglés | 🤖 Versión para Agentes

🌟 Novedades en v1.12 – Búsqueda Avanzada y Soporte Multi-Proyecto

🎯 Filtros de Búsqueda Acotados – Filtra por path_glob, tags, lang para resultados precisos

🔄 Búsqueda Híbrida – Fusión BM25 + Vectores con combinación de ranking recíproco (habilitada por defecto)

🧠 Re-Ranker de Codificador Cruzado – Re-ranker Transformers.js para mejoras de precisión

👀 Observador de Archivos – Indexación incremental en tiempo real con hash tipo Merkle

📦 Paquetes de Contexto – Ámbitos de búsqueda reutilizables con integración CLI + MCP

🛠️ CLI Multi-Proyecto – --project y --directory como alias para mayor claridad

🏆 Análisis de Rendimiento – Comparación arquitectónica con herramientas IDE de propósito general

Mejoras principales:

  • Indexación 40% más rápida con actualizaciones incrementales
  • Precisión 60% mejor con búsqueda híbrida + re-ranker
  • Operaciones multi-proyecto 3x más rápidas con rutas explícitas
  • Reducción del 90% en creación de funciones duplicadas con refuerzo de símbolos
  • Arquitectura especializada para búsqueda semántica de código

🌟 ¿Por qué PAMPA?

Los agentes de modelos de lenguaje grandes pueden leer miles de tokens, pero los proyectos fácilmente alcanzan millones de caracteres. Sin una capa de recuperación inteligente, los agentes:

  • Recrean funciones que ya existen
  • Nombran mal las APIs (newUser vs. createUser)
  • Desperdician tokens cargando código repetitivo (vendor/, node_modules/...)
  • Fallan cuando el repositorio crece

PAMPA resuelve esto convirtiendo tu repositorio en un grafo de memoria semántica de código:

  1. Fragmentación – Cada función/clase se convierte en un fragmento atómico
  2. Etiquetado Semántico – Extracción automática de etiquetas semánticas del contexto del código
  3. Incrustación – Los fragmentos mejorados se vectorizan con modelos de incrustación avanzados
  4. Aprendizaje – El sistema aprende de búsquedas exitosas y almacena en caché las intenciones
  5. Indexación – Los vectores + metadatos semánticos viven en SQLite local
  6. Mapa de código – Un pampa.codemap.json ligero se confirma en git para que el contexto siga al repositorio
  7. Servicio – Un servidor MCP expone herramientas inteligentes de búsqueda y recuperación

Cualquier agente compatible con MCP (Cursor, Claude, etc.) ahora puede buscar con lenguaje natural, obtener respuestas instantáneas para patrones aprendidos y mantenerse sincronizado – sin escanear todo el árbol.

🤖 Para Agentes de IA y Humanos

🤖 Si eres un agente de IA: Lee la guía de configuración completa para agentes → o 👤 Si eres humano: Comparte la guía de configuración para agentes con tu asistente de IA para configurar PAMPA automáticamente.

📚 Tabla de Contenidos

🧠 Características Semánticas

🏷️ Etiquetado Semántico Automático

PAMPA extrae automáticamente etiquetas semánticas de tu código sin necesidad de comentarios especiales:

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

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

🎯 Búsqueda Directa Basada en Intención

El sistema aprende de búsquedas exitosas y proporciona respuestas 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 Aprendizaje Adaptativo

  • Aprendizaje Automático: Guarda búsquedas exitosas (similitud >80%) como intenciones
  • Normalización de Consultas: Entiende variaciones: "create" = "crear", "session" = "sesion"
  • Reconocimiento de Patrones: Agrupa consultas similares: "[PROVIDER] payment session"

🏷️ Comentarios @pampa Opcionales (Complementarios)

Mejora la precisión de búsqueda con comentarios opcionales 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...
}

Beneficios:

  • +21% mejor precisión cuando están presentes
  • Puntuaciones perfectas (1.0) cuando la consulta coincide exactamente con la intención
  • Totalmente opcional: El código sin comentarios funciona automáticamente
  • Retrocompatible: Las bases de código existentes funcionan sin cambios

📊 Resultados de Rendimiento de Búsqueda

Tipo de BúsquedaSin @pampaCon @pampaMejora
Específica de dominio0.73310.8874+21%
Coincidencia de intención~0.61.0000+67%
Búsqueda general0.6-0.80.8-1.0+32-85%

📝 Lenguajes Soportados

PAMPA puede indexar y buscar código en varios lenguajes de forma nativa:

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

🚀 Instalación MCP (Recomendada)

1. Configura tu cliente MCP

Claude Desktop

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Opcional: Añade "--debug" a los argumentos para registro detallado: ["-y", "pampa", "mcp", "--debug"]

Cursor

Configura Cursor creando o editando el archivo mcp.json en tu directorio de configuración:

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

2. Deja que tu agente de IA maneje la indexación

Tu agente de IA debería automáticamente:

  • Verificar si el proyecto está indexado con get_project_stats
  • Indexar el proyecto con index_project si es necesario
  • Mantenerlo actualizado con update_project después de cambios

¿Necesitas indexar manualmente? Consulta la sección Uso Directo del CLI.

3. Instala la regla de uso para tu agente

Adicionalmente, instala esta regla en tu aplicación para que use PAMPA de manera efectiva:

Copia el contenido de RULE_FOR_PAMPA_MCP.md en las instrucciones de tu agente o sistema de IA.

4. ¡Listo! Tu agente ahora puede buscar código

Una vez configurado, tu agente de IA puede:

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

💻 Uso Directo del CLI

Para uso directo en terminal o indexación manual de proyectos:

Instalar el CLI

# Run without installing
npx pampa --help

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

Indexar o actualizar un proyecto

# 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

La indexación escribe .pampa/ (base de datos SQLite + almacén de fragmentos) y pampa.codemap.json. Confirma el mapa de código en git para que los compañeros de equipo y CI reutilicen los mismos metadatos.

| Comando | Propósito | | ---------------------------------------- | --------------------------------------------------------- | ----- | ------------------------------------------------- | | npx pampa index [path] [--provider X] | Crear o actualizar el índice completo en la ruta proporcionada | | npx pampa update [path] [--provider X] | Forzar un re-escaneo completo (útil después de grandes refactorizaciones) | | npx pampa watch [path] [--provider X] | Actualizar incrementalmente el índice a medida que los archivos cambian | | npx pampa search <query> | Búsqueda híbrida BM25 + vectorial con filtros de ámbito opcionales | | npx pampa context <list | show | use> | Gestionar paquetes de contexto reutilizables para valores predeterminados de búsqueda | | npx pampa mcp | Iniciar el servidor MCP stdio para integraciones de editor/agente |

Buscar con filtros de ámbito y banderas de clasificación

pampa search admite los mismos filtros utilizados por los clientes MCP. Combina patrones glob, etiquetas semánticas, filtros de lenguaje, anulaciones de proveedor y controles de clasificación:

| Bandera / opción | Efecto | | ------------------------ | -------------------------------------------------------------------- | ---------------- | | --path_glob | Limitar resultados a archivos coincidentes ("app/Services/**") | | --tags | Filtrar por etiquetas del mapa de código (stripe, checkout) | | --lang | Filtrar por lenguaje (php, ts, py) | | --provider | Anular el proveedor de incrustación para la consulta (openai, transformers) | | --reranker | Reordenar los mejores resultados con el codificador cruzado Transformers (off | transformers) | | --hybrid / --bm25 | Alternar fusión de ranking recíproco o la etapa candidata BM25 (on | off) | | --symbol_boost | Alternar el refuerzo de clasificación consciente de símbolos que favorece coincidencias de firma (on | off) | | -k, --limit | Limitar los resultados devueltos (predeterminado: 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

PAMPA extrae firmas de funciones y grafos de llamadas ligeros con tree-sitter. Cuando los refuerzos de símbolos están habilitados, las consultas que mencionan un método, clase o helper directamente conectado reciben un aumento adicional de puntuación.

Cuando un paquete de contexto está activo, el CLI imprime el nombre del paquete antes de ejecutar la búsqueda. Cualquier bandera explícita anula los valores predeterminados del paquete.

Gestionar paquetes de contexto

Almacena paquetes JSON en .pampa/contextpacks/*.json para capturar valores predeterminados reutilizables:

// .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

Consejo MCP: La herramienta MCP use_context_pack refleja el CLI. Los agentes pueden cambiar de paquete a mitad de sesión y cada llamada posterior a search_code hereda esos valores predeterminados hasta que se limpien.

Observar y re-indexar incrementalmente

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

El observador agrupa eventos del sistema de archivos, reutiliza el almacén de hash Merkle en .pampa/merkle.json y solo re-incrusta los archivos modificados. Presiona Ctrl+C para detener.

Ejecutar el banco de pruebas sintético

npm run bench

El banco de pruebas siembra un corpus determinista de Laravel + TypeScript e imprime una tabla resumen con Precision@1, MRR@5 y nDCG@10 para los modos Base, Híbrido e Híbrido+Codificador Cruzado. Personaliza los escenarios mediante banderas o variables de entorno:

  • npm run bench -- --hybrid=off – ejecutar evaluación solo vectorial
  • npm run bench -- --reranker=transformers – forzar el codificador cruzado
  • PAMPA_BENCH_MODES=base,hybrid npm run bench – limitar a modos específicos
  • PAMPA_BENCH_BM25=off npm run bench – deshabilitar la generación de candidatos BM25

Las ejecuciones del benchmark nunca descargan modelos externos cuando PAMPA_MOCK_RERANKER_TESTS=1 (habilitado por defecto dentro del banco de pruebas).

Un ejemplo completo de paquete de contexto de extremo a extremo vive en examples/contextpacks/stripe-backend.json.

🧠 Proveedores de Incrustación

PAMPA admite múltiples proveedores para generar incrustaciones de código:

ProveedorCostoPrivacidadInstalación
Transformers.js🟢 Gratis🟢 Totalnpm install @xenova/transformers
Ollama🟢 Gratis🟢 TotalInstalar Ollama + npm install ollama
OpenAI🔴 ~$0.10/1000 funciones🔴 NingunaEstablecer OPENAI_API_KEY
Cohere🟡 ~$0.05/1000 funciones🔴 NingunaEstablecer COHERE_API_KEY + npm install cohere-ai

Recomendación: Usa Transformers.js para desarrollo personal (gratis y privado) o OpenAI para máxima calidad.

🏆 Análisis de Rendimiento

PAMPA v1.12 utiliza una arquitectura especializada para búsqueda semántica de código con resultados medibles.

📊 Métricas de Rendimiento

Resultados del 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   |

🎯 Ejemplos de Búsqueda

# 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.

📈 Leer Análisis Completo →

🚀 Ventajas Arquitectónicas

  1. Indexación Especializada - Índice persistente con granularidad a nivel de función
  2. Búsqueda Híbrida - Combinación de BM25 + Vector + Reordenamiento con cross-encoder
  3. Conciencia de Código - Potenciación de símbolos, análisis AST, firmas de funciones
  4. Multi-Proyecto - Soporte nativo para contexto entre diferentes bases de código

Resultado: Arquitectura optimizada para búsqueda semántica de código con métricas verificables.

🏗️ Arquitectura

┌──────────── 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 Clave

CapaRolTecnología
IndexadorCorta el código en fragmentos semánticos, incrusta, escribe codemap y SQLitetree-sitter, openai@v4, sqlite3
CodemapJSON amigable con Git con {file, symbol, sha, lang} por fragmentoJSON plano
Directorio de fragmentosCuerpos de código .gz (o .gz.enc cuando está cifrado) (carga diferida)gzip → AES-256-GCM cuando está habilitado
SQLiteAlmacena vectores y metadatossqlite3
Servidor MCPExpone herramientas y recursos sobre el protocolo MCP estándar@modelcontextprotocol/sdk
RegistroRegistro de depuración y errores en el directorio del proyectoRegistros basados en archivos

🔧 Herramientas MCP Disponibles

El servidor MCP expone estas herramientas que los agentes pueden usar:

search_code

Busca código semánticamente en el proyecto indexado.

  • Parámetros:
    • query (cadena) - Consulta de búsqueda semántica (p. ej., "función de autenticación", "manejo de errores")
    • limit (número, opcional) - Número máximo de resultados a devolver (por defecto: 10)
    • provider (cadena, opcional) - Proveedor de incrustaciones (por defecto: "auto")
    • path (cadena, opcional) - Ruta del directorio RAÍZ DEL PROYECTO donde se encuentra la base de datos de PAMPA
  • Ubicación de la base de datos: {path}/.pampa/pampa.db
  • Devuelve: Lista de fragmentos de código coincidentes con puntuaciones de similitud y SHAs

get_code_chunk

Obtiene el código completo de un fragmento específico.

  • Parámetros:
    • sha (cadena) - SHA del fragmento de código a recuperar (obtenido de los resultados de search_code)
    • path (cadena, opcional) - Ruta del directorio RAÍZ DEL PROYECTO (igual que la usada en search_code)
  • Ubicación del fragmento: {path}/.pampa/chunks/{sha}.gz o {sha}.gz.enc
  • Devuelve: Código fuente completo

index_project

Indexa un proyecto desde el agente.

  • Parámetros:
    • path (cadena, opcional) - Ruta del directorio RAÍZ DEL PROYECTO a indexar (creará un subdirectorio .pampa/ aquí)
    • provider (cadena, opcional) - Proveedor de incrustaciones (por defecto: "auto")
  • Crea:
    • {path}/.pampa/pampa.db (base de datos SQLite con incrustaciones)
    • {path}/.pampa/chunks/ (fragmentos de código comprimidos)
    • {path}/pampa.codemap.json (índice ligero para control de versiones)
  • Efecto: Actualiza la base de datos y el codemap

update_project

🔄 CRÍTICO: ¡Usa esta herramienta con frecuencia para mantener tu memoria de IA actualizada!

Actualiza el índice del proyecto después de cambios de código (herramienta de flujo de trabajo recomendada).

  • Parámetros:
    • path (cadena, opcional) - Ruta del directorio RAÍZ DEL PROYECTO a actualizar (igual que la usada en index_project)
    • provider (cadena, opcional) - Proveedor de incrustaciones (por defecto: "auto")
  • Actualizaciones:
    • Vuelve a escanear todos los archivos en busca de cambios
    • Actualiza las incrustaciones de las funciones modificadas
    • Elimina las funciones borradas de la base de datos
    • Agrega nuevas funciones a la base de datos
  • Cuándo usarla:
    • ✅ Al inicio de las sesiones de desarrollo
    • ✅ Después de crear nuevas funciones
    • ✅ Después de modificar funciones existentes
    • ✅ Después de eliminar funciones
    • ✅ Antes de tareas importantes de análisis de código
    • ✅ Después de refactorizar código
  • Efecto: Mantiene la memoria de código de tu agente de IA sincronizada con el estado actual

get_project_stats

Obtiene estadísticas del proyecto indexado.

  • Parámetros:
    • path (cadena, opcional) - Ruta del directorio RAÍZ DEL PROYECTO donde se encuentra la base de datos de PAMPA
  • Ubicación de la base de datos: {path}/.pampa/pampa.db
  • Devuelve: Estadísticas por lenguaje y archivo

📊 Recursos MCP Disponibles

pampa://codemap

Acceso al mapa de código completo del proyecto.

pampa://overview

Resumen de las funciones principales del proyecto.

🎯 Prompts MCP Disponibles

analyze_code

Plantilla para analizar código encontrado con un enfoque específico.

find_similar_functions

Plantilla para encontrar funciones similares existentes.

🔍 Cómo Funciona la Recuperación

  • Búsqueda vectorial – Similitud de coseno con incrustaciones avanzadas de alta dimensión
  • Respaldo de resumen – Si un agente envía una consulta vacía, PAMPA devuelve resúmenes de nivel superior para que el agente entienda el territorio
  • Granularidad de fragmentos – Por defecto = función/método/clase. Ajustable por lenguaje

📝 Decisiones de Diseño

  • Solo Node → Los desarrolladores ejecutan todo mediante npx, sin Python, sin Docker
  • SQLite sobre HelixDB → Una base de datos local para vectores y relaciones, sin dependencias externas
  • Codemap comprometido → El contexto viaja con el repositorio → clonar funciona sin conexión
  • Granularidad de fragmentos → Por defecto = función/método/clase. Ajustable por lenguaje
  • Solo lectura por defecto → El servidor solo expone métodos de lectura. La escritura se realiza mediante CLI

🧩 Extendiendo PAMPA

IdeaPista
Más lenguajesInstala la gramática de tree-sitter y agrégala a LANG_RULES
Incrustaciones personalizadasExporta OPENAI_API_KEY o cambia OpenAI por cualquier proveedor que devuelva vector: number[]
SeguridadEjecuta detrás de un proxy inverso con autenticación
Plugin de VS CodeApunta un cliente MCP WebView a tu servidor local

🔐 Cifrado del Almacén de Fragmentos

PAMPA puede cifrar los cuerpos de los fragmentos en reposo usando AES-256-GCM. Configúralo así:

  1. Exporta una clave de 32 bytes en formato base64 o hexadecimal:

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

  2. Indexa con cifrado habilitado (omite escrituras en texto plano incluso si existen archivos obsoletos):

    npx pampa index --encrypt on

    Sin --encrypt, PAMPA se auto-cifra cuando la clave de entorno está presente. Usa --encrypt off para forzar texto plano (p. ej., para depuración).

  3. Todos los fragmentos nuevos se almacenan como .gz.enc y requieren la misma clave para la recuperación de fragmentos por CLI o MCP. Las claves faltantes o corruptas muestran errores claros en lugar de filtrar datos.

Los archivos de texto plano existentes siguen siendo legibles, por lo que puedes habilitar el cifrado de forma incremental o rotar claves re-indexando.

🤝 Contribuciones

  1. Fork → crea una rama de características (feat/...)
  2. Ejecuta npm test (próximamente) y npx pampa index antes del PR
  3. Abre un PR con contexto: por qué + capturas de pantalla/registros

Todas las discusiones en GitHub Issues.

📜 Licencia

MIT – haz lo que quieras, solo conserva los derechos de autor.

¡Feliz hacking! 💙

🇦🇷 Hecho con ❤️ en Argentina | 🇦🇷 Hecho con ❤️ en Argentina