Magpie Search: AI 에이전트와 LLM을 위한 통합 검색 엔진

에이전트가 작업하던 세션 도중에 컴퓨터가 재부팅되거나 정전이 발생한 적이 있나요? 에이전트가 가지고 있던 모든 스레드는 사라집니다. 이제 이를 되찾을 수 있는 도구가 있습니다.
다시는 에이전트가 무엇을 잃었는지 잊지 마세요. Magpie는 AI가 작업했던 모든 것을 로컬에서 인덱싱하므로, 충돌(crash)은 기억 상실증(amnesia) 대신 일시적인 불편함에 불과합니다.

Magpie란 무엇인가

일반적인 검색 엔진은 한 곳만 살펴봅니다. Magpie는 하나의 질문을 받아 AI의 전체 대화 기록, 기기상의 파일, 구조화된 지식 그래프(structured knowledge graph), 벡터 스토어(vector store), 그리고 실시간 웹 등 중요한 모든 곳에 동시에 퍼뜨려 검색한 후, 실제로 정보가 존재하는 곳에서 답변을 끌어옵니다.
다섯 가지 소스, 하나의 호출.

그리고 각 소스를 올바른 방식으로 검색합니다. 정확한 토큰(예: 파일 경로, 오류 메시지, 코드 한 줄)을 알고 있다면 정규 표현식(regex)으로 grep할 수 있습니다. 키워드로 검색할 수도 있고, 의미로 검색하여 단어가 일치하지 않아도 원하는 것을 찾을 수 있습니다. 이 모든 것을 동시에 수행할 수 있습니다.

그러면 신뢰성을 확보하는 역할을 합니다. 모든 정보를 단일 순위 답변으로 융합하며, 모든 결과에는 **신뢰 등급(trust tier)**이 부여됩니다—사실(fact) > 참고 자료(reference) > 유도 정보(lead) > 오래된 정보(stale)입니다. 확실한 출처가 상위에 오르고, 불확실한 출처는 검증이 필요한 유도 정보로 표시되며, 중복 내용은 통합되고, 모든 것이 AI의 컨텍스트를 넘치지 않도록 간결하게 다듬어집니다. 심층적인 조사를 요청하면 하나의 질문을 여러 개로 확장하고, 페이지들을 읽어 독립적으로 동의하는 출처가 몇 개인지 알려줍니다—여러 에이전트 부대 없이도 완벽한 연구 조사(research sweep)를 수행합니다.

이는 오직 기기에서만 실행됩니다. 서버도 없고, 계정도 없으며, 텔레메트리 기능은 사용자가 켜지 않는 한 작동하지 않습니다. AI의 기록과 파일은 절대 외부로 나가지 않습니다. MCP 위에서 구동되는 모든 AI에 플러그인되어 에이전트가 필요할 때 즉시 여섯 가지 출처 모두에 접근할 수 있게 합니다.

이는 AI를 위한 도구입니다—에이전트 또는 LLM을 위한 것입니다.

내부 구성 요소

핵심에는 AI의 기록(transcripts)을 담는 로컬 인덱스가 있습니다. 이는 두 가지 구조가 나란히 구축된 SQLite 데이터베이스입니다—

• FTS5 전체 텍스트 인덱스 (BM25 키워드 순위 지정),
• 소형 all-MiniLM-L6-v2 모델이 로컬에서 생성한 384차원 임베딩의 벡터 인덱스(sqlite-vec).

모든 데이터는 수집 시(at ingest) 마스킹 처리됩니다—스크러버가 단일 바이트가 인덱스에 도달하기 전에 약 30가지 클래스의 비밀 정보(키, 토큰, 개인 키, 연결 문자열 등)를 제거합니다.

이 인덱스 위에는 다섯 가지 검색 모드가 자리 잡고 있습니다:

