ESC
开源 2 分钟阅读

Leviathan 开源：为 Agent 提供大型数据集上的深度记忆与全文索引

开源项目 Leviathan 发布：单一静态二进制文件，可将 JSONL、CSV/TSV、SQLite 等记录构建为排序全文索引，供 AI Agent 用自然语言查询。官方基准显示，100 万条记录下单次提问中位仅消耗 436 token，为最优 grep 策略的 1/245，前 5 命中率 99%，中位延迟 33ms。Rust 编写，Apache-2.0 协议，支持 MCP 接入。

来源：GitHub

Leviathan

面向大型数据集的 Agent 深度记忆。
索引任意表格，一次性导出或记录日志；你的 Agent 将直接获得能回答问题的少数几条记录。

CI License: Apache-2.0 Rust 1.88+ MCP optional

Leviathan 是一个单一二进制文件，可将记录（JSONL、JSON、CSV/TSV、SQLite，或任何数据库 CLI 的输出）转换为排序的全文索引。Agent 用自然语言提问，即可获得简短、带引用的结果卡片：无论数据集多大，每个答案约 450 token，而无需 grep 并阅读原始历史记录。

Median tokens per question at 1M records: Leviathan 436, grep entity + question words 107K, grep entity history 209K, read all 203M

Median tokens per question vs dataset size Answer rate vs dataset size

Tokens per question vs entity history size Latency vs dataset size

100 万条记录时（678 MB）Leviathan最优 grep 策略
每个问题的中位 token 数436107,122（245×）
返回相关记录99.0% 前 5 · 98.5% 排名第 196.0%（30K 字符输出内）
最坏情况（1,200 个问题）602 token970 万 token
中位延迟33 ms92 ms

基准测试在一份合成维护日志上进行（仅一个示例数据集；Leviathan 中没有任何专门针对该数据集的逻辑）。方法论、全部六个规模及注意事项见：docs/BENCHMARKS.md。

快速开始

cargo install leviathan-index       # 或者：cargo install --git https://github.com/elstongun/leviathan
cd examples/tickets && leviathan index
leviathan search -g acme "sso login loop after password reset"

leviathan search · customer C-ACME "Acme Corp" (7 tickets) · query "sso login loop after password reset" · shown 3 of 3 · 24 tickets indexed
[1] T-1001 · 2024-01-08 09:12 · rel 16.9
  Login loops back to sign-in page after password reset
  status: closed · priority: high
  resolution: Cleared stale session cookies on password reset; shipped in 4.2.1. Workaround: clear site data.
  match: Users who reset their password get redirected to the sign-in page again in an endless loop.
...
  • -g 接受键、名称或部分名称。组名有歧义或未知时会列出候选并返回退出码 3，绝不猜测。
  • 组内无匹配时会回退到其他组，并标记为 OTHER CUSTOMER。
  • 可组合使用 --where field=value、--since/--until、"短语" 和 -排除词。

预编译二进制文件见 Releases。无运行时依赖；索引就是一个 SQLite 文件。

映射你的数据

字段即路径（a.b、items[].name）；只有 id 是必需的。

字段启用功能
idget、upsert、delete、引用
title / text卡片标题（权重 2×）/ 检索文本（默认：所有字符串）
group / group_name-g 范围搜索、名称解析、带标签的回退
date--since、--until、recent
filters / display--where 过滤面 / 卡片上显示的字段
empty_values / rank.boost视为缺失的占位符 / 偏爱完整记录
leviathan init ./export                       # 推断出一个带注释的 leviathan.toml
leviathan index tickets.csv --id "Ticket ID" --group customer_id --date created_at   # 或使用 flags
leviathan index -c tickets.toml               # 或使用你的 agent 根据模式生成的配置
leviathan describe                            # 字段、分组、过滤值、示例调用

任何数据库都可通过其自身的 CLI 接入；Leviathan 绝不持有凭证：

psql "$DATABASE_URL" -At -c "SELECT row_to_json(t) FROM tickets t" | leviathan index - -c tickets.toml
leviathan index app.db --sql "SELECT * FROM tickets" -c tickets.toml
duckdb -json -c "SELECT * FROM 'events/*.parquet'" | leviathan index - -c events.toml

构建是原子性的，数据无变化时会自动跳过；upsert 和 delete 可保持索引新鲜。完整参考：docs/CONFIG.md。

接入你的 Agent

CLI + 技能（推荐）： 任何拥有 shell 的 agent 都可以调用它。将 skills/leviathan 复制到 ~/.claude/skills/，或粘贴到 AGENTS.md / .cursor/rules 中。未被使用时不消耗任何 token。

MCP（可选）： leviathan mcp 提供四个只读 stdio 工具（search、resolve_group、get、describe），其描述中包含你数据集的摘要（每次会话约 640 token）。leviathan wrap <claude|cursor|codex|vscode|gemini|windsurf|generic> 会打印相应配置。

命令

命令功能
init / index / upsert / delete提出映射 / 构建 / 更新 / 删除记录
search [-g G] [words]排序记录（--scope、--where、--since、--until、-n、--offset）
recent [-g G] · resolve <g> · get <id…> · describe最新记录 · 组候选 · 完整记录 · 索引摘要
mcp · wrap <agent>MCP 服务器 · agent 配置

全局选项：--index PATH、--json、--max-chars N。退出码：0 正常（包括零命中）、1 错误、2 请求有误、3 组未知/有歧义。

工作原理

记录流入一个带 FTS5 索引的 SQLite 文件。搜索会解析组（精确 → 名称 → 包含 → 模糊），运行一次 FTS5 匹配，其中组和过滤值作为索引 token 处理（无需后置过滤），按 BM25 × 提升系数排序，并仅将前 N 条解码为截断的卡片。记录自身的组名会在范围匹配中被排除，占位符计为缺失，且每个答案都会报告 shown N of M，让 Agent 能区分"无匹配"和"无数据"。

复现基准测试

python3 -m venv bench/.venv && bench/.venv/bin/pip install -r bench/requirements.txt
bench/.venv/bin/python bench/run_bench.py && bench/.venv/bin/python bench/report.py   # 约 30 分钟，约 4 GB

Index build time and size

贡献、安全与许可

参见 CONTRIBUTING.md（排名相关改动需附改动前后的基准数据）和 SECURITY.md（只读、离线、无 unsafe；安全问题请私下报告）。基于 Apache-2.0 许可发布；依赖项见 THIRD_PARTY.md。