elstongun/leviathan

Leviathan – 快速、节省 Token 的 AI 智能体记忆工具

Leviathan 是一个单一二进制 Rust 工具，可将任何表格或类 JSON 数据源（CSV/TSV、JSONL、SQLite 或数据库 CLI 的输出）转换为全文可搜索的 SQLite 索引。智能体随后可以提出自然语言问题，并收到一份简短、包含引用的“卡片”，其中包含最相关的记录——通常只需几百个 Token，而非数百万。

---

功能概述

功能	效果
通用数据导入	leviathan index 读取 JSONL、CSV、TSV、SQLite 文件，或任何输出 JSON 行的命令（例如 psql … -c "SELECT row_to_json(t) FROM …"）。
Schema 映射	一个极简的 leviathan.toml 告诉 Leviathan 哪个字段是记录 id，哪些字段是 title、text、group、date 等。仅 id 为必填。
全文 + BM25 排序	记录存储在 SQLite FTS5 表中；查询按 BM25 排序，并支持可选的字段级加权。
分组限定搜索	-g <group> 将结果限制为某个客户、项目或任何逻辑分组；未知分组会明确报告，而非猜测。
Token 预算答案	工具返回固定大小的“卡片”（约 450 Token），可轻松放入 LLM 上下文窗口。
增量更新	upsert 和 delete 原子地修改索引，无需完全重建即可保持最新。
智能体集成	附带现成的 skills，适用于 Claude、Cursor、VS Code/Copilot、Gemini CLI 等；一个包装器（leviathan wrap <agent>）可生成这些智能体所需的配置。
可选记忆层	第二个 SQLite 文件可存储键值“记忆”，智能体可在 Token 预算内 remember 和 recall。
MCP / HTTP 服务器	leviathan mcp 通过基于 stdio 的多客户端协议暴露相同工具；leviathan serve --http 提供 REST/OpenAPI 端点，支持 Bearer Token 或 OAuth2.1 认证。
零运行时依赖	索引是纯 SQLite 文件；二进制文件自包含。

---

典型工作流

1. 创建 Schema – leviathan init ./export 生成一个带注释的 leviathan.toml，可供编辑。
2. 构建索引 – leviathan index tickets.csv --id "Ticket ID" --group customer_id --date created_at（或从任何数据库管道传入 JSON）。
3. 查询 – leviathan search -g acme "sso login loop after password reset" 返回一份简洁、带引用的卡片。
4. 接入智能体 – 将 skills/leviathan 复制到智能体的技能目录，或运行 leviathan wrap claude --memory --apply 添加一个 LLM 可调用的工具。

---

工作原理（高层）

1. 数据导入 – 流式读取行，每个字段被分词，记录插入包含 FTS5 虚拟表的 SQLite 文件。
2. 查询处理 – 工具解析请求的组（精确匹配 → 名称 → 模糊匹配），构建包含组和过滤 Token 的单个 FTS5 查询并执行。
3. 排序 – 结果按 BM25 × 用户指定的加权（例如 title 权重 2 倍）评分。
4. 卡片生成 – 仅解码前 N 条记录，截断至 Token 预算，并格式化包含引用、日期及任何 display 字段。
5. 记忆（可选） – 一个单独的 SQLite 文件存储键值对；每次写入都会替换同一键的旧值，保持记忆一致性。

---

基准测试（来自仓库）

• 100 万条记录（约 678 MB） → 中位答案大小 436 Token，而朴素的 grep 需要超过 10 万 Token。
• 相关记录召回率 – 前 5 名结果中 99% 包含正确记录；排名第一的召回率为 98.5%。
• 延迟 – 每次查询中位数为 33 毫秒（而最佳 grep 策略为 92 毫秒）。
• 记忆 Token 预算 – 经过 300 次会话后，一个 33K Token 的 Markdown 记忆文件加载时缩减至约 736 Token。

---

典型工作流程

1. 创建 Schema – leviathan init ./export 生成一个带注释的 leviathan.toml，可供编辑。
2. 构建索引 – leviathan index tickets.csv --id "Ticket ID" --group customer_id --date created_at（或从任何数据库管道传入 JSON）。
3. 查询 – leviathan search -g acme "sso login loop after password reset" 返回一份简洁、带引用的卡片。
4. 接入智能体 – 将 skills/leviathan 复制到智能体的技能目录，或运行 leviathan wrap claude --memory --apply 添加一个 LLM 可调用的工具。

---

工作原理（高层）

1. 数据导入 – 流式读取行，每个字段被分词，记录插入包含 FTS5 虚拟表的 SQLite 文件。
2. 查询处理 – 工具解析请求的组（精确匹配 → 名称 → 模糊匹配），构建包含组和过滤 Token 的单个 FTS5 查询并执行。
3. 排序 – 结果按 BM25 × 用户指定的加权（例如 title 权重 2×）评分。
4. 卡片生成 – 仅解码前 N 条记录，截断至 Token 预算，并格式化包含引用、日期及任何 display 字段。
5. 记忆（可选） – 一个单独的 SQLite 文件存储键值对；每次写入都会替换同一键的旧值，保持记忆一致性。

---

基准测试（来自仓库）

• 100 万条记录（约 678 MB） → 中位答案大小 436 Token，而朴素的 grep 需要超过 10 万 Token。
• 相关记录召回率 – 前 5 名结果中 99% 包含正确记录；排名第一的召回率为 98.5%。
• 延迟 – 每次查询中位数为 33 毫秒（而最佳 grep 策略为 92 毫秒）。
• 记忆 Token 预算 – 经过 300 次会话后，一个 33K Token 的 Markdown 记忆文件在加载时缩减至约 736 Token。

---

适用人群

• 基于 LLM 的支持智能体，需要快速、节省 Token 地访问大型工单或日志数据库。
• 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。
• Schema 驱动 – 必须提供映射（id、title 等）；未映射的字段将被忽略。
• 单节点 – 索引存储在一个 SQLite 文件中；不是分布式存储。
• 无模型推理 – Leviathan 不运行任何 LLM；它仅为模型提供简洁的上下文供其消费。

---

许可证与贡献

Leviathan 以 Apache-2.0 许可证发布。欢迎通过拉取请求贡献代码；影响基准测试的更改必须包含前后数据。安全问题在 SECURITY.md 中说明（默认离线，除非显式提供服务，否则索引为只读）。

---

总结： Leviathan 提供了一种快速、节省 Token 的方式，将任何表格数据集转换为可搜索的记忆，LLM 智能体可直接调用，无需向量数据库或外部服务的开销。

SUMMARY: Leviathan 是一个基于 Rust 的 CLI 工具，可将 CSV/JSON/SQLite 数据索引到单个 SQLite FTS5 文件中，为 AI 智能体提供快速、受 Token 预算约束的自然语言搜索。它支持按组限定查询、增量 upsert、可选键值记忆，并可封装为 Claude、Gemini、VS Code/Copilot 等智能体的技能。基准测试显示，100 万条记录的回答约 436 Token，延迟 33 毫秒，远小于原始 grep 方法。

TITLE: Leviathan – 面向 LLM 智能体的节省 Token 的全文记忆工具