Ephemeral Buffer MCP Server (ephemeral-buffer)

Eine flüchtige In-Memory-Befehlserfassungs- und Hybrid-Such-Engine (BM25 + Semantic Embeddings) für KI-Codierungsassistenten (Claude Code, Antigravity, Cursor usw.).

🎯 Das Problem, das dies löst

Wenn Codierungsagenten Befehle ausführen, die große Ausgaben erzeugen (Tausende von Zeilen Build-Logs, Testläufe, Stack-Traces, JSON-Dumps), stehen Agenten vor zwei Fehlerarten:

1. Kontextverschmutzung: Das Aufnehmen von Megabyte an Rohtext sprengt Token-Limits und beeinträchtigt die Modellschlussfolgerung.

2. Blindes Bash-Filtern: Agenten verschwenden mehrere Runden damit, head, tail, grep und awk auszuführen, um Fehlermuster zu erraten.

Related MCP server: Qurio MCP Server

💡 Die Lösung

ephemeral-buffer bietet einen transienten In-Memory-Ringpuffer mit dualem Hybrid-Indexing:

• BM25-Lexikalsuche (SQLite FTS5): Für exakte Übereinstimmungen bei Fehlercodes (NullPointerException, ECONNREFUSED, exit 137, HTTP 502).

• Dichte semantische Vektorsuche (FastEmbed ONNX): Für unscharfe konzeptionelle Abfragen ("Wo ist der DB-Verbindungspool fehlgeschlagen?" oder "Warum ist die Authentifizierung fehlgeschlagen?").

• Reciprocal Rank Fusion (RRF): Kombiniert lexikalisches und semantisches Ranking für eine hohe Präzision beim Abruf.

• Ringpuffer-Eviction: Hält nur die letzten $N$ Erfassungen (Standard: 10) und gewährleistet so keinen dauerhaften Speicherzuwachs oder Speicherlecks.

🏗 Architektur & Ablauf

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

🚀 Verwendung

1. Vom Terminal (CLI-Pipe über agy-cap)

Sie können die Befehlsausgabe direkt in den laufenden MCP-Server leiten:

# 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. Vom KI-Agenten über MCP-Tools

Der Agent hat Zugriff auf die folgenden Tools:

🛠 Testen des Servers

Führen Sie die Testsuite aus:

./venv/bin/python test_engine.py