Cass

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.

Constraints

• Never run bare cass because it launches a blocking TUI; use a JSON, robot, or explicit file-output command.
• Within authorized sources and destinations, treat a stale index as searchable and refresh it only when the selected invocation permits indexing, using a bounded background command; stale is not broken.
• Preserve source sessions and require explicit permission for destructive cleanup; recovery may rebuild only derived index state.

Authorization and episode association

Before any search, view, context lookup, export, index recovery or sync, check source-owner, task, model/provider and destination authorization. Indexes, hit metadata, source paths and tracker comments inherit source restrictions; read permission does not permit forwarding to another model or versioning in Git. The recovery defaults below apply only inside this authorized envelope; source sync and model downloads also require the selected egress authority. Unavailable controls leave restricted-source operations unavailable, without retrieving first and redacting later. Missing, restricted, unavailable, no-match and insufficient evidence are different outcomes.

Capture work identity at dispatch/start and observed native IDs at startup through the caller-owned native comments/metadata or runtime facts, independently of handoff. Use SESSION_FORMATS.md for source-store/work identity, parent/resume provenance, supported work spans, permitted locators and available frozen source bounds/digests. Native logs retain execution authority; CASS discovers candidates. Search/view/expand/context output does not prove a complete episode was read or that a related hit is a parent. Record query, filters, limit, index freshness and discovery cutoff; zero hits means no match within those observed limits, not absence everywhere. Missing children, new tails and unknown source lengths remain explicit. T09 owns later coverage verification; this skill does not implement or certify it.

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

Folded triggers (ag-s43tg wave 1): casr + cass-memory route here

• casr → cross-harness resume. RESUME.md distinguishes cass resume (same-harness command resolution) from the separate cross-harness converter. cass context discovers candidate relations; verify a native parent link before choosing a parent session to resume.
• cass-memory → cm procedural memory. Use when starting non-trivial work, mining lessons, or preventing repeated mistakes with cm procedural memory — mine past sessions here first, then promote the durable lessons through cm instead of re-deriving them each session.

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. CASS is a context source in the federated graph: it supplies cited episodic evidence on demand — mine as a research-phase move before writing a fresh plan or prompt. What it returns is evidence with source identity and freshness, never policy, and AgentOps maintains no merged corpus of its own around it.

History-First Routing

Before deriving a plan, prompt, or approach from scratch, run one bounded search of past sessions (one query family, --fields minimal, a real --limit, under a minute of wall clock). Three outcomes, each with its own routing:

• Direct hit — a prior session solved this. Reuse its prompt or decision; cite source_path and line in whatever you build on it.
• Adjacent hit — prior work borders the problem. Extract the working fragments, then derive only the missing part fresh.
• Bounded no-match — zero hits after retrying against authorized discovered workspace keys (--aggregate workspace). Derive from available evidence and report the query/index limits; this does not establish global absence.

The named failure mode is re-derivation drift: solving the same problem slightly differently each session, so the corpus accumulates near-duplicate approaches and no single one ever hardens into a ritual. Stop condition for the history pass itself: one query family exhausted or a direct hit found — history search is a bounded pre-step, not an open-ended excavation that displaces the actual task.

Lesson Weighting: Decay and Failure Overweight

Mined lessons are evidence with a shelf life, not doctrine:

• Confidence decays with corpus drift. Weight a mined lesson by what has changed since it was captured, not by calendar age alone. A lesson about a tool surface or repository that has since moved is a hypothesis to re-verify — one probe against the current surface — before it steers a fresh plan. A lesson about durable method (how to decompose, how to verify) decays far more slowly. Never carry a stale-surface lesson forward at its original confidence; the named failure mode is fossil doctrine — a dead workaround reapplied for months because it once worked and nobody re-checked.
• Overweight failures. A session where an approach failed is worth more than a session where one worked: successes are overrepresented in what gets polished and remembered, while failures encode the boundary of validity. When mining prior art for an approach, explicitly search for its failures ("didn't work", "reverted", "gave up", error strings) before adopting it. A hit showing the approach failing in circumstances like yours outranks three hits showing it succeeding elsewhere.

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 authorized hits: View a bounded excerpt of the actual content
   cass view /path/from/source_path.jsonl -n LINE -C 20

4. Expand context: Inspect another bounded conversation window
   cass expand /path/from/source_path.jsonl --line LINE --context 3

5. Discover related: Find candidates, not proven parents or a complete 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 (a discovery heuristic, not guaranteed prompt position), 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:

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.

Incremental refresh can become authoritative

An invocation requested as cass index --json may discover that incremental state cannot be reconciled and expand into an authoritative rebuild over the full conversation corpus. A large total or a longer run is evidence of recovery mode, not evidence that source sessions were lost. Do not start a second indexer or report a zero-result search while the first call is still converging.

Concurrent status and search reads can exceed their normal latency during that rebuild. Bound observations with a wall-clock timeout, retain the exit status, and distinguish timeout from an empty result:

status_rc=0
timeout 15 cass status --json > /tmp/cass-status.json || status_rc=$?
# Exit 124 means status was not observed within the cap.

search_rc=0
timeout 30 cass search "QUERY" --json --fields minimal --limit 20 \
  > /tmp/cass-search.json || search_rc=$?
# Exit 124 is NOT zero hits; retry after the rebuild settles.

If status returns, inspect .rebuild.active, .rebuild.phase, .rebuild.processed_conversations, .rebuild.total_conversations, and .rebuild.updated_at. When updated_at or processed count advances, wait for that bounded run rather than stacking recovery. If a bounded read times out, report only that the read was not observed within the cap and keep the last known freshness; do not infer corruption or data loss. See OBSERVABILITY.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)

Long-form versions with mined evidence: ANTI_PATTERNS.md.

Safety Boundaries

Within the authorized source/model/destination and egress envelope above, the following operate on derived state rather than granting new source access: 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

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/. Inspect their access and write scope before use when uncertain. Consistent with the Safety Boundaries above, recover.sh and quick_analysis.sh may rebuild derived index state autonomously (pre-authorized: doctor --fix, index --full) and multi_machine_search.sh reads remote sources over ssh; none destroy source sessions, and nothing destructive (coredump/.beads deletion, git reset --hard, source edits) runs without explicit confirmation.

Validation

# Quick health check
cass status --json | jq '.index.fresh'

# Should return: true

If false, run: cass index --json

Output Specification

• Path: stdout for search, status, capability, and introspection results; this skill creates no artifact directory by default.
• Filename: none unless the caller explicitly requests an export path such as /tmp/cass-export.json with -o.
• Format: use the installed command's JSON schema from cass introspect --json; wide searches should keep --fields minimal and downstream narrowing must preserve source_path and line location.
• Exit code: validate with cass status --json | jq -e . and parse every selected result with jq; a nonzero command, malformed JSON, or unresolved source path blocks the handoff.
• Downstream handoff: consumed by research, planning, recovery, or postmortem work with the exact query, canonical workspace, selected source paths/lines, and index freshness noted.

Quality Checklist

• Results come from a canonical workspace key and include enough source location to reopen the session context.
• A zero-hit result was retried against authorized discovered workspace keys and reported as bounded no-match with its discovery limits.
• Index recovery stayed bounded and preserved source sessions; no stale state was misreported as broken.