cass

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CASS - Coding Agent Session Search

CASS - 编码Agent会话搜索

Unified, high-performance CLI/TUI to index and search your local coding agent history. Aggregates sessions from 11 agents: Codex, Claude Code, Gemini CLI, Cline, OpenCode, Amp, Cursor, ChatGPT, Aider, Pi-Agent, and Factory (Droid).

一款统一的高性能CLI/TUI工具，用于索引和搜索你的本地编码Agent会话历史。聚合来自11种Agent的会话：Codex、Claude Code、Gemini CLI、Cline、OpenCode、Amp、Cursor、ChatGPT、Aider、Pi-Agent以及Factory（Droid）。

CRITICAL: Robot Mode Required for AI Agents

重要提示：AI Agent必须使用机器人模式

NEVER run bare
cass
- it launches an interactive TUI that blocks your session!

bash

undefined

切勿直接运行
cass
- 它会启动交互式TUI，阻塞你的会话！

bash

undefined

WRONG - blocks terminal

错误用法 - 会阻塞终端

cass

CORRECT - JSON output for agents

正确用法 - 为Agent输出JSON格式结果

cass search "query" --robot cass search "query" --json # alias


**Always use `--robot` or `--json` flags for machine-readable output.**

---

cass search "query" --robot cass search "query" --json # 别名


**始终使用`--robot`或`--json`标志以获取机器可读的输出。**

---

Quick Reference for AI Agents

AI Agent快速参考指南

Pre-Flight Check

预检查

bash

undefined

bash

undefined

Health check (exit 0=healthy, 1=unhealthy, <50ms)

健康检查（返回0=健康，1=不健康，耗时<50ms）

cass health

If unhealthy, rebuild index

如果不健康，重建索引

cass index --full

undefined

cass index --full

undefined

Essential Commands

核心命令

bash

undefined

bash

undefined

Search with JSON output

搜索并输出JSON结果

cass search "authentication error" --robot --limit 5

Search with metadata (elapsed_ms, cache stats, freshness)

搜索并包含元数据（耗时、缓存统计、新鲜度）

cass search "error" --robot --robot-meta

Minimal payload (path, line, agent only)

极简返回结果（仅路径、行号、Agent信息）

cass search "bug" --robot --fields minimal

View source at specific line

查看指定行的源内容

cass view /path/to/session.jsonl -n 42 --json

Expand context around a line

扩展指定行的上下文内容

cass expand /path/to/session.jsonl -n 42 -C 5 --json

Capabilities discovery

功能发现

cass capabilities --json

Full API schema

完整API schema

cass introspect --json

LLM-optimized documentation

针对LLM优化的文档

cass robot-docs guide cass robot-docs commands cass robot-docs schemas cass robot-docs examples cass robot-docs exit-codes

---

cass robot-docs guide cass robot-docs commands cass robot-docs schemas cass robot-docs examples cass robot-docs exit-codes

---

Why Use CASS

为什么选择CASS

Cross-Agent Knowledge Transfer

跨Agent知识迁移

Your coding agents create scattered knowledge:

Claude Code sessions in
```
~/.claude/projects
```
Codex sessions in
```
~/.codex/sessions
```
Cursor state in SQLite databases
Aider history in markdown files

CASS unifies all of this into a single searchable index. When you're stuck on a problem, search across ALL your past agent sessions to find relevant solutions.

你的编码Agent会产生分散的知识：

Claude Code会话存储在
```
~/.claude/projects
```
Codex会话存储在
```
~/.codex/sessions
```
Cursor状态存储在SQLite数据库中
Aider历史存储在markdown文件中

CASS将所有这些内容统一到一个可搜索的索引中。当你遇到问题时，可以搜索所有过往Agent会话以找到相关解决方案。

Use Cases

使用场景

bash

undefined

bash

undefined

"I solved this before..."

“我以前解决过这个问题...”

cass search "TypeError: Cannot read property" --robot --days 30

Cross-agent learning (what has ANY agent said about X?)

跨Agent学习（所有Agent关于X的说法是什么？）

cass search "authentication" --robot --workspace /path/to/project

Agent-to-agent handoff

Agent间交接

cass search "database migration" --robot --fields summary

Daily review

每日回顾

cass timeline --today --json

---

cass timeline --today --json

---

Command Reference

命令参考

Indexing

索引

bash

undefined

bash

undefined

Full rebuild of DB and search index

完全重建数据库和搜索索引

cass index --full

Incremental update (since last scan)

增量更新（自上次扫描后）

cass index

Watch mode: auto-reindex on file changes

监听模式：文件变更时自动重新索引

cass index --watch

Force rebuild even if schema unchanged

即使schema未变更，强制重建

cass index --full --force-rebuild

Safe retries with idempotency key (24h TTL)

带幂等键的安全重试（24小时TTL）

cass index --full --idempotency-key "build-$(date +%Y%m%d)"

JSON output with stats

带统计信息的JSON输出

cass index --full --json

undefined

cass index --full --json

undefined

Search

搜索

bash

undefined

bash

undefined

Basic search (JSON output required for agents!)

基础搜索（Agent必须使用JSON输出！）

cass search "query" --robot

With filters

带过滤器的搜索

cass search "error" --robot --agent claude --days 7 cass search "bug" --robot --workspace /path/to/project cass search "panic" --robot --today

Time filters

时间过滤器

cass search "auth" --robot --since 2024-01-01 --until 2024-01-31 cass search "test" --robot --yesterday cass search "fix" --robot --week

Wildcards

通配符

cass search "auth*" --robot # prefix: authentication, authorize cass search "*tion" --robot # suffix: authentication, exception cass search "config" --robot # substring: misconfigured

cass search "auth*" --robot # 前缀匹配：authentication、authorize等 cass search "*tion" --robot # 后缀匹配：authentication、exception等 cass search "config" --robot # 子串匹配：misconfigured等

Token budget management (critical for LLMs!)

