cxs — agent session search

Why not Embeddings? 为什么不用 Embedding？

Because this is built for Agents. Embeddings try to do semantic reasoning for humans, but an Agent is already a world-class reasoning engine. Chunking logs into a vector database destroys the causal timeline (Command → Error → Fix). cxs simply uses fast full-text search (FTS) to drop a bookmark, and lets the Agent use its own intelligence to read the surrounding timeline. 因为这是给 Agent 用的。Embedding 试图替人类做语义理解，但 Agent 本身就是最顶级的语义引擎。把对话切碎塞进向量库，会彻底破坏“执行命令 → 报错 → 修复”的因果时间线。cxs 只用极速的 FTS 全文检索提供锚点，把阅读和推理的权力完整交还给 Agent。

Why not ripgrep? 为什么不用 ripgrep？

rg dumps raw JSONL lines. Agents need conversational context, not unparsed strings. cxs understands the session structure: it finds the exact message, then provides primitives (read-range, read-page) for the Agent to page through the surrounding dialogue cleanly. rg 只能搜出杂乱无章的单行 JSONL 文本。而 Agent 需要的是“对话上下文”，不是干瘪的字符串。cxs 真正理解会话结构：它先精确定位 (find)，再让 Agent 像人一样干净地翻阅上下文对话 (read-range, read-page)。

Zero Documentation Tax 零文档整理负担

You don't need to stop and write clean notes. The raw history of how you and your agent solved a problem last time is directly searchable next time. 不再需要停下手中的活去整理一份干净的文档或 Runbook。你和 Agent 解决上一个问题的原始对话过程，就是最直接的记忆，随时可供下次查阅。

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

You don't have to use cxs end-to-end. It's a CLI that outputs standard JSON. Use it to locate the exact session, then pipe it to jq, read the raw file, or pass the context to other tools like Mainline. It's a retrieval engine, not a walled garden. 你不必被 cxs 绑定到底。它是一个标准的 CLI，支持 JSON 输出。你可以用它找到目标会话的精确位置，然后用 jq 处理数据，直接读取原始文件，或者把召回的上下文交接给其他工具（如 Mainline）。它是一个底层的检索引擎，而不是一个封闭的生态。

How it works in practice Agent 召回上下文示例

When an Agent joins a new task, it searches past conversations to understand why decisions were made or how past workflows were executed. 当 Agent 接手任务时，它会搜索历史对话，来搞清楚当时的“架构决策背景”或是“具体的工作流”。

Step 1: Recall Context

$ cxs find "auth session migration"

{
  "rank": 1,
  "title": "Refactoring auth flow",
  "matchSeq": 18,
  "snippet": "Let's migrate from JWT to server sessions..."
}

Step 2: Progressive Read

$ cxs read-range a1b2c3d4-0000-0000-0000-e5f6g7h8i9j0 --seq 18

# The Agent reads the surrounding dialogue to understand the context:
[seq: 17] Agent: The JWT tokens are getting too large due to role-based claims.
[seq: 18] User: Let's migrate from JWT to server sessions. We can use Redis.
[seq: 19] Agent: Good idea. I'll update auth.middleware.ts to check Redis instead of verifying JWT signatures.

Step 1: 召回相关历史对话 (Recall Context)

$ cxs find "权限 session 迁移"

{
  "rank": 1,
  "title": "重构登录逻辑",
  "matchSeq": 18,
  "snippet": "我们从 JWT 迁移到 服务端 session 吧..."
}

Step 2: 渐进式翻阅对话 (Progressive Read)

$ cxs read-range a1b2c3d4-0000-0000-0000-e5f6g7h8i9j0 --seq 18

# Agent 顺藤摸瓜，直接还原了当时的架构决策现场：
[seq: 17] Agent: 发现权限字段太多，导致 JWT token 超载。
[seq: 18] User: 我们从 JWT 迁移到服务端 session 吧。用 Redis 存。
[seq: 19] Agent: 好主意。我这就去改 auth.middleware.ts，把 JWT 校验换成 Redis 查询。