Waggle-mcp

왜 waggle-mcp인가요?

대부분의 LLM은 대화가 끝나면 모든 것을 잊어버립니다. waggle-mcp는 MCP 호환 클라이언트를 통해 읽고 쓸 수 있는 영구적인 지식 그래프를 AI에 제공하여 이 문제를 해결합니다.

Waggle의 핵심 장점은 구조화된 맥락을 통한 토큰 효율성입니다:

검색 참고: Waggle은 원시 회상 범위를 일부 희생하는 대신 토큰 비용을 획기적으로 낮추고 관계형 맥락을 풍부하게 제공합니다. 정확한 수치는 벤치마크 섹션을 참조하세요.

30초 만에 시작하기

pip install waggle-mcp
waggle-mcp init

init 마법사는 MCP 클라이언트를 감지하고, 설정 파일을 작성하며, 데이터베이스 디렉토리를 생성합니다. JSON을 직접 수정할 필요가 없습니다. Claude Desktop, Cursor, Codex 및 일반 JSON 폴백을 지원합니다.

초기화 후 MCP 클라이언트를 재시작하면 AI가 영구적인 메모리를 갖게 됩니다. 클라우드 서비스나 API 키가 필요 없습니다. 의미론적 검색은 완전히 로컬에서 실행됩니다.

실제 작동 모습

AI를 매일 사용하는 개발자의 실제 사용 전/후 사례입니다:

세션 1 — 4월 10일

User:  Let's use PostgreSQL. MySQL replication has been painful.
Agent: [calls observe_conversation()]
       → stores decision node: "Chose PostgreSQL over MySQL"
       → stores reason node:   "MySQL replication painful"
       → links them with a depends_on edge

세션 2 — 4월 12일 (새로운 맥락 창, 이전 기록 없음)

User:  What did we decide about the database?
Agent: [calls query_graph("database decision")]
       → retrieves the decision node + linked reason from April 10

       "You decided on PostgreSQL on April 10. The reason recorded was
        that MySQL replication had been painful."

세션 3 — 4월 14일

User:  Actually, let's reconsider — the team is more familiar with MySQL.
Agent: [calls store_node() + store_edge(new_node → old_node, "contradicts")]
       → conflict is flagged automatically; both positions are preserved in the graph

에이전트는 기억하거나 검색하라는 명시적인 지시를 받은 적이 없습니다. 대화에 따라 적절한 도구를 호출했고, 그래프가 올바른 맥락을 제공했습니다.

작동 원리

메모리는 단순히 저장되는 것이 아니라 수명 주기를 따라 흐릅니다:

You talk to your AI
        │
        ▼
  observe_conversation()          ← AI drops the turn in; facts extracted via structured LLM (regex fallback)
        │
        ▼
  Graph nodes are created         ← "Chose PostgreSQL" becomes a decision node
  Edges are inferred              ← linked to the "database" entity node
        │
        ▼
  Future conversation starts
        │
        ▼
  query_graph("DB schema")        ← semantic search finds the node from 3 sessions ago
        │
        ▼
  AI answers with full context    ← "You decided on PostgreSQL on Apr 10, here's why…"

모든 노드는 all-MiniLM-L6-v2를 사용하여 로컬에서 계산된 의미론적 임베딩을 가집니다. 이는 API 키나 네트워크 호출 없이 장치 내에서 완전히 실행되는 빠르고 가벼운 모델입니다. 즉, 의미론적 검색이 오프라인에서도 작동하며, 쿼리당 비용이 발생하지 않고, 데이터가 비공개로 유지됩니다.

마법의 도구: observe_conversation

가장 많이 사용하게 될 도구입니다. 사실을 수동으로 저장할 필요가 없습니다. 에이전트에게 대화의 각 턴을 관찰하도록 지시하기만 하면 나머지는 알아서 처리합니다.

observe_conversation(user_message, assistant_response)

내부적으로는 다음을 수행합니다:

1. 대화 양측에서 원자적 사실을 추출합니다.

2. 의미론적 유사성을 사용하여 기존 노드와 중복을 제거합니다.

3. 관련 개념 간에 타입이 지정된 엣지를 생성합니다.

4. 기존에 저장된 신념과의 모순을 표시합니다.

지시사항이 필요 없습니다. 정의할 스키마도 없습니다. 그냥 관찰하세요.

모든 호출은 내부적으로 Pydantic으로 검증된 LLM 추출 패스(정규식 폴백 포함)를 실행하여 복잡한 대화에서 구조화된 사실을 뽑아냅니다.

예시: "MySQL 복제는 너무 고통스러우니 PostgreSQL을 사용합시다."

{
  "facts": [
    {
      "label": "PostgreSQL for generic events",
      "content": "Chose PostgreSQL over MySQL because MySQL replication is too painful.",
      "node_type": "decision",
      "confidence": 0.95,
      "tags": ["llm-extracted", "confidence:0.95"]
    }
  ]
}

confidence < 0.5이거나 스키마가 유효하지 않은 추출 결과는 환각 노이즈를 방지하기 위해 조용히 삭제됩니다.

메모리 모델

노드 타입 — 저장되는 내용:

엣지 타입 — 노드 연결 방식:

relates_to · contradicts · depends_on · part_of · updates · derived_from · similar_to

MCP 도구

AI가 직접 호출하므로 수동으로 사용할 필요가 없습니다.