Token预算管理（对LLM至关重要！）

cass search "error" --robot --fields minimal # path, line, agent only cass search "error" --robot --fields summary # adds title, score cass search "error" --robot --max-content-length 500 # truncate fields cass search "error" --robot --max-tokens 2000 # soft budget (~4 chars/token) cass search "error" --robot --limit 5 # cap results

cass search "error" --robot --fields minimal # 仅返回路径、行号、Agent信息 cass search "error" --robot --fields summary # 额外返回标题、评分 cass search "error" --robot --max-content-length 500 # 截断长字段 cass search "error" --robot --max-tokens 2000 # 软预算（约4字符/Token） cass search "error" --robot --limit 5 # 限制结果数量

Pagination (cursor-based)

分页（基于游标）

cass search "TODO" --robot --robot-meta --limit 20

Use _meta.next_cursor from response:

使用响应中的_meta.next_cursor：

cass search "TODO" --robot --robot-meta --limit 20 --cursor "eyJ..."

Match highlighting

匹配高亮

cass search "authentication error" --robot --highlight

Query analysis/debugging

查询分析/调试

cass search "auth*" --robot --explain # parsed query, cost estimates cass search "auth error" --robot --dry-run # validate without executing

cass search "auth*" --robot --explain # 解析后的查询、成本估算 cass search "auth error" --robot --dry-run # 验证查询但不执行

Aggregations (server-side counts)

聚合（服务端统计）

cass search "error" --robot --aggregate agent,workspace,date

Request correlation

请求关联

cass search "bug" --robot --request-id "req-12345"

Source filtering (for multi-machine setups)

源过滤（适用于多机器环境）

cass search "auth" --robot --source laptop cass search "error" --robot --source remote

Traceability (for debugging agent pipelines)

可追溯性（用于调试Agent流水线）

cass search "error" --robot --trace-file /tmp/cass-trace.json

undefined

cass search "error" --robot --trace-file /tmp/cass-trace.json

undefined

Session Analysis

会话分析

bash

undefined

bash

undefined

Export conversation to markdown/HTML/JSON

将对话导出为markdown/HTML/JSON格式

cass export /path/to/session.jsonl --format markdown -o conversation.md cass export /path/to/session.jsonl --format html -o conversation.html cass export /path/to/session.jsonl --format json --include-tools

Expand context around a line (from search result)

扩展指定行的上下文内容（来自搜索结果）

cass expand /path/to/session.jsonl -n 42 -C 5 --json

Shows 5 messages before and after line 42

显示第42行前后各5条消息

View source at line

查看指定行的源内容

cass view /path/to/session.jsonl -n 42 --json

Activity timeline

活动时间线

cass timeline --today --json --group-by hour cass timeline --days 7 --json --agent claude cass timeline --since 7d --json

Find related sessions for a file

查找与文件相关的会话

cass context /path/to/source.ts --json

undefined

cass context /path/to/source.ts --json

undefined

Status & Diagnostics

状态与诊断

bash

undefined

bash

undefined

Quick health (<50ms)

快速健康检查（<50ms）

cass health cass health --json

Full status snapshot

完整状态快照

cass status --json cass state --json # alias

cass status --json cass state --json # 别名

Statistics

统计信息

cass stats --json cass stats --by-source # for multi-machine

cass stats --json cass stats --by-source # 适用于多机器环境

Full diagnostics

完整诊断

cass diag --verbose

---

cass diag --verbose

---

Aggregation & Analytics

聚合与分析

Aggregate search results server-side to get counts and distributions without transferring full result data:

bash

undefined

通过服务端聚合搜索结果，无需传输完整结果数据即可获取统计数量和分布：

bash

undefined

Count results by agent

按Agent统计结果数量

cass search "error" --robot --aggregate agent

→ { "aggregations": { "agent": { "buckets": [{"key": "claude_code", "count": 45}, ...] } } }

Multi-field aggregation

多字段聚合

cass search "bug" --robot --aggregate agent,workspace,date

Combine with filters

结合过滤器

cass search "TODO" --agent claude --robot --aggregate workspace


| Aggregation Field | Description |
|-------------------|-------------|
| `agent` | Group by agent type (claude_code, codex, cursor, etc.) |
| `workspace` | Group by workspace/project path |
| `date` | Group by date (YYYY-MM-DD) |
| `match_type` | Group by match quality (exact, prefix, fuzzy) |

Top 10 buckets returned per field, with `other_count` for remaining items.

---

cass search "TODO" --agent claude --robot --aggregate workspace


| 聚合字段 | 描述 |
|-------------------|-------------|
| `agent` | 按Agent类型分组（claude_code、codex、cursor等） |
| `workspace` | 按工作区/项目路径分组 |
| `date` | 按日期分组（YYYY-MM-DD） |
| `match_type` | 按匹配质量分组（精确、前缀、模糊） |

每个字段返回前10个分组，剩余项统计在`other_count`中。

---

Remote Sources (Multi-Machine Search)

远程源（多机器搜索）

Search across sessions from multiple machines via SSH/rsync.

通过SSH/rsync跨多台机器搜索会话。

Setup Wizard (Recommended)

设置向导（推荐）

bash

cass sources setup

The wizard:

Discovers SSH hosts from
```
~/.ssh/config
```
Probes each for agent data and cass installation
Optionally installs cass on remotes
Indexes sessions on remotes
Configures
```
sources.toml
```
Syncs data locally

bash

cass sources setup --hosts css,csd,yto  # Specific hosts only
cass sources setup --dry-run             # Preview without changes
cass sources setup --resume              # Resume interrupted setup

bash

cass sources setup

向导会：

从
```
~/.ssh/config
```
发现SSH主机
探测每台主机的Agent数据和CASS安装情况
可选在远程主机安装CASS
索引远程主机的会话
配置
```
sources.toml
```
将数据同步到本地

bash

cass sources setup --hosts css,csd,yto  # 仅指定特定主机
cass sources setup --dry-run             # 预览变更但不执行
cass sources setup --resume              # 恢复中断的设置

