Ephemeral Buffer MCP Server (ephemeral-buffer)

Un motor de captura de salida de comandos en memoria efímera y búsqueda híbrida (BM25 + Semantic Embeddings) para asistentes de codificación de IA (Claude Code, Antigravity, Cursor, etc.).

🎯 El problema que resuelve

Cuando los agentes de codificación ejecutan comandos que generan grandes salidas (miles de líneas de registros de compilación, ejecuciones de pruebas, trazas de pila, volcados JSON), los agentes se enfrentan a dos modos de fallo:

1. Contaminación del contexto: Ingerir megabytes de texto sin procesar agota los límites de tokens y degrada el razonamiento del modelo.

2. Filtrado Bash a ciegas: Los agentes pierden múltiples turnos ejecutando head, tail, grep y awk tratando de adivinar patrones de error.

Related MCP server: Qurio MCP Server

💡 La solución

ephemeral-buffer proporciona un búfer circular en memoria transitorio con Indexación Híbrida Dual:

• Búsqueda léxica BM25 (SQLite FTS5): Para coincidencias exactas en códigos de error (NullPointerException, ECONNREFUSED, exit 137, HTTP 502).

• Búsqueda densa de vectores semánticos (FastEmbed ONNX): Para consultas conceptuales difusas ("¿Dónde falló el grupo de conexiones de la base de datos?" o "¿Por qué falló la autenticación?").

• Fusión de rango recíproco (RRF): Combina la clasificación léxica y semántica para una recuperación de alta precisión.

• Desalojo de búfer circular: Mantiene solo las últimas $N$ capturas (por defecto: 10), asegurando cero acumulación de almacenamiento persistente o fugas de memoria.

🏗 Arquitectura y flujo

flowchart TD
    subgraph Ingestion["1. Ingestion Paths"]
        A["CLI Pipe: command 2>&1 | agy-cap"] --> D["Unix Socket (/tmp/ephemeral_buffer.sock)"]
        B["Agent Tool: execute_and_capture(cmd)"] --> E["Ephemeral Ring Buffer Engine"]
        C["Agent Tool: capture_text / capture_file"] --> E
        D --> E
    end

    subgraph Indexing["2. Dual Hybrid Indexing"]
        E --> F["SQLite FTS5 (BM25 Lexical)"]
        E --> G["FastEmbed ONNX (Dense Vectors)"]
    end

    subgraph Querying["3. Agent Query & Retrieval"]
        F & G --> H["Reciprocal Rank Fusion (RRF)"]
        H --> I["search_capture(query, mode='hybrid')"]
        I --> J["Precise Context Chunk + Line Numbers"]
    end

🚀 Cómo usarlo

1. Desde la terminal (tubería CLI a través de agy-cap)

Puedes canalizar la salida de comandos directamente al servidor MCP en ejecución:

# Pipe any command output into the buffer
pytest -v 2>&1 | agy-cap --label "pytest run"

# Or wrap command execution
agy-cap --label "backend build" -- cargo build --verbose

2. Desde el agente de IA a través de herramientas MCP

El agente tiene acceso a las siguientes herramientas:

🛠 Probando el servidor

Ejecuta la suite de pruebas:

./venv/bin/python test_engine.py