chunxiaoxx/nautilus-compass

nautilus‑compass – AI 에이전트를 위한 오픈소스 메모리 및 신뢰성 레이어

정의 – 로컬에서 실행되는 플러그인 스타일 서비스로, 대규모 언어 모델 에이전트에 장기 메모리 저장소, 드리프트 감지 가드, 멀티 에이전트 워크플로우를 위한 경량 거버넌스 시스템을 제공합니다. Python 패키지(nautilus‑compass), Model‑Context‑Protocol(MCP) 서버, 명령줄 도구 세트로 제공됩니다.

중요성 –

• 최첨단 검색 – BGE‑m3 임베딩 모델과 하이브리드 BM25＋dense‑RRF 검색을 사용합니다. 공개 벤치마크 LongMemEval‑S에서 P@1 0.890, P@5 0.978, MRR 0.929를 기록하여 인기 있는 mem0 베이스라인을 10퍼센트 포인트 이상 능가하면서 완전히 로컬에서 실행되고 약 14배 저렴합니다.
• 드리프트 감지 – 모든 프롬프트는 선별된 실패 패턴 '앵커' 세트와 비교됩니다. 감지기는 보류 데이터에서 AUC 0.83을 달성하고, 지연 시간은 50ms 미만이며, 프로덕션 트래픽의 약 0.5%에서만 작동합니다.
• 크로스 에이전트 계약 – 여러 Claude 기반 에이전트가 파일을 공유할 때 플러그인은 암시적 핸드오프 계약을 추론하고, 완료를 추적하며, '가짜 완료' 또는 규칙 드리프트를 감사합니다. 28시간 현장 연구가 저장소에 문서화되어 있습니다.
• 개방적이고 재현 가능한 증거 – 모든 벤치마크 실행, 데이터, 스크립트는 저장소에 있습니다(예: scripts/reproduce_lmes_retrieval.sh). 저자는 논문, Hugging Face 데이터 세트, 라이브 데모 스페이스도 게시합니다.

사용 방법

1. 설치 – pip install nautilus-compass(CLI, MCP 서버, A2A 어댑터 설치).
2. MCP 클라이언트에 연결 – 저장소는 Claude Desktop(또는 Cursor, Cline, Continue.dev, Zed 등)에 세 개의 후크를 추가하는 작은 설치 프로그램을 제공하여 사용자 프롬프트가 제출될 때마다 시스템이 다음을 수행합니다:
   • 가장 관련성 높은 과거 메모리 청크를 호출하고,
   • 드리프트 검사를 실행하고,
   • 프로필 요약을 추가합니다.
3. 데몬 실행 – BGE‑m3 임베딩 데몬은 부팅 시 한 번 시작됩니다(daemon_start.sh). 데몬은 디렉토리를 감시하고(inotify), 새 파일을 인덱싱하고, 빠른 호출 쿼리를 제공합니다.
4. 선택적 클라우드 게이트웨이 – 관리형 서비스를 선호하는 팀을 위해 호스팅된 멀티 테넌트 MCP 엔드포인트(https://compass.nautilus.social/mcp/)를 사용할 수 있습니다. 토큰은 사용자별로 범위가 지정되며 모든 트래픽은 mTLS로 보호됩니다.

주요 명령/도구(MCP JSON‑RPC를 통해 노출):

도구	기능	일반적인 지연 시간
ingest_obs	새 관찰 저장(드리프트용 자동 앵커)	~150 ms
recall	인덱싱된 모든 텍스트에서 의미론적＋키워드 검색	~200 ms
session_search	단일 채팅 세션 내 시간 버킷 검색	~80 ms
drift_check	실패 앵커에 대해 프롬프트 점수 매기기	<50 ms
profile	에이전트의 현재 작업 부하 및 드리프트 추세 요약	~100 ms

벤치마크 한눈에 보기

벤치마크	점수(compass)	비교
LongMemEval‑S(500문항)	P@1 0.890, P@5 0.978, MRR 0.929	mem0 0.774/0.916/0.834 능가
LOCOMO‑10(1,986문항)	P@1 0.644, P@5 0.890, MRR 0.740	mem0보다 +5.2포인트
EverMemBench‑Dynamic	44.4% – 47.3%	게시된 4개 베이스라인 중 최고
드리프트 감지기 AUC	0.83(보류 데이터)	드리프트 감지를 제공하는 유일한 공개 메모리 레이어
500문항 평가당 비용	≈ $3.50	GPT‑4o 판정 스택보다 약 14배 저렴

AI 스택에서의 위치

• 메모리 레이어 – LLM과 사용자 사이에 위치하여 데이터를 기기 외부로 보내지 않고 장기적이고 검색 가능한 컨텍스트를 제공합니다.
• 신뢰성 가드 – 드리프트 감지기는 안전망 역할을 하여 모델이 출력을 생성하기 전에 알려진 실패 패턴과 유사한 프롬프트를 플래그합니다.
• 거버넌스 – 계약 시스템은 공유 리소스에서 작동하는 여러 에이전트를 팀이 조정하는 데 도움이 됩니다.

빠른 시작(Claude Desktop 예시)

# Claude의 플러그인 폴더에 클론
 git clone https://github.com/chunxiaoxx/nautilus-compass ~/.claude/plugins/nautilus-compass
bash ~/.claude/plugins/nautilus-compass/install.sh   # 후크 및 데몬 설치
bash ~/.claude/plugins/nautilus-compass/daemon_start.sh

그 후 Claude에서 /compass-recall <query>를 입력하면 가장 일치하는 메모리 청크가 반환되고 시스템은 모든 프롬프트에서 자동으로 드리프트 검사를 실행합니다.

리소스

• PyPI – nautilus-compass(v3.3.0) – CLI, 서버, 어댑터.
• 논문 및 증거 – paper/BLACKBOX_VS_WHITEBOX.md, 벤치마크 JSON 파일, 전체 재현 스크립트.
• 라이브 데모 – Hugging Face Space: https://huggingface.co/spaces/chunxiaox/nautilus-compass
• 판정용 모델 – nautilus-compass/nacre-judge-v1(1.7 B LoRA) on Hugging Face.
• MCP 레지스트리 항목 – io.github.chunxiaoxx/nautilus-compass.

---

위의 모든 진술은 저장소의 README에서 직접 가져온 것이며 추가 기능은 추론되지 않았습니다.