Manual Setup

手动设置

bash

undefined

bash

undefined

Add a remote machine

添加远程机器

cass sources add user@laptop.local --preset macos-defaults cass sources add dev@workstation --path ~/.claude/projects --path ~/.codex/sessions

List sources

列出源

cass sources list --json

Sync sessions

同步会话

cass sources sync cass sources sync --source laptop --verbose

Check connectivity

检查连接性

cass sources doctor cass sources doctor --source laptop --json

Path mappings (rewrite remote paths to local)

路径映射（将远程路径重写为本地路径）

cass sources mappings list laptop cass sources mappings add laptop --from /home/user/projects --to /Users/me/projects cass sources mappings test laptop /home/user/projects/myapp/src/main.rs

Remove source

移除源

cass sources remove laptop --purge -y


Configuration stored in `~/.config/cass/sources.toml` (Linux) or `~/Library/Application Support/cass/sources.toml` (macOS).

---

cass sources remove laptop --purge -y


配置存储在`~/.config/cass/sources.toml`（Linux）或`~/Library/Application Support/cass/sources.toml`（macOS）。

---

Robot Mode Deep Dive

机器人模式深度解析

Self-Documenting API

自文档化API

CASS teaches agents how to use itself:

bash

undefined

CASS会教Agent如何使用自身：

bash

undefined

Quick capability check

快速功能检查

cass capabilities --json

Returns: features, connectors, limits

返回：功能、连接器、限制

Full API schema

完整API schema

cass introspect --json

Returns: all commands, arguments, response shapes

返回：所有命令、参数、响应结构

Topic-based docs (LLM-optimized)

基于主题的文档（针对LLM优化）

cass robot-docs commands # all commands and flags cass robot-docs schemas # response JSON schemas cass robot-docs examples # copy-paste invocations cass robot-docs exit-codes # error handling cass robot-docs guide # quick-start walkthrough cass robot-docs contracts # API versioning cass robot-docs sources # remote sources guide

undefined

cass robot-docs commands # 所有命令和标志 cass robot-docs schemas # 响应JSON schema cass robot-docs examples # 可直接复制的调用示例 cass robot-docs exit-codes # 错误处理 cass robot-docs guide # 快速入门指南 cass robot-docs contracts # API版本控制 cass robot-docs sources # 远程源指南

undefined

Forgiving Syntax (Agent-Friendly)

容错语法（对Agent友好）

CASS auto-corrects common mistakes:

What you type	What CASS understands
`cass serach "error"`	`cass search "error"` (typo corrected)
`cass -robot -limit=5`	`cass --robot --limit=5` (single-dash fixed)
`cass --Robot --LIMIT 5`	`cass --robot --limit 5` (case normalized)
`cass find "auth"`	`cass search "auth"` (alias resolved)
`cass --limt 5`	`cass --limit 5` (Levenshtein <=2)

Command Aliases:

```
find
```
,
```
query
```
,
```
q
```
,
```
lookup
```
,
```
grep
```
→
```
search
```
```
ls
```
,
```
list
```
,
```
info
```
,
```
summary
```
→
```
stats
```
```
st
```
,
```
state
```
→
```
status
```
```
reindex
```
,
```
idx
```
,
```
rebuild
```
→
```
index
```
```
show
```
,
```
get
```
,
```
read
```
→
```
view
```
```
docs
```
,
```
help-robot
```
,
```
robotdocs
```
→
```
robot-docs
```

CASS会自动纠正常见错误：

输入内容	CASS实际解析内容
`cass serach "error"`	`cass search "error"` （纠正拼写错误）
`cass -robot -limit=5`	`cass --robot --limit=5` （修复单短横线）
`cass --Robot --LIMIT 5`	`cass --robot --limit 5` （统一大小写）
`cass find "auth"`	`cass search "auth"` （解析别名）
`cass --limt 5`	`cass --limit 5` （编辑距离≤2时纠正）

命令别名：

```
find
```
,
```
query
```
,
```
q
```
,
```
lookup
```
,
```
grep
```
→
```
search
```
```
ls
```
,
```
list
```
,
```
info
```
,
```
summary
```
→
```
stats
```
```
st
```
,
```
state
```
→
```
status
```
```
reindex
```
,
```
idx
```
,
```
rebuild
```
→
```
index
```
```
show
```
,
```
get
```
,
```
read
```
→
```
view
```
```
docs
```
,
```
help-robot
```
,
```
robotdocs
```
→
```
robot-docs
```

Output Formats

输出格式

bash

undefined

bash

undefined

Pretty-printed JSON (default)

格式化JSON（默认）

cass search "error" --robot

Streaming JSONL (header + one hit per line)

流式JSONL（头部 + 每行一个结果）

cass search "error" --robot-format jsonl

Compact single-line JSON

紧凑单行JSON

cass search "error" --robot-format compact

With performance metadata

带性能元数据

cass search "error" --robot --robot-meta


**Design principle:** stdout = JSON only; diagnostics go to stderr.

cass search "error" --robot --robot-meta


**设计原则：stdout仅输出JSON；诊断信息输出到stderr。**

Token Budget Management

Token预算管理

LLMs have context limits. Control output size:

Flag	Effect
`--fields minimal`	Only `source_path` , `line_number` , `agent`
`--fields summary`	Adds `title` , `score`
`--fields score,title,snippet`	Custom field selection
`--max-content-length 500`	Truncate long fields (UTF-8 safe)
`--max-tokens 2000`	Soft budget (~4 chars/token)
`--limit 5`	Cap number of results

Truncated fields include

*_truncated: true

indicator.

LLM有上下文限制，可控制输出大小：

标志	效果
`--fields minimal`	仅返回 `source_path` , `line_number` , `agent`
`--fields summary`	额外返回 `title` , `score`
`--fields score,title,snippet`	自定义字段选择
`--max-content-length 500`	截断长字段（UTF-8安全）
`--max-tokens 2000`	软预算（约4字符/Token）
`--limit 5`	限制结果数量

