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`で、どのフィールドがレコードの`id`で、どのフィールドが`title`、`text`、`group`、`date`などを指定します。必須なのは`id`のみです。
全文検索+BM25ランキング	レコードはSQLite FTS5テーブルに保存され、クエリはフィールドごとのブースト付きBM25でランク付けされます。
グループスコープ検索	`-g <group>`で顧客、プロジェクト、または任意の論理バケットに結果を制限します。不明なグループは推測せずに報告されます。
トークン予算内の回答	ツールは固定サイズの「カード」（約450トークン）を返し、LLMのコンテキストウィンドウに余裕を持って収まります。
インクリメンタル更新	`upsert`と`delete`でインデックスを原子的に変更し、完全な再構築なしで最新の状態を保ちます。
エージェント統合	Claude、Cursor、VS Code/Copilot、Gemini CLIなど用の既製のスキルが付属。ラッパー（`leviathan wrap <agent>`）がそれらのエージェントに必要な設定を生成します。
オプションのメモリレイヤー	2番目のSQLiteファイルにキーと値の「メモリ」を保存でき、エージェントはトークン予算内で`remember`と`recall`できます。
MCP / HTTPサーバー	`leviathan mcp`はstdioベースのMulti-Client-Protocolで同じツールを公開。`leviathan serve --http`はベアラートークンまたは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ファイルにキーと値のペアを保存。各書き込みは同じキーの以前の値を置き換え、メモリの一貫性を保ちます。

ベンチマーク（リポジトリより）

100万レコード（約678 MB） → 中央値の回答サイズ436トークン。一方、単純なgrepでは>10万トークンが必要。
関連レコードの再現率 – 上位5件の結果の99%に正しいレコードが含まれ、ランク1の再現率は98.5%。
レイテンシ – クエリあたり中央値33ms（最良のgrep戦略の92msに対して）。
メモリのトークン予算 – 300セッション後、33KトークンのMarkdownメモリファイルは読み込み時に約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エージェントが直接呼び出せるようにする、高速でトークン効率の良い方法を提供します。