• 제공자 플러그인 시스템(provider plugin system). 다섯 가지 백엔드(스크립트, 파일, 지식 그래프, 벡터, 웹)가 각각 신뢰 등급이 태그된 Hit 객체를 반환합니다.
• 팬아웃(fan-out): 하나의 쿼리가 모든 제공자에게 동시에 전송됩니다(≤8 워커). 각 제공자는 5초의 타임아웃을 가지며, 이는 실패 시 열림(fails open) 방식을 채택하여 느린 소스가 호출을 차단하는 대신 아무것도 기여하지 않습니다.
• 신뢰 가중치 RRF 융합(Trust-weighted RRF fusion): Reciprocal Rank Fusion에서 각 소스의 순위는 신뢰 가중치(fact ×3, reference ×2, lead ×1, stale ×0.3)를 곱하여 적용하며, 감쇠 상수(damping constant)는 60입니다. 이것이 여섯 가지 이질적인 소스를 하나의 정직한 순위로 병합하는 수학적 방식입니다.
• 콘텐츠 해시 기반 교차 소스 중복 제거(Cross-source dedup by content hash): 세 곳에서 발견된 동일한 사실은 하나의 Hit으로 통합되며, 다른 어디에 나타났는지도 태그됩니다(교차 검증/corroboration).
• 호출하는 AI의 컨텍스트를 넘치지 않도록 **토큰 예산 트리밍(token-budget trim)**을 수행합니다.

그리고 이 모든 것을 MCP 서버를 통해 AI에 노출시킵니다. 즉, 에이전트에게 제공되는 도구는 정확히 search, recent, session, list_sessions, stats, reindex입니다. 목록에 없는 것은 무엇일까요? 답을 작성하는 어떤 것도 없습니다.

왜 이것이 RAG가 아닌가

RAG = Retrieval-Augmented Generation(검색 증강 생성). 이는 2단계 파이프라인이며, 결정적인 단계는 두 번째 단계입니다. 검색기(retriever)가 청크를 찾고 → 이 청크들이 프롬프트에 채워지며 → 언어 모델이 산문 형태의 답변을 **생성(generates)**합니다. 'G'가 이름의 핵심 목적점이며, 생성기가 답을 작성하지 않는다면 그것은 RAG가 아닙니다.

Magpie에는 G가 없습니다:

1. 검색 경로 어디에도 생성기(generator)는 없습니다. Magpie는 자연어 답변을 구성하는 것이 아닙니다. 모델과 가장 유사한 기능인 크로스 인코더 리랭커(cross-encoder reranker)는 결과당 관련성 점수(relevance number)를 출력하고 목록을 재정렬할 뿐입니다. 이는 점수를 매길 뿐, 문장을 작성하지 않습니다.
2. '다음은 순위가 매겨진 검색 결과입니다.'에서 멈춥니다. RAG는 프롬프트 조립과 모델 호출을 담당합니다. Magpie는 통합되고 신뢰도에 따라 순위가 매겨진 결과를 반환하고 이를 MCP를 통해 전달할 뿐입니다. AI가 다음에 무엇을 할지—심지어 무언가를 생성하는지 여부까지—는 Magpie 외부, 즉 AI의 몫입니다.
3. 그 검색기(retriever)는 RAG의 검색기보다 적은 것이 아니라 더 많습니다. 교과서적인 RAG 검색기는 하나의 벡터 저장소만 사용합니다: 쿼리를 임베딩하고 코사인 유사도 기준으로 상위 k개를 가져오는 식입니다. Magpie의 검색은 여섯 가지 소스, 다섯 가지 모드, 신뢰 가중치 기반 융합(trust-weighted fusion), 크로스 소스 중복 제거를 수행합니다. 이는 훨씬 더 뛰어난 'R'이지만, 여전히 오직 'R'일 뿐입니다.

Magpie를 AI에 연결하면 두 조합이 RAG를 형성할 수 있습니다—Magpie가 R이고, 가져오는 AI가 G인 식입니다. 하지만 Magpie 자체는 오직 R만을 제공하며, 평소보다 더 강력한 R을 제공합니다. 이는 진실을 찾아내고 순위를 매길 뿐, 답변을 생성하지 않습니다.

딥 웹 검색 — 토큰 비용 없이 연구 범위 확장하기

'심층 연구(deep research)'의 비싼 부분은 **추론(reasoning)**이며, 멀티 에이전트 접근 방식은 이 비용을 N배로 지불하게 만듭니다—에이전트당 하나의 전체 LLM 컨텍스트가 필요하며, 단일 질문에 수백만 개의 토큰이 소요되기도 합니다. 그러나 추론은 분산될 필요가 없습니다; 이미 컨텍스트 내에 있는 충분한 모델 하나만으로도 종합할 수 있습니다. **검색(searching)**만이 폭넓을 필요가 있으며—웹 검색은 순수한 검색, 즉 LLM 토큰 비용이 0입니다.