被截断的字段会包含

*_truncated: true

标识。

Structured Error Handling

结构化错误处理

Errors are JSON with actionable hints:

json

{
  "error": {
    "code": 3,
    "kind": "index_missing",
    "message": "Search index not found",
    "hint": "Run 'cass index --full' to build the index",
    "retryable": false
  }
}

错误以JSON格式返回，并包含可操作提示：

json

{
  "error": {
    "code": 3,
    "kind": "index_missing",
    "message": "搜索索引未找到",
    "hint": "运行'cass index --full'以构建索引",
    "retryable": false
  }
}

Exit Codes

退出码

Code	Meaning	Action
0	Success	Parse stdout
1	Health check failed	Run `cass index --full`
2	Usage error	Fix syntax (hint provided)
3	Index/DB missing	Run `cass index --full`
4	Network error	Check connectivity
5	Data corruption	Run `cass index --full --force-rebuild`
6	Incompatible version	Update cass
7	Lock/busy	Retry later
8	Partial result	Increase `--timeout`
9	Unknown error	Check `retryable` flag

代码	含义	操作
0	成功	解析stdout
1	健康检查失败	运行 `cass index --full`
2	使用错误	修正语法（参考提示）
3	索引/数据库缺失	运行 `cass index --full`
4	网络错误	检查连接性
5	数据损坏	运行 `cass index --full --force-rebuild`
6	版本不兼容	更新CASS
7	锁定/繁忙	稍后重试
8	部分结果	增加 `--timeout`
9	未知错误	检查 `retryable` 标志

Search Modes

搜索模式

Three search modes, selectable with

--mode

flag:

Mode	Algorithm	Best For
lexical (default)	BM25 full-text	Exact term matching, code searches
semantic	Vector similarity	Conceptual queries, "find similar"
hybrid	Reciprocal Rank Fusion	Balanced precision and recall

bash

cass search "authentication" --mode lexical --robot
cass search "how to handle user login" --mode semantic --robot
cass search "auth error handling" --mode hybrid --robot

Hybrid combines lexical and semantic using RRF:

RRF_score = Σ 1 / (60 + rank_i)

可通过

--mode

标志选择三种搜索模式：

模式	算法	最佳适用场景
lexical（默认）	BM25全文检索	精确术语匹配、代码搜索
semantic	向量相似度	概念性查询、"查找相似内容"
hybrid	reciprocal Rank Fusion	平衡精确性和召回率

bash

cass search "authentication" --mode lexical --robot
cass search "如何处理用户登录" --mode semantic --robot
cass search "auth错误处理" --mode hybrid --robot

Hybrid模式使用RRF结合lexical和semantic搜索：

RRF_score = Σ 1 / (60 + rank_i)

Pipeline Mode (Chained Search)

流水线模式（链式搜索）

Chain searches by piping session paths:

bash

undefined

通过管道传递会话路径来链式搜索：

bash

undefined

Find sessions mentioning "auth", then search within those for "token"

查找提及"auth"的会话，然后在这些会话中搜索"token"

cass search "authentication" --robot-format sessions |
cass search "refresh token" --sessions-from - --robot

Build a filtered corpus from today's work

从今日工作内容构建过滤后的语料库

cass search --today --robot-format sessions > today_sessions.txt cass search "bug fix" --sessions-from today_sessions.txt --robot


Use cases:
- **Drill-down**: Broad search → narrow within results
- **Cross-reference**: Find sessions with term A, then find term B within them
- **Corpus building**: Save session lists for repeated searches

---

cass search --today --robot-format sessions > today_sessions.txt cass search "bug fix" --sessions-from today_sessions.txt --robot


使用场景：
- **深度钻取**：宽泛搜索 → 在结果中缩小范围
- **交叉引用**：查找包含术语A的会话，然后在其中查找术语B
- **语料库构建**：保存会话列表以便重复搜索

---

Query Language

查询语言

Basic Queries

基础查询

Query	Matches
`error`	Messages containing "error" (case-insensitive)
`python error`	Both "python" AND "error"
`"authentication failed"`	Exact phrase

查询语句	匹配内容
`error`	包含"error"的消息（不区分大小写）
`python error`	同时包含"python"和"error"
`"authentication failed"`	精确短语

Boolean Operators

布尔运算符

Operator	Example	Meaning
`AND`	`python AND error`	Both terms required (default)
`OR`	`error OR warning`	Either term matches
`NOT`	`error NOT test`	First term, excluding second
`-`	`error -test`	Shorthand for NOT

bash

undefined

运算符	示例	含义
`AND`	`python AND error`	必须同时包含两个术语（默认）
`OR`	`error OR warning`	包含任意一个术语即可
`NOT`	`error NOT test`	包含第一个术语，但排除第二个
`-`	`error -test`	NOT的简写

bash

undefined

Complex boolean query

复杂布尔查询

cass search "authentication AND (error OR failure) NOT test" --robot

Exclude test files

排除测试文件

cass search "bug fix -test -spec" --robot

Either error type

任意一种错误类型

cass search "TypeError OR ValueError" --robot

undefined

cass search "TypeError OR ValueError" --robot

undefined

Wildcard Patterns

通配符模式

Pattern	Type	Performance
`auth*`	Prefix	Fast (edge n-grams)
`*tion`	Suffix	Slower (regex)
`config`	Substring	Slowest (regex)

模式	类型	性能
`auth*`	前缀	快速（边缘n-gram）
`*tion`	后缀	较慢（正则表达式）
`config`	子串	最慢（正则表达式）

Match Types

匹配类型

Results include

match_type

Type	Meaning	Score Boost
`exact`	Verbatim match	Highest
`prefix`	Via prefix expansion	High
`suffix`	Via suffix pattern	Medium
`substring`	Via substring pattern	Lower
`fuzzy`	Auto-fallback (sparse results)	Lowest

