elstongun/leviathan

Deep memory for agents over large datasets. Leviathan is a single static binary that turns your records (JSONL, JSON, CSV/TSV, SQLite, or anything a database CLI can export) into a ranked full-text index.

Leviathan – 빠르고 토큰 효율적인 AI 에이전트용 메모리

Leviathan은 단일 바이너리 Rust 도구로, 표 형식 또는 JSON 유사 데이터 소스(CSV/TSV, JSONL, SQLite 또는 데이터베이스 CLI 출력)를 전문 검색 가능한 SQLite 인덱스로 변환합니다. 에이전트는 자연어 질문을 하고 가장 관련성 높은 레코드를 포함하는 짧고 인용이 풍부한 "카드"를 받을 수 있습니다. 일반적으로 수백만 토큰 대신 수백 토큰만 사용합니다.

기능

기능	제공 내용
범용 수집	`leviathan index`는 JSONL, CSV, TSV, SQLite 파일 또는 JSON 행을 스트리밍하는 모든 명령(예: `psql … -c "SELECT row_to_json(t) FROM …"`)을 읽습니다.
스키마 매핑	작은 `leviathan.toml` 파일이 Leviathan에 레코드 `id` 필드, `title`, `text`, `group`, `date` 등의 필드를 알려줍니다. `id`만 필수입니다.
전문 검색 + BM25 순위	레코드는 SQLite FTS5 테이블에 저장됩니다. 쿼리는 선택적 필드별 가중치와 함께 BM25로 순위가 매겨집니다.
그룹 범위 검색	`-g <group>`은 결과를 고객, 프로젝트 또는 논리적 버킷으로 제한합니다. 알 수 없는 그룹은 추측하지 않고 보고됩니다.
토큰 예산 응답	도구는 LLM 컨텍스트 창에 잘 맞는 고정 크기 "카드"(약 450토큰)를 반환합니다.
증분 업데이트	`upsert` 및 `delete`는 인덱스를 원자적으로 수정하여 전체 재구축 없이 최신 상태를 유지합니다.
에이전트 통합	Claude, Cursor, VS Code/Copilot, Gemini CLI 등을 위한 준비된 스킬이 포함되어 있습니다. 래퍼(`leviathan wrap <agent>`)는 해당 에이전트에 필요한 구성을 생성합니다.
선택적 메모리 계층	두 번째 SQLite 파일에 키-값 "메모리"를 저장할 수 있으며, 에이전트는 토큰 예산 내에서 `remember` 및 `recall`할 수 있습니다.
MCP / HTTP 서버	`leviathan mcp`는 stdio 기반 Multi-Client-Protocol을 통해 동일한 도구를 노출합니다. `leviathan serve --http`는 bearer-token 또는 OAuth2.1 인증을 사용하는 REST/OpenAPI 엔드포인트를 제공합니다.
런타임 종속성 없음	인덱스는 일반 SQLite 파일이며 바이너리는 자체 포함되어 있습니다.

일반적인 워크플로우

스키마 생성 – leviathan init ./export는 편집할 수 있는 주석이 달린 leviathan.toml을 생성합니다.
인덱스 구축 – leviathan index tickets.csv --id "Ticket ID" --group customer_id --date created_at (또는 모든 DB에서 JSON 파이프).
쿼리 – leviathan search -g acme "sso login loop after password reset"는 간결하고 인용된 카드를 반환합니다.
에이전트에 연결 – skills/leviathan을 에이전트의 스킬 디렉토리에 복사하거나 leviathan wrap claude --memory --apply를 실행하여 LLM이 호출할 수 있는 도구를 추가합니다.

작동 방식 (높은 수준)

수집 – 행이 스트리밍되고 각 필드가 토큰화되며 레코드는 FTS5 가상 테이블을 포함하는 SQLite 파일에 삽입됩니다.
쿼리 처리 – 도구는 요청된 그룹(정확히 일치 → 이름 → 퍼지)을 해결하고 그룹 및 필터 토큰을 포함하는 단일 FTS5 쿼리를 구성하고 실행합니다.
순위 – 결과는 BM25 × 사용자 지정 가중치(예: title 2배 가중치)로 점수가 매겨집니다.
카드 생성 – 상위 N개 레코드만 디코딩되고 토큰 예산으로 잘린 다음 인용, 날짜 및 display 필드와 함께 형식화됩니다.
메모리 (선택 사항) – 별도의 SQLite 파일에 키-값 쌍이 저장됩니다. 각 쓰기는 동일한 키의 이전 값을 대체하여 메모리 일관성을 유지합니다.

벤치마크 (저장소에서)

1백만 레코드 (약 678MB) → 중앙값 응답 크기 436토큰 vs. >100k 토큰이 필요한 순진한 grep.
관련 레코드 재현율 – 상위 5개 결과의 99%가 올바른 레코드를 포함합니다. rank-1 재현율은 98.5%입니다.
지연 시간 – 쿼리당 중앙값 33ms (최상의 grep 전략의 92ms 대비).
메모리 토큰 예산 – 300세션 후 33K 토큰 마크다운 메모리 파일이 로드 시 약 736토큰으로 줄어듭니다.

누가 사용할까요?

대규모 티켓 또는 로그 데이터베이스에 대한 빠르고 토큰 효율적인 액세스가 필요한 LLM 기반 지원 에이전트.
검색 단계가 제한된 컨텍스트 창 내에 있어야 하는 RAG 파이프라인.
별도의 벡터 저장소 없이 플러그 앤 플레이 "지식 베이스"를 원하는 자율 에이전트 개발자 (Claude, Gemini, ChatGPT 플러그인 등).
CSV/SQLite에 로그를 이미 저장하고 종속성 없는 오프라인 검색 가능한 인덱스를 원하는 데이터 중심 팀.

시작하기

# crates.io에서 바이너리 설치 (또는 Git에서 직접)
cargo install leviathan-index
# 또는 GitHub Releases 페이지에서 사전 빌드된 릴리스 다운로드.

# CSV 파일 인덱스
leviathan index tickets.csv --id "Ticket ID" --group customer_id --date created_at

# 검색
leviathan search -g acme "sso login loop after password reset"

제한 사항 및 고려 사항

전문 검색 전용 – 의미론적 임베딩 없음. 관련성은 키워드 일치 및 BM25 기반.
스키마 기반 – 매핑(id, title 등)을 제공해야 합니다. 매핑되지 않은 필드는 무시됩니다.
단일 노드 – 인덱스는 하나의 SQLite 파일에 있습니다. 분산 저장소가 아닙니다.
모델 추론 없음 – Leviathan은 LLM을 실행하지 않습니다. 모델이 소비할 간결한 컨텍스트만 제공합니다.

라이선스 및 기여

Leviathan은 Apache-2.0 라이선스로 배포됩니다. 풀 리퀘스트를 통한 기여를 환영합니다. 벤치마크에 영향을 주는 변경 사항에는 전후 수치가 포함되어야 합니다. 보안 문제는 SECURITY.md에서 다룹니다(기본적으로 오프라인, 명시적으로 제공되지 않는 한 읽기 전용 인덱스).

결론: Leviathan은 벡터 데이터베이스나 외부 서비스의 오버헤드 없이 모든 표 형식 데이터 세트를 LLM 에이전트가 직접 호출할 수 있는 검색 가능한 메모리로 변환하는 빠르고 토큰 효율적인 방법을 제공합니다.