sherlog

Install 安装

npx skills add -g catoncat/sherlog

curl -fsSL
https://github.com/catoncat/sherlog/releases/latest/download/install.sh
| sh

brew tap catoncat/sherlog
brew install sherlog

Quick start 快速开始

# First install: index the default Codex root
shlog sync

# Recall candidates: compact text, one block per session with a ready read: line
shlog find "JWT server sessions"

# Read the surrounding context (paste the read: line, or add --json for the full contract)
shlog read-range <sessionRef> --seq <matchSeq> --query "JWT server sessions"

Why not Embeddings? 为什么不用 Embedding？

Because agents are already the semantic engine. Embeddings try to do semantic thinking for humans, but an Agent is a world-class reasoner. Chunking logs into a vector database destroys the causal timeline (Command → Error → Fix). Sherlog uses fast full-text search to drop a bookmark in the timeline, then lets the Agent read the surrounding conversation itself. 因为 Agent 本身就是最强的语义引擎。Embedding 试图替人类做语义理解，但 Agent 本来就是顶级推理器。把对话切碎塞进向量库，会破坏“执行命令 → 报错 → 修复”的因果时间线。Sherlog 用极速全文检索在时间线上放下锚点，把上下文阅读交还给 Agent。

Why not ripgrep? 为什么不用 ripgrep？

rg finds raw JSONL lines. Agents need conversational context, not unparsed strings. Sherlog understands session structure: it finds the exact message, then provides read-range and read-page for the Agent to page through the dialogue cleanly. rg 只能翻出杂乱的原生 JSONL 行；Agent 需要的是对话上下文。Sherlog 真正理解会话结构：先精确定位消息，再用 read-range / read-page 让 Agent 干净地翻阅上下文。

Zero Documentation Tax 零文档整理负担

Your raw agent history is already the best runbook. Don’t stop to write clean notes. The conversation where you and your agent solved a problem last time is directly searchable next time. 你和 Agent 的历史对话，就是最好的 Runbook。不用停下来整理文档。上次怎么解决问题的，下次直接搜得到。

A Composable Primitive 高度可组合的基础组件

Sherlog is a retrieval primitive, not a walled garden. It outputs standard JSON. Pipe it to jq, read the raw file, or hand the context to other tools like Mainline. Sherlog 是底层检索组件，不是封闭生态。它输出标准 JSON，可以接 jq、直接读原文，也可以把上下文交给 Mainline 等其它工具。

Commands 命令