Ephemeral Buffer MCP Server (ephemeral-buffer)

An ephemeral in-memory command output capture and hybrid search engine (BM25 + Semantic Embeddings) for AI coding assistants (Claude Code, Antigravity, Cursor, etc.).

🎯 The Problem This Solves

When coding agents run commands that generate large outputs (thousands of lines of build logs, test runs, stack traces, JSON dumps), agents face two failure modes:

1. Context Pollution: Ingesting megabytes of raw text blows out token limits and degrades model reasoning.

2. Blind Bash Filtering: Agents waste multiple turns running head, tail, grep, and awk trying to guess error patterns.

Related MCP server: Qurio MCP Server

💡 The Solution

ephemeral-buffer provides a transient in-memory ring buffer with Dual Hybrid Indexing:

• BM25 Lexical Search (SQLite FTS5): For exact matches on error codes (NullPointerException, ECONNREFUSED, exit 137, HTTP 502).

• Dense Semantic Vector Search (FastEmbed ONNX): For fuzzy conceptual queries ("Where did the DB connection pool fail?" or "Why did authentication fail?").

• Reciprocal Rank Fusion (RRF): Blends lexical and semantic ranking for high precision retrieval.

• Ring Buffer Eviction: Holds only the last $N$ captures (default: 10), ensuring zero persistent storage buildup or memory leaks.

🏗 Architecture & Flow

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

🚀 How to Use It

1. From the Terminal (CLI Pipe via agy-cap)

You can pipe command output directly into the running MCP server:

# 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. From the AI Agent via MCP Tools

The agent has access to the following tools:

🛠 Testing the Server

Run the test suite:

./venv/bin/python test_engine.py