结果中会包含

match_type

字段：

类型	含义	评分提升
`exact`	完全匹配	最高
`prefix`	前缀扩展	高
`suffix`	后缀模式	中等
`substring`	子串模式	较低
`fuzzy`	自动回退（结果稀疏时）	最低

Auto-Fuzzy Fallback

自动模糊回退

When exact query returns <3 results, CASS automatically retries with wildcards:

```
auth
```
→
```
*auth*
```
Results flagged with
```
wildcard_fallback: true
```

当精确查询返回结果<3条时，CASS会自动使用通配符重试：

```
auth
```
→
```
*auth*
```
结果会标记
```
wildcard_fallback: true
```

Flexible Time Input

灵活的时间输入

CASS accepts a wide variety of time/date formats:

Format	Examples
Relative	`-7d` , `-24h` , `-30m` , `-1w`
Keywords	`now` , `today` , `yesterday`
ISO 8601	`2024-11-25` , `2024-11-25T14:30:00Z`
US Dates	`11/25/2024` , `11-25-2024`
Unix Timestamp	`1732579200` (seconds or milliseconds)

CASS支持多种时间/日期格式：

格式	示例
相对时间	`-7d` , `-24h` , `-30m` , `-1w`
关键词	`now` , `today` , `yesterday`
ISO 8601	`2024-11-25` , `2024-11-25T14:30:00Z`
美式日期	`11/25/2024` , `11-25-2024`
Unix时间戳	`1732579200` （秒或毫秒）

Ranking Modes

排序模式

Cycle with

F12

in TUI or use

--ranking

flag:

Mode	Formula	Best For
Recent Heavy	`relevance0.3 + recency0.7`	"What was I working on?"
Balanced	`relevance0.5 + recency0.5`	General search
Relevance	`relevance0.8 + recency0.2`	"Best explanation of X"
Match Quality	Penalizes fuzzy matches	Precise technical searches
Date Newest	Pure chronological	Recent activity
Date Oldest	Reverse chronological	"When did I first..."

在TUI中按

F12

切换，或使用

--ranking

标志：

模式	公式	最佳适用场景
近期优先	`relevance0.3 + recency0.7`	"我之前在做什么？"
平衡模式	`relevance0.5 + recency0.5`	通用搜索
相关性优先	`relevance0.8 + recency0.2`	"X的最佳解释"
匹配质量优先	惩罚模糊匹配	精确技术搜索
最新日期	纯时间顺序	近期活动
最早日期	逆时间顺序	"我第一次做...是什么时候？"

Score Components

评分组成

Text Relevance (BM25): Term frequency, inverse document frequency, length normalization
Recency: Exponential decay (today ~1.0, last week ~0.7, last month ~0.3)
Match Exactness: Exact phrase=1.0, Prefix=0.9, Suffix=0.8, Substring=0.6, Fuzzy=0.4

文本相关性（BM25）：词频、逆文档频率、长度归一化
时效性：指数衰减（今日~~1.0，上周~~0.7，上月~0.3）
匹配精确性：精确短语=1.0，前缀=0.9，后缀=0.8，子串=0.6，模糊=0.4

Blended Scoring Formula

混合评分公式

Final_Score = BM25_Score × Match_Quality + α × Recency_Factor

Mode	α Value	Effect
Recent Heavy	1.0	Recency dominates
Balanced	0.4	Moderate recency boost
Relevance Heavy	0.1	BM25 dominates
Match Quality	0.0	Pure text matching

Final_Score = BM25_Score × Match_Quality + α × Recency_Factor

模式	α值	效果
近期优先	1.0	时效性主导
平衡模式	0.4	适度时效性提升
相关性优先	0.1	BM25主导
匹配质量优先	0.0	纯文本匹配

Supported Agents (11 Connectors)

支持的Agent（11种连接器）

Agent	Location	Format
Claude Code	`~/.claude/projects`	JSONL
Codex	`~/.codex/sessions`	JSONL (Rollout)
Gemini CLI	`~/.gemini/tmp`	JSON
Cline	VS Code global storage	Task directories
OpenCode	`.opencode` directories	SQLite
Amp	`~/.local/share/amp` + VS Code	Mixed
Cursor	`~/Library/Application Support/Cursor`	SQLite (state.vscdb)
ChatGPT	`~/Library/Application Support/com.openai.chat`	JSON (v1 unencrypted)
Aider	`~/.aider.chat.history.md` + per-project	Markdown
Pi-Agent	`~/.pi/agent/sessions`	JSONL with thinking
Factory (Droid)	`~/.factory/sessions`	JSONL by workspace

Note: ChatGPT v2/v3 are AES-256-GCM encrypted (keychain access required). Legacy v1 unencrypted conversations are indexed automatically.

Agent	存储位置	格式
Claude Code	`~/.claude/projects`	JSONL
Codex	`~/.codex/sessions`	JSONL（逐步推出）
Gemini CLI	`~/.gemini/tmp`	JSON
Cline	VS Code全局存储	任务目录
OpenCode	`.opencode` 目录	SQLite
Amp	`~/.local/share/amp` + VS Code	混合格式
Cursor	`~/Library/Application Support/Cursor`	SQLite（state.vscdb）
ChatGPT	`~/Library/Application Support/com.openai.chat`	JSON（v1未加密）
Aider	`~/.aider.chat.history.md` + 每个项目目录	Markdown
Pi-Agent	`~/.pi/agent/sessions`	包含思考过程的JSONL
Factory (Droid)	`~/.factory/sessions`	按工作区划分的JSONL

注意： ChatGPT v2/v3采用AES-256-GCM加密（需要钥匙串访问权限）。旧版v1未加密的对话会自动被索引。

TUI Features (for Humans)

TUI功能（面向人类用户）

Launch with

cass

(no flags):

直接运行

cass

（无标志）启动：

Keyboard Shortcuts

键盘快捷键

Navigation:

```
Up/Down
```
: Move selection
```
Left/Right
```
: Switch panes
```
Tab/Shift+Tab
```
: Cycle focus
```
Enter
```
: Open in
```
$EDITOR
```
```
Space
```
: Full-screen detail view
```
Home/End
```
: Jump to first/last result
```
PageUp/PageDown
```
: Scroll by page

Filtering:

```
F3
```
: Agent filter
```
F4
```
: Workspace filter
```
F5/F6
```
: Time filters (from/to)
```
Shift+F3
```
: Scope to current result's agent
```
Shift+F4
```
: Clear workspace filter
```
Shift+F5
```
: Cycle presets (24h/7d/30d/all)
```
Ctrl+Del
```
: Clear all filters

Modes:

```
F2
```
: Toggle theme (6 presets)
```
F7
```
: Context window size (S/M/L/XL)
```
F9
```
: Match mode (prefix/standard)
```
F12
```
: Ranking mode
```
Ctrl+B
```
: Toggle border style

Selection & Actions:

```
m
```
: Toggle selection
```
Ctrl+A
```
: Select all
```
A
```
: Bulk actions menu
```
Ctrl+Enter
```
: Add to queue
```
Ctrl+O
```
: Open all queued
```
y
```
: Copy path/content
```
Ctrl+Y
```
: Copy all selected
```
/
```
: Find in detail pane
```
n/N
```
: Next/prev match

Views & Palette:

```
Ctrl+P
```
: Command palette
```
1-9
```
: Load saved view
```
Shift+1-9
```
: Save view to slot

Source Filtering (multi-machine):

```
F11
```
: Cycle source filter (all/local/remote)
```
Shift+F11
```
: Source selection menu

Global:

```
Ctrl+C
```
: Quit
```
F1
```
or
```
?
```
: Toggle help
```
Ctrl+Shift+R
```
: Force re-index
```
Ctrl+Shift+Del
```
: Reset all TUI state

导航：

```
Up/Down
```
：移动选择
```
Left/Right
```
：切换面板
```
Tab/Shift+Tab
```
：循环聚焦
```
Enter
```
：在
```
$EDITOR
```
中打开
```
Space
```
：全屏详情视图
```
Home/End
```
：跳转到第一个/最后一个结果
```
PageUp/PageDown
```
：按页滚动

过滤：

```
F3
```
：Agent过滤器
```
F4
```
：工作区过滤器
```
F5/F6
```
：时间过滤器（起始/结束）
```
Shift+F3
```
：限定到当前结果的Agent
```
Shift+F4
```
：清除工作区过滤器
```
Shift+F5
```
：循环预设（24h/7d/30d/全部）
```
Ctrl+Del
```
：清除所有过滤器

模式：

```
F2
```
：切换主题（6种预设）
```
F7
```
：上下文窗口大小（S/M/L/XL）
```
F9
```
：匹配模式（前缀/标准）
```
F12
```
：排序模式
```
Ctrl+B
```
：切换边框样式

选择与操作：

```
m
```
：切换选择
```
Ctrl+A
```
：全选
```
A
```
：批量操作菜单
```
Ctrl+Enter
```
：添加到队列
```
Ctrl+O
```
：打开所有队列项
```
y
```
：复制路径/内容
```
Ctrl+Y
```
：复制所有选中项
```
/
```
：在详情面板中查找
```
n/N
```
：下一个/上一个匹配项

视图与面板：

```
Ctrl+P
```
：命令面板
```
1-9
```
：加载已保存视图
```
Shift+1-9
```
：将当前视图保存到插槽

源过滤（多机器）：

```
F11
```
：循环源过滤器（全部/本地/远程）
```
Shift+11
```
：源选择菜单

全局：

```
Ctrl+C
```
：退出
```
F1
```
或
```
?
```
：切换帮助
```
Ctrl+Shift+R
```
：强制重新索引
```
Ctrl+Shift+Del
```
：重置所有TUI状态

Detail Pane Tabs

详情面板标签

Tab	Content	Switch With
Messages	Full conversation with markdown	`[` / `]`
Snippets	Keyword-extracted summaries	`[` / `]`
Raw	Unformatted JSON/text	`[` / `]`

标签	内容	切换快捷键
Messages	带markdown格式的完整对话	`[` / `]`
Snippets	关键词提取的摘要	`[` / `]`
Raw	未格式化的JSON/文本	`[` / `]`

Context Window Sizing

上下文窗口大小

Size	Characters	Use Case
Small	~200	Quick scanning
Medium	~400	Default balanced view
Large	~800	Longer passages
XLarge	~1600	Full context, code review

Peek Mode (

Ctrl+Space

): Temporarily expand to XL without changing default.

大小	字符数	使用场景
Small	~200	快速扫描
Medium	~400	默认平衡视图
Large	~800	较长段落
XLarge	~1600	完整上下文、代码评审

预览模式（

Ctrl+Space

）：临时扩展到XL大小，不修改默认设置。

Theme Presets

主题预设

Cycle through 6 built-in themes with

F2

Theme	Description	Best For
Dark	Tokyo Night-inspired deep blues	Low-light environments
Light	High-contrast light background	Bright environments
Catppuccin	Warm pastels, reduced eye strain	All-day coding
Dracula	Purple-accented dark theme	Popular developer theme
Nord	Arctic-inspired cool tones	Calm, focused work
High Contrast	Maximum readability	Accessibility needs

All themes validated against WCAG contrast requirements (4.5:1 minimum for text).

按

F2

循环切换6种内置主题：

主题	描述	最佳适用场景
Dark	灵感来自Tokyo Night的深蓝主题	低光环境
Light	高对比度浅色背景	明亮环境
Catppuccin	温暖的柔和色调，减少眼部疲劳	全天编码
Dracula	带紫色点缀的深色主题	流行的开发者主题
Nord	北极风格的冷色调	平静、专注的工作
High Contrast	最大可读性	无障碍需求