성능 및 벤치마킹

아래 모든 수치는 scripts/benchmark_extraction.py의 하네스를 사용하여 benchmarks/fixtures/에 체크인된 픽스처에서 재현 가능합니다. 저장된 출력 아티팩트는 tests/artifacts/에 있습니다.

명령어 하나로 아래 모든 표를 생성합니다 (추출 정규식 기준, 검색, 중복 제거 및 비교 토큰 효율성 파일럿):

PYTHONPATH=src .venv/bin/python scripts/benchmark_extraction.py \
  --extraction-backend regex \
  --systems waggle rag_naive \
  --output tests/artifacts/benchmark_current.json

LLM 추출 행(75%)은 로컬 Ollama 인스턴스를 사용한 별도의 실행이 필요하며 benchmark_current.json에는 포함되지 않습니다:

# Requires Ollama running locally with qwen2.5:7b pulled
PYTHONPATH=src .venv/bin/python scripts/benchmark_extraction.py \
  --extraction-backend llm --ollama-model qwen2.5:7b --ollama-timeout-seconds 30

추출 정확도

말뭉치: 단순 회상, 중단, 반전, 모호한 진술 및 상충되는 신호를 포함하는 12개의 대화 쌍 (benchmarks/fixtures/extraction_cases.json).

검색 정확도

말뭉치: 18개 노드, 18개 쿼리 — 6개 쉬움(직접적인 의역) 및 12개 어려움(적대적: 의미론적 일반화, 시간적 모호성 해소, 간접적 도메인 번역, 개인정보 프레이밍). 출처: benchmarks/fixtures/retrieval_cases.json.

단순 청크 기반 벡터 RAG 대비 토큰 효율성

위의 검색 정확도 표는 Waggle의 독립형 검색 품질을 측정합니다. 아래 비교는 청크 기반 벡터 기준 대비 토큰 효율성을 테스트하기 위해 설계된 별도의 멀티 세션 말뭉치를 사용합니다.

말뭉치: 24개 멀티 세션 시나리오, 7개 작업군에 걸친 66개 검색 쿼리 (benchmarks/fixtures/comparative_eval.json).

Waggle은 이 말뭉치에서 단순 청크 기준보다 검색당 ~4배 적은 토큰을 사용합니다.

Waggle의 Hit@k(91%)와 정확한 지원(74%) 사이의 격차는 그래프 검색이 올바른 주제를 찾지만 때때로 충분한 뒷받침 세부 정보를 반환하지 못함을 나타냅니다. 이는 cross_scenario_synthesis 쿼리에서 가장 두드러집니다(8/8 히트, 1/8 정확). 맥락 조립 개선, 특히 엣지 탐색 깊이와 다중 홉 서브그래프 확장이 다음 단계로 추적되고 있습니다.

트레이드오프는 정직합니다. 청크 기반 기준은 top_k=5에서 모든 사실을 자체 세션 청크에서 검색할 수 있기 때문에 이 말뭉치에서 100% Hit@k를 달성합니다. 토큰 효율성 이점은 실질적이고 재현 가능합니다. 검색 우위 주장은 청크 범위가 누락된 관계형 맥락을 보상할 수 없는 말뭉치가 필요합니다. 말뭉치 강화가 진행 중입니다.

추출 실패 시

사용자: "네, 우리가 이야기했던 그 일을 그냥 합시다."

LLM은 모호한 입력에 낮은 신뢰도(confidence < 0.5)를 할당합니다. Waggle은 추측을 저장하는 대신 추출을 조용히 삭제합니다. 파이프라인은 타임아웃 시 정규식으로 조용히 폴백하지 않으며, 백엔드 실패는 기록되는 명시적인 오류로 나타납니다.

말뭉치: 22개 노드 쌍 — 11개 실제 중복(동의어, 의역, 도메인 동등성) 및 11개 거짓 친구(같은 기술 범주, 다른 기술). 출처: benchmarks/fixtures/dedup_cases.json.

파이프라인은 5개 계층을 실행합니다:

1. 계층 0 — 엔티티 키 하드 블록 — 두 노드가 같은 범주에서 다른 기술을 명명하는 경우(예: postgresql vs mysql), 병합이 무조건 차단됩니다.

2. 계층 0b — 숫자 충돌 방지 — 같은 엔티티이지만 다른 중요 숫자(예: jwt 15분 vs 1시간) → 차단. 기술은 공유하지만 핵심 값이 다른 별개의 사실이 병합되는 것을 방지합니다.

3. 계층 1 — 정확한 문자열 일치 — 정규화된 내용 또는 레이블 동일성.

4. 계층 2 — 부분 문자열 포함 — 한 문장이 다른 문장의 엄격한 하위 집합인 경우.

5. 계층 3 — 의미론적 유사성 — all-MiniLM-L6-v2를 통한 코사인:

   • 엔티티 동일성 공격적 경로: 둘 다 같은 엔티티 토큰을 참조하는 경우, 코사인 ≥ 0.60에서 병합 (의역 중복 포착: "fastapi가 선택됨" / "비동기 때문에 fastapi를 선택함")

   • 타입 인식 임계값: decision/preference → 0.82; fact → 0.92; entity → 0.97

   • 자카드 부스트 경로: 단어 중복 ≥ 0.35 AND 코사인 ≥ (타입 임계값 − 0.05)

   • 보수