magpie-search deepweb은 이러한 비대칭성에 기반합니다. 이는 여러 하위 쿼리를 웹에 병렬로 발사하고, 신뢰 가중치 RRF(Reciprocal Rank Fusion)와 URL 기반 중복 제거를 통해 이를 하나의 간결하고 토큰 예산이 절감된 소스 세트로 융합하며, 선택적으로 상위 페이지의 텍스트를 읽고(여전히 토큰 비용 없음), 결과가 얼마나 많은 독립적인 도메인에 의해 입증되는지 보고합니다—이는 연구 스웜(research swarm)이 에이전트에게 지불하는 검증 작업을 에이전트 없이 수행한 것입니다.

따라서 여러 에이전트가 페이지를 읽고 교차 검증하는 다중 에이전트 심층 검색(multi-agent deep search)의 폭넓은 범위와 페이지 읽기 기능 및 상호 검증 기능을 모두 얻으면서도, 모델은 잘라낸 결과 집합에 대해 **단일 합성 패스(single synthesis pass)**만 수행하면 됩니다.

측정된 토큰 비용 — 하나의 심층 질문:

이는 검색 및 페이지 읽기가 순수한 검색(pure retrieval)이며 (모델 토큰 없음) 모델이 잘라내고 상호 검증된 집합에 대해 최종 합성 패스만 수행하기 때문에 약 ~2,000배 적은 토큰 — 비용의 약 1/2000 수준입니다.

# 하나의 질문, 여러 각도, 상위 페이지 읽기 — 모두 토큰 무료 검색
magpie-search deepweb "질문" --q "다른 각도" --q "세 번째 각도" --thorough

이후 루프 내의 모델은 병합되고 상호 검증된 집합에 대해 단일 합성 패스를 수행합니다. 이것이 전체 절약점입니다: 폭넓은 범위는 무료이며, 답변에 대해서만 비용을 지불하는 것입니다.

설치 (Install)

pip install magpie-search

실시간 웹 검색 및 deepweb에는 web 추가 기능이 필요합니다:

pip install "magpie-search[web]"

이것 없이는 --sources web과 deepweb이 결과를 반환하지 않습니다 — 웹 제공업체는 페더레이티드 검색(federated search)을 절대 중단시키지 않도록 설계되었기 때문에, 누락된 종속성은 마치 아무것도 찾지 못한 검색처럼 보입니다. 1.3.1 버전부터는 조용히 실패하는 대신 표준 에러 스트림(stderr)에 한 줄의 이유를 출력합니다.

또는 소스에서 최신 버전을 설치할 수 있습니다:

pip install "git+https://github.com/xfloukiex-lab/magpie-search.git#egg=magpie-search[web]"

선택 사항 — 로컬 LLM 기능을 추가합니다 (크로스 인코더 재순위 지정기(cross-encoder reranker)는 기본 설치에서 실행되며, 세션 요약기는 Ollama가 필요합니다):

# 1. Ollama 설치 (무료이며 완전히 로컬에서 실행됨) — https://ollama.com/download
# 2. magpie-search가 사용하는 모델 풀링
olama pull phi3.5

Windows, macOS 및 Linux의 Python 3.10 이상.

빠른 시작 (Quickstart)

magpie-search index                               # 인덱스 구축 (증분)
magpie-search search "that retry backoff thing"   # 키워드 검색
magpie-search search --mode hybrid "..."          # 키워드 + 의미론적, 융합
...

AI에 연결하기 (MCP)

Magpie는 Model Context Protocol을 사용하므로, MCP를 지원하는 모든 에이전트가 이를 호출할 수 있습니다. 클라이언트를 번들된 서버로 지정하세요:

