sherlog：把 Codex 和 Claude Code 的会话历史做成可全文检索的本地索引

「上周让 agent 改的那个 nginx 配置，对话里到底怎么说的来着」——用过几个月 Codex 或 Claude Code 之后，这类回忆会越来越频繁。会话记录躺在 ~/.codex/sessions 和 ~/.claude/projects 里一大堆 JSONL，手动翻基本不现实。sherlog 把这些转录索引进本地 SQLite，做成一个能用一条命令全文检索的 CLI，命令名叫 shlog。

项目简介

sherlog 用 Rust 写的单二进制，MIT 开源，内置 SQLite 和 FTS5 全文索引，不依赖 Node.js。目前 27 stars，2026 年 4 月建仓，当前版本 v0.5.3。支持四个数据源：Codex（默认，最完整）、Claude Code、Pi、dsh（DeepSeek Harness，zstd 压缩的转录也能透明读），后三家标注为 experimental。

它的定位和之前介绍过的 Wake 是同一个问题的两种解法：Wake 做成 GUI 三栏应用给人翻，sherlog 做成 CLI 原语，更多是给 agent 自己用的。

渐进式检索：三步走

sherlog 的搜索路径分三层，每层只做一件事：

1. status —— 看索引状态和覆盖率，告诉你该不该先同步
2. find —— 全文搜索，返回按相关度排序的会话候选
3. read-range / read-page —— 只读匹配点附近的一段窗口，或者按页翻

所有读命令都只打开 SQLite 索引，从不扫原始转录文件。整个工具只有 sync 一个命令写索引，增量同步时未变的文件直接复用，追加的从断点续。

设计取舍：为什么不用 ripgrep，也不用向量

这是 sherlog 最值得看的部分，仓库里专门有一篇 PHILOSOPHY 文档。

为什么不是 ripgrep：rg 能搜到原始 JSONL 行，但它不认识会话结构，吐出来的是未解析的原始记录。agent 需要的会话上下文、出处和过滤过的安全投影，它给不了。

为什么不做向量检索：agent 本身就是语义引擎。一个紧凑的全文候选层保留了因果时间线——命令、报错、决定、修复的先后顺序，然后让 agent 在一个显式的证据窗口上推理。向量库反而会引入第二份存储真相，语义匹配那层留给 agent 做，纯粹是重复。

这个思路对做 agent 工具的人有参考价值：检索层不必什么都做，把结构化、可验证、省 token 的候选交给模型，效果往往比堆基础设施好。

零文档税也值得提：不需要你把解决过的问题手动整理成笔记，sync 自动从过往会话里抽取一份白名单投影，工具结果、思考过程、附件默认不进索引。读原始转录是最后手段——只有投影明显不够（比如要完整的补丁或长代码块）才做窄范围回读，而且要求单独标注来源。

安装与上手

curl -fsSL https://github.com/catoncat/sherlog/releases/latest/download/install.sh | sh
# 或 Homebrew
brew tap catoncat/sherlog && brew install sherlog

安装器放到 ~/.local/bin，校验 SHA-256，全程不碰 sudo。预编译包覆盖 macOS arm64/x64 和 Linux x64。装完三步走：

shlog sync                      # 索引默认的 Codex 会话
shlog find "health check"       # 跨会话全文搜索
shlog read-range <sessionRef> --seq <matchSeq>   # 读匹配点附近

索引库存在 ~/.local/state/shlog/index.sqlite。从 0.4.x 升级的用户跑一次 shlog sync 完成向 v8 的迁移，旧索引会留备份。

命令速览

命令都支持 --json 结构化输出和 --cwd 项目范围过滤。覆盖率机制做得细：find 零结果时 status 会告诉你 recommendedAction 是直接查还是先 sync，避免对着过期索引盲搜。

让 agent 自己查

一条命令把 sherlog 装成 agent 技能：

npx skills add -g catoncat/sherlog

之后 Claude Code、Codex 这些 agent 就能自己调 shlog 翻你的历史会话。设计上有个贴心的细节：find 的 JSON 结果里自带一个闭包好的 evidenceRead.command，agent 原样执行就能拿到证据上下文，不用自己拼参数。作者把它定位成一个可组合的短命 CLI 原语，输出走 jq 管道、给别的工具供证据都行。

注意事项

• Claude Code、Pi、dsh 三个数据源还在 experimental，主力场景是 Codex 会话
• 只发布了 macOS 和 Linux x64 包，Windows 和 Linux arm64 没有
• 项目还小（27 stars），单人维护，核心路径（索引、搜索、读取）已经稳定，但别指望企业级支持
• 隐私上它是本地优先的：索引在本机，投影默认排除敏感记录

项目链接

• GitHub 仓库：https://github.com/catoncat/sherlog
• 官网：https://sherlog.net