Ephemeral Buffer MCP Server (ephemeral-buffer)

AI 코딩 어시스턴트(Claude Code, Antigravity, Cursor 등)를 위한 임시 인메모리 명령 출력 캡처 및 하이브리드 검색 엔진(BM25 + 시맨틱 임베딩)입니다.

🎯 이 도구가 해결하는 문제

코딩 에이전트가 대량의 출력(수천 줄의 빌드 로그, 테스트 실행, 스택 트레이스, JSON 덤프)을 생성하는 명령을 실행할 때, 에이전트는 두 가지 실패 모드에 직면합니다:

1. 컨텍스트 오염: 수 메가바이트의 원시 텍스트를 입력하면 토큰 한도를 초과하고 모델 추론 능력이 저하됩니다.

2. 맹목적 Bash 필터링: 에이전트는 오류 패턴을 추측하기 위해 head, tail, grep, awk를 실행하며 여러 턴을 낭비합니다.

Related MCP server: Qurio MCP Server

💡 해결책

ephemeral-buffer는 이중 하이브리드 인덱싱을 갖춘 일시적인 인메모리 링 버퍼를 제공합니다:

• BM25 어휘 검색(SQLite FTS5): 오류 코드(NullPointerException, ECONNREFUSED, exit 137, HTTP 502)의 정확한 일치를 위한 검색입니다.

• 밀집 시맨틱 벡터 검색(FastEmbed ONNX): 모호한 개념적 질의("DB 연결 풀이 어디서 실패했나요?" 또는 "인증이 왜 실패했나요?")를 위한 검색입니다.

• 상호 순위 융합(RRF): 어휘 및 시맨틱 순위를 혼합하여 높은 정밀도의 검색을 제공합니다.

• 링 버퍼 축출: 마지막 $N$개 캡처(기본값: 10)만 보관하여 영구 저장소 누적이나 메모리 누수가 없도록 보장합니다.

🏗 아키텍처 및 흐름

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

🚀 사용 방법

1. 터미널에서(CLI 파이프 via agy-cap)

실행 중인 MCP 서버로 명령 출력을 직접 파이프할 수 있습니다:

# 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. AI 에이전트에서 MCP 도구를 통해

에이전트는 다음 도구에 접근할 수 있습니다:

🛠 서버 테스트

테스트 스위트를 실행합니다:

./venv/bin/python test_engine.py