// 예: MCP 클라이언트 설정
{
  "mcpServers": {
...

그러면 해당 에이전트는 search, recent, session, list_sessions, stats, 그리고 reindex를 사용할 수 있게 됩니다. 이 기능들은 연합(federated), 신뢰 등급 지정(trust-ranked), 컨텍스트 예산 할당(context-budgeted) 방식으로 제공됩니다.

CLI 참고 자료

| 명령어 | 설명 | |
|---|---| |
| magpie-search index | ~/.claude/projects/에 대한 증분 인덱싱 패스 |
| ... | |
모든 옵션은 어떤 명령어에도 --help를 추가하여 확인할 수 있습니다.

Python API

import magpie_search

results = magpie_search.search("retry backoff", mode="hybrid", k=5)
...

백업

magpie-search backup은 사용자가 선택한 목적지(로컬 폴더(기본값, 설정 불필요), 원격 SSH 대상(NAS / 홈 서버), 또는 VM 부팅/일시 중지 기능이 있는 원격 SSH 대상)로 전사 기록 트리(transcript tree)를 복사합니다. 이는 ~/.magpie-search/backup.env에서 구성할 수 있습니다:

[email protected]
MAGPIE_SEARCH_BACKUP_SSH_DEST=~/claude-transcripts/

유용한 플래그: --dry-run, --no-suspend, --show-config. 백업은 복사본을 만들 뿐, 원본을 절대 삭제하지 않습니다.

설정

모든 것은 환경 변수 기반이며 합리적인 기본값을 가집니다.

| 변수 | 기본값 | 설명 | |
|---|---| :---|
| MAGPIE_SEARCH_HOME | ~/.magpie-search | 데이터 디렉토리 (DB, 모델, 로그) |
| ... | |
요약기는 6가지 프로브 가드레일 스택(길이, 고유 명사 안전성, 식별자 안전성, 거부 드리프트, 의미론적 접지(semantic-grounding), 자체 검증(self-verify))을 통과합니다. trust: clean 상태가 되려면 이 여섯 가지 모두를 통과해야 합니다. 하나라도 실패하면 요약은 생략되고 trust: degraded가 반환됩니다. 잘못된 정보보다는 침묵하는 것을 선호합니다. 원본 메시지는 magpie-search session SESSION-ID를 통해 계속 접근할 수 있습니다.

개인정보 보호

Magpie Search는 로컬 도구입니다. 서버도, 계정도, 자동 업데이트도, 충돌 보고기도 없으며, 명시적으로 옵트인하지 않는 한 텔레메트리(telemetry)를 전송하지 않습니다 (아래 참조). 사용자의 스크립트, 인덱스, 감사 로그(audit log), 모델 캐시, 백업은 모두 사용자 기기에 저장됩니다.

옵트인 텔레메트리. 텔레메트리는 기본적으로 꺼져 있습니다 — magpie는 magpie-search telemetry enable을 실행하거나 (MAGPIE_SEARCH_TELEMETRY=1로 설정) 하기 전까지 아무것도 보내지 않습니다. 활성화된 경우, 익명 사용량(anonymous usage)만 전송합니다: 어떤 명령이 실행되었는지, 검색 모드, 결과/히트 횟수, 지연 시간(latency), 오류 클래스, 그리고 사용자 magpie/python/OS 버전과 무작위 설치 ID가 태그됩니다. 사용자의 질의(queries), 파일 경로, 결과, 스크립트 내용, 사용자 이름 또는 IP는 절대 전송하지 않습니다 — telemetry.py에 있는 강력한 콘텐츠 방화벽이 숫자나 짧은 열거형 토큰(enum token)이 아닌 모든 것을 차단합니다. 언제든지 magpie-search telemetry disable로 비활성화할 수 있으며, 상태는 magpie-search telemetry status로 확인할 수 있습니다. 이 도구가 수행하는 유일한 네트워크 호출은 다음과 같습니다: 로컬 Ollama 서버 (LLM 기능), 사용자의 백업 대상 (오직 backup을 실행할 때만), 그리고 첫 실행 시 Hugging Face로부터의 일회성 모델 다운로드입니다. tcpdump, Wireshark 또는 네트워크 차단 샌드박스를 사용하여 직접 확인해 보세요.

스케줄링(Scheduling)

정기적으로 magpie-search index (선택적으로 backup)를 실행하세요. 시스템d(Linux), launchd(macOS), 그리고 Task Scheduler(Windows)용으로 바로 사용할 수 있는 유닛이 installers/에 있습니다.

문제 해결(Troubleshooting)