所有主题均通过WCAG对比度要求验证（文本最小4.5:1）。

Role-Aware Message Styling

角色感知消息样式

Role	Visual Treatment
User	Blue-tinted background, bold
Assistant	Green-tinted background
System	Gray/muted background
Tool	Orange-tinted background

角色	视觉处理
User	蓝色背景、加粗
Assistant	绿色背景
System	灰色/ muted背景
Tool	橙色背景

Saved Views

已保存视图

Save filter configurations to 9 slots for instant recall.

What Gets Saved:

Active filters (agent, workspace, time range)
Current ranking mode
The search query

Keyboard:

```
Shift+1
```
through
```
Shift+9
```
: Save current view
```
1
```
through
```
9
```
: Load view from slot

Via Command Palette:

Ctrl+P

→ "Save/Load view"

Views persist in

tui_state.json

across sessions.

将过滤器配置保存到9个插槽以便快速调用。

保存的内容：

活动过滤器（Agent、工作区、时间范围）
当前排序模式
搜索查询

键盘操作：

```
Shift+1
```
至
```
Shift+9
```
：保存当前视图
```
1
```
至
```
9
```
：从插槽加载视图

通过命令面板：

Ctrl+P

→ "Save/Load view"

视图会持久化存储在

tui_state.json

中，跨会话保留。

Density Modes

密度模式

Control lines per search result. Cycle with

Shift+D

Mode	Lines	Best For
Compact	3	Maximum results visible
Cozy	5	Balanced view (default)
Spacious	8	Detailed preview

控制每个搜索结果的行数，按

Shift+D

循环切换：

模式	行数	最佳适用场景
Compact	3	显示最多结果
Cozy	5	平衡视图（默认）
Spacious	8	详细预览

Bookmark System

书签系统

Save important results with notes and tags:

In TUI: Press

to bookmark, add notes and tags.

Bookmark Structure:

```
title
```
: Short description
```
source_path
```
,
```
line_number
```
,
```
agent
```
,
```
workspace
```
```
note
```
: Your annotations
```
tags
```
: Comma-separated labels
```
snippet
```
: Extracted content

Storage:

~/.local/share/coding-agent-search/bookmarks.db

(SQLite)

保存重要结果并添加备注和标签：

在TUI中：按

添加书签，添加备注和标签。

书签结构：

```
title
```
：简短描述
```
source_path
```
,
```
line_number
```
,
```
agent
```
,
```
workspace
```
```
note
```
：你的注释
```
tags
```
：逗号分隔的标签
```
snippet
```
：提取的内容

存储位置：

~/.local/share/coding-agent-search/bookmarks.db

（SQLite）

Optional Semantic Search

可选语义搜索

Local-only semantic search using MiniLM (no cloud):

Required files (place in data directory):

```
model.onnx
```
```
tokenizer.json
```
```
config.json
```
```
special_tokens_map.json
```
```
tokenizer_config.json
```

Vector index stored as

vector_index/index-minilm-384.cvvi

CASS does NOT auto-download models; you must manually install them.

Hash Embedder Fallback: When MiniLM not installed, CASS uses a hash-based embedder for approximate semantic similarity.

使用MiniLM的本地语义搜索（无需云端）：

所需文件（放置在数据目录）：

```
model.onnx
```
```
tokenizer.json
```
```
config.json
```
```
special_tokens_map.json
```
```
tokenizer_config.json
```

向量索引存储为

vector_index/index-minilm-384.cvvi

。

CASS不会自动下载模型；你必须手动安装。

哈希嵌入器回退： 当未安装MiniLM时，CASS使用基于哈希的嵌入器实现近似语义相似度匹配。

Watch Mode

监听模式

Real-time index updates:

bash

cass index --watch

Debounce: 2 seconds (wait for burst to settle)
Max wait: 5 seconds (force flush during continuous activity)
Incremental: Only re-scans modified files

TUI automatically starts watch mode in background.

实时更新索引：

bash

cass index --watch

防抖： 2秒（等待突发操作结束）
最大等待时间： 5秒（持续活动时强制刷新）
增量： 仅重新扫描修改的文件

TUI会在后台自动启动监听模式。

Deduplication Strategy

去重策略

CASS uses multi-layer deduplication:

Message Hash: SHA-256 of
```
(role + content + timestamp)
```
- identical messages stored once
Conversation Fingerprint: Hash of first N message hashes - detects duplicate files
Search-Time Dedup: Results deduplicated by content similarity

Noise Filtering:

Empty messages and pure whitespace
System prompts (unless searching for them)
Repeated tool acknowledgments

CASS使用多层去重：

消息哈希：
```
(role + content + timestamp)
```
的SHA-256哈希 - 相同消息仅存储一次
对话指纹：前N个消息哈希的哈希 - 检测重复文件
搜索时去重：基于内容相似度对结果去重

噪声过滤：

空消息和纯空白内容
系统提示（除非专门搜索）
重复的工具确认消息

Performance Characteristics

性能特征

Operation	Latency
Prefix search (cached)	2-8ms
Prefix search (cold)	40-60ms
Substring search	80-200ms
Full reindex	5-30s
Incremental reindex	50-500ms
Health check	<50ms

Memory: 70-140MB typical (50K messages) Disk: ~600 bytes/message (including n-gram overhead)

操作	延迟
前缀搜索（缓存）	2-8ms
前缀搜索（冷启动）	40-60ms
子串搜索	80-200ms
完全重新索引	5-30s
增量重新索引	50-500ms
健康检查	<50ms

内存： 典型70-140MB（50K条消息） 磁盘： 每条消息约600字节（包含n-gram开销）

Response Shapes

响应结构

Search Response:

json

