majiayu000 cass Session Search
Core Insight: Your repeated prompts are your best prompts. If you typed it 10+ times, it works. Mine your history.
cass is an upstream (Dicklesworthstone) tool and is self-describing — do not re-learn its surface from this skill. Discover it live:
cass capabilities --json # features/connectors/limits of the installed binary
cass introspect --json # full schema of every command + response
cass robot-docs guide|commands|examples|schemas|contracts # machine-targeted docs
This skill carries only the AgentOps operating doctrine: when to reach for cass, the discovery workflow, the recovery posture, and the anti-patterns we have actually hit.
When to Use
- "What did I ask last time?" / "find that prompt that worked" — session archaeology
- Prior-art check before inventing a new approach, plan, or prompt
- Scope archaeology: "when did we decide NOT to do X?"
- Post-context-loss recovery: what was searched for after a crash = what mattered
The Goldmine Principle
Your conversation history contains:
- Refined prompts — Every rephrase that worked better was captured
- Working rituals — Prompts repeated 10+ times ARE your methodology
- Scope decisions — "When did we decide NOT to do X?"
- Recovery moments — What you searched for after context loss = what mattered
The insight: Mining your past beats inventing new approaches. In the AgentOps loop the goal is prior-art first: mine as a research-phase move before writing a fresh plan or prompt, and feed what you find back into the corpus instead of re-deriving it.
THE EXACT PROMPT — Discovery Workflow
1. Bootstrap: Check health, refresh index, get project overview
cass status --json && cass index --json
cass search "*" --workspace /data/projects/PROJECT --aggregate agent,date --limit 1 --json
2. Find prompts: Search for keywords, filter to user prompts (lines 1-3)
cass search "KEYWORD" --workspace /data/projects/PROJECT --json --fields minimal --limit 50 \
| jq '[.hits[] | select(.line_number <= 3)]'
3. Follow hits: View the actual content
cass view /path/from/source_path.jsonl -n LINE -C 20
4. Expand context: See the full conversation flow
cass expand /path/from/source_path.jsonl --line LINE --context 3
5. Discover related: Find the whole work cluster
cass context /path/from/source_path.jsonl --json
Why it works: aggregations first (know the terrain), --fields minimal (5x smaller output), line_number <= 3 (user prompts live at the top), context clustering (one good hit → many related sessions). >10 matches for a prompt = a ritual; document and reuse it.
Operating Doctrine: Stale ≠ Broken
Three index states matter — never conflate them:
| State | Meaning | Do |
|---|---|---|
cass health exit 0 |
Healthy | Search immediately |
stale (index.stale=true) |
Usable but old | Search NOW; refresh in background with a wall-clock cap: ( timeout 600 cass index --json &>/tmp/cass-bg.log </dev/null & ) — NEVER a bare &, cass index can hang |
broken (database.exists=false or documents=0) |
Truly uninitialized | cass doctor --fix --json, then cass index --full --json |
The trap: treating stale as broken triggers an unneeded 8–25s full rebuild when a 1–3s incremental (or a stale-but-correct query) would do. scripts/recover.sh implements the full decision tree with timeouts. Detailed symptom→fix tables (issue #196 hang, stale locks, database is busy race, etc.): RECOVERY.md, OBSERVABILITY.md, PITFALLS.md.
Version Pinning
cass evolves quickly; the released binary may lack HEAD features. When a flag returns "unrecognized", do not guess — probe: cass capabilities --json and cass introspect --json | jq '.commands[].name', and check cass --version.
Anti-Patterns (Don't Do These)
| Anti-pattern | Why it's wrong | Do instead |
|---|---|---|
| Asking the user "should I rebuild the index?" | They have agents waiting; rebuild is safe and idempotent | Just run cass doctor --fix --json (preserves source data) |
Running cass index --full whenever status says unhealthy |
A 25s rebuild for a 30-min stale index is wasteful | Check index.stale separately from database.exists; prefer incremental |
Running bare cass to "see what's there" |
Launches blocking TUI in the agent's session | Always --json or --robot; never bare |
Piping cass export into head/jq |
Broken-pipe panic on large sessions | cass export ... -o /tmp/x.json first, then operate on the file |
| Treating subagent files as parent sessions | Subagents are separate logs with their own line-2 prompt; also NOT resumable | Filter by select(.source_path | contains("subagent")); resolve to parent via cass context before cass resume |
Using --limit 0 for "no limit" |
Earlier cass panics | Use a real limit (--limit 50); --limit 1 minimum for aggregations |
Trusting 0 hits with --workspace /X |
Workspace strings are case- and trailing-slash-sensitive | Re-run with --aggregate workspace --limit 1 to discover the canonical key |
Skipping --fields minimal on wide scans |
~3KB per hit × 100 hits = 300KB context burn | --fields minimal for wide passes; upgrade to summary/full for keepers |
Reading session files with cat |
Loads the full conversation into context | cass view PATH -n LINE -C 5 or cass expand PATH --line LINE --context 3 |
| Re-indexing on every search | Index is shared across processes | Refresh only when status says stale |
Falling back to manual find/grep when cass misbehaves |
Recovery is autonomous; skipping cass loses the corpus | Walk the recovery tree in RECOVERY.md. One real exception: terms inside tool stdout/stderr are skipped at index time — there rg -n "TERM" /path.jsonl is correct |
Long-form versions with mined evidence: ANTI_PATTERNS.md.
Safety Boundaries
Pre-authorized (rebuilds derived index data only, never destroys source sessions): cass doctor --fix --json, cass index --full --force-rebuild --json, cass sources doctor/sync, cass models install/verify.
Do NOT without explicit permission: delete core.NNNNN coredumps, delete .beads/, git reset --hard, or hand-edit ~/.config/cass/sources.toml — the CLI commands above already do everything safely. Never run bare cass (blocking TUI) inside an agent loop.
Reference Index
| Need | Reference |
|---|---|
| Full command reference | COMMANDS.md |
| Workflow recipes | RECIPES.md |
| jq patterns | PATTERNS.md |
| Pitfalls & fixes | PITFALLS.md |
| Session file formats | SESSION_FORMATS.md |
| Remote sources, multi-machine search | REMOTE_SOURCES.md |
| Semantic / hybrid / models | SEMANTIC_AND_HYBRID.md |
| Token / tool / model analytics | ANALYTICS.md |
| Cross-harness session resume | RESUME.md |
| Doctor + autonomous recovery | RECOVERY.md |
| Mined gold-standard prompts | PROMPTS.md |
| Anti-patterns (long form) | ANTI_PATTERNS.md |
| Health vs status vs index nuance | OBSERVABILITY.md |
| Pages encrypted archive + HTML export | PAGES_AND_EXPORT.md |
Harness exclusion (disabled_agents) |
HARNESS_EXCLUSION.md |
| Schema introspection contracts | INTROSPECTION.md |
When the right reference isn't obvious from titles, grep -ni "SYMPTOM" references/*.md — cheaper than loading whole files into context.
Scripts
Scripts live under scripts/. They execute, never load — zero context tokens. None mutate state without explicit confirmation.
| Script | Usage |
|---|---|
./scripts/quick_analysis.sh /path |
One-command project overview (status → aggregate agent/date → top prompts) |
./scripts/prompt_miner.py --workspace /path |
Find repeated prompts (ritual detection) |
./scripts/validate.sh |
Validate cass install + skill structure |
./scripts/recover.sh |
Autonomous recovery decision tree (READY → STALE_BUT_USABLE → BROKEN); wraps every cass index in timeout |
./scripts/multi_machine_search.sh "QUERY" [host…] |
Parallel fan-out across the fleet; merges + dedups hits |
Validation
# Quick health check
cass status --json | jq '.index.fresh'
# Should return: true
If false, run: cass index --json