{
  "query": "error",
  "limit": 10,
  "count": 5,
  "total_matches": 42,
  "hits": [
    {
      "source_path": "/path/to/session.jsonl",
      "line_number": 123,
      "agent": "claude_code",
      "workspace": "/projects/myapp",
      "title": "Authentication debugging",
      "snippet": "The error occurs when...",
      "score": 0.85,
      "match_type": "exact",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "_meta": {
    "elapsed_ms": 12,
    "cache_hit": true,
    "wildcard_fallback": false,
    "next_cursor": "eyJ...",
    "index_freshness": { "stale": false, "age_seconds": 120 }
  }
}

Aggregation Response:

json

{
  "aggregations": {
    "agent": {
      "buckets": [
        {"key": "claude_code", "count": 120},
        {"key": "codex", "count": 85}
      ],
      "other_count": 15
    }
  }
}

搜索响应：

json

{
  "query": "error",
  "limit": 10,
  "count": 5,
  "total_matches": 42,
  "hits": [
    {
      "source_path": "/path/to/session.jsonl",
      "line_number": 123,
      "agent": "claude_code",
      "workspace": "/projects/myapp",
      "title": "Authentication debugging",
      "snippet": "The error occurs when...",
      "score": 0.85,
      "match_type": "exact",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "_meta": {
    "elapsed_ms": 12,
    "cache_hit": true,
    "wildcard_fallback": false,
    "next_cursor": "eyJ...",
    "index_freshness": { "stale": false, "age_seconds": 120 }
  }
}

聚合响应：

json

{
  "aggregations": {
    "agent": {
      "buckets": [
        {"key": "claude_code", "count": 120},
        {"key": "codex", "count": 85}
      ],
      "other_count": 15
    }
  }
}

Environment Variables

环境变量

Variable	Purpose
`CASS_DATA_DIR`	Override data directory
`CHATGPT_ENCRYPTION_KEY`	Base64 key for encrypted ChatGPT
`PI_CODING_AGENT_DIR`	Override Pi-Agent sessions path
`CASS_CACHE_SHARD_CAP`	Per-shard cache entries (default 256)
`CASS_CACHE_TOTAL_CAP`	Total cached hits (default 2048)
`CASS_DEBUG_CACHE_METRICS`	Enable cache debug logging
`CODING_AGENT_SEARCH_NO_UPDATE_PROMPT`	Skip update checks

变量	用途
`CASS_DATA_DIR`	覆盖数据目录
`CHATGPT_ENCRYPTION_KEY`	加密ChatGPT的Base64密钥
`PI_CODING_AGENT_DIR`	覆盖Pi-Agent会话路径
`CASS_CACHE_SHARD_CAP`	每个分片的缓存条目数（默认256）
`CASS_CACHE_TOTAL_CAP`	总缓存结果数（默认2048）
`CASS_DEBUG_CACHE_METRICS`	启用缓存调试日志
`CODING_AGENT_SEARCH_NO_UPDATE_PROMPT`	跳过更新检查

Shell Completions

Shell补全

bash

cass completions bash > ~/.local/share/bash-completion/completions/cass
cass completions zsh > "${fpath[1]}/_cass"
cass completions fish > ~/.config/fish/completions/cass.fish
cass completions powershell >> $PROFILE

bash

cass completions bash > ~/.local/share/bash-completion/completions/cass
cass completions zsh > "${fpath[1]}/_cass"
cass completions fish > ~/.config/fish/completions/cass.fish
cass completions powershell >> $PROFILE

API Contract & Versioning

API契约与版本控制

bash

cass api-version --json

bash

cass api-version --json

→ { "version": "0.4.0", "contract_version": "1", "breaking_changes": [] }

cass introspect --json

→ Full schema: all commands, arguments, response types

→ 完整schema：所有命令、参数、响应类型


**Guaranteed Stable:**
- Exit codes and their meanings
- JSON response structure for `--robot` output
- Flag names and behaviors
- `_meta` block format

---


**保证稳定的内容：**
- 退出码及其含义
- `--robot`输出的JSON响应结构
- 标志名称和行为
- `_meta`块格式

---

Integration with CASS Memory (cm)

与CASS Memory (cm)集成

CASS provides episodic memory (raw sessions). CM extracts procedural memory (rules and playbooks):

bash

undefined

CASS提供情景记忆（原始会话）。CM提取过程记忆（规则和操作手册）：

bash

undefined

1. CASS indexes raw sessions

1. CASS索引原始会话

cass index --full

2. Search for relevant past experience

2. 搜索相关过往经验

cass search "authentication timeout" --robot --limit 10

3. CM reflects on sessions to extract rules

3. CM反思会话以提取规则

cm reflect

---

cm reflect

---

Troubleshooting

故障排除

Issue	Solution
"missing index"	`cass index --full`
Stale warning	Rerun index or enable watch
Empty results	Check `cass stats --json` , verify connectors detected
JSON parsing errors	Use `--robot-format compact`
Watch not triggering	Check `watch_state.json` , verify file event support
Reset TUI state	`cass tui --reset-state` or `Ctrl+Shift+Del`

问题	解决方案
"missing index"	`cass index --full`
过期警告	重新运行索引或启用监听模式
空结果	检查 `cass stats --json` ，验证连接器是否检测到
JSON解析错误	使用 `--robot-format compact`
监听模式未触发	检查 `watch_state.json` ，验证文件事件支持
重置TUI状态	`cass tui --reset-state` 或 `Ctrl+Shift+Del`

Installation

安装

bash

undefined

bash

undefined

One-liner install

一键安装

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh
| bash -s -- --easy-mode --verify

Windows

irm https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.ps1 | iex

---

irm https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.ps1 | iex

---

Integration with Flywheel

与Flywheel集成

Tool	Integration
CM	CASS provides episodic memory, CM extracts procedural memory
NTM	Robot mode flags for searching past sessions
Agent Mail	Search threads across agent history
BV	Cross-reference beads with past solutions

工具	集成方式
CM	CASS提供情景记忆，CM提取过程记忆
NTM	机器人模式标志用于搜索过往会话
Agent Mail	跨Agent历史搜索线程
BV	将beads与过往解决方案交叉引用