build a cass fix from source (e.g. a commit not yet in a stable release), install

Verify Installation

cm --version
cm doctor --json

Initial Setup

# Initialize (creates global config and playbook)
cm init
Or with a starter playbook for common patterns
cm init --starter typescript  # or: react, python, go
cm starters  # list available starters

Automating Reflection

The key to the system is automated reflection. Set up a cron job or hook:

# Daily reflection on recent sessions
cm reflect --days 7 --json
Only one project's sessions, only some agents
cm reflect --workspace ~/code/api --agent claude,codex --json
Via cron (runs at 2am daily)
0 2   * /usr/local/bin/cm reflect --days 7 >> ~/.cass-memory/reflect.log 2>&1

For Claude Code, install the auto-reflect hook once and every finished session is reflected in the background:

cm hook install            # this project (.claude/settings.json)
cm hook install --global   # every project (~/.claude/settings.json)
cm hook status             # where it is installed
cm hook uninstall          # remove it (other hooks are left alone)

For other agents, call the same entry point from a wrapper script or the agent's own end-of-session hook:

cm hook session-end --transcript ~/.codex/sessions/2026/10/06/rollout.jsonl

🛠️ CLI Reference

Quick Reference Table

Error Output & Exit Codes

{
  "success": false,
  "error": "…",
  "code": "…",
  "exitCode": 2,
  "recovery": ["…", "…"],
  "cause": "…",
  "docs": "README.md#-troubleshooting",
  "hint": "…",
  "details": {}
}

Exit codes are categorized for scripting:

Agent Commands (Primary Workflow)

# Get context before starting a task (THE MAIN COMMAND)
cm context "implement user authentication" --json
Self-documenting explanation of the system
cm quickstart --json
Find rules similar to a query
cm similar "error handling best practices"
Machine-readable CLI docs (JSON): all topics, or one of
guide | commands | examples | exit-codes | schemas
cm robot-docs
cm robot-docs schemas

Playbook Commands (Inspect & Manage Rules)

# List all active rules
cm playbook list
Get detailed info for a specific rule
cm playbook get b-8f3a2c
Add a new rule manually
cm playbook add "Always run tests before committing"
Remove/deprecate a rule
cm playbook remove b-xyz789 --reason "No longer applicable"
Export playbook for backup or sharing
cm playbook export > playbook-backup.yaml
Import playbook from file. Rules matching an existing one by text (exact,
or near-identical wording) merge their feedback into it instead of becoming
duplicates; contradictions with existing rules are reported.
cm playbook import shared-playbook.yaml
Find rules that contradict each other (with a keep/retire suggestion)
cm playbook conflicts --json
Strip feedback that came from cm's own LLM subprocess transcripts (or any
session path pattern), recount helpful/harmful, re-derive maturity.
Backs up each playbook first; bullets left without genuine support are
reported, and deprecated only with --deprecate-orphans.
cm playbook scrub --cm-subprocess-calls --dry-run --json
cm playbook scrub --from-sessions "/old-project/" --deprecate-orphans
Show top N most effective rules
cm top 10
Find rules without recent feedback (stale)
cm stale --days 60
Show why a rule exists (provenance)
cm why b-8f3a2c
Get playbook health metrics
cm stats --json

Learning Commands (Feedback & Reflection)

# Process recent sessions into rules (usually automated)
cm reflect --days 7 --json
Manual feedback on a rule
cm mark b-8f3a2c --helpful
cm mark b-xyz789 --harmful --reason "Caused regression"
Record session outcome (positional: status, rules)
cm outcome success b-8f3a2c,b-def456
cm outcome failure b-x7k9p1 --summary "Auth approach failed"
Apply recorded outcomes to playbook
cm outcome-apply
Validate a proposed rule against history
cm validate "Always check null before dereferencing"
Deprecate a rule permanently
cm forget b-xyz789 --reason "Superseded by better pattern"
Revert a curation decision
cm undo b-xyz789
Check sessions for rule violations
cm audit --days 30

System Commands (Setup & Diagnostics)

# Initialize configuration and playbook
cm init
cm init --starter typescript  # With starter template
cm starters                   # List available starters
Check system health
cm doctor --json
cm doctor --fix               # Auto-fix issues
Check for / install a newer release
cm update --check             # Exit code 0 = up to date, 1 = update available
cm update                     # Re-runs the documented install script (interactive only)
Export rules for AGENTS.md
cm project --format agents.md
Show LLM cost and usage statistics
cm usage
Run MCP HTTP server for agent integration (default: 127.0.0.1:8765)
cm serve
Privacy controls
cm privacy status
cm privacy enable   # Enable cross-agent enrichment
cm privacy disable  # Disable cross-agent enrichment

Safety Commands (Trauma Guard)

# View active trauma patterns
cm trauma list
Add a dangerous pattern
cm trauma add "DROP TABLE" --description "Database table deletion" --severity critical
Temporarily disable a pattern
cm trauma heal t-abc123 --reason "Intentional migration cleanup"
Permanently remove a pattern
cm trauma remove t-abc123
Scan sessions for potential traumas
cm trauma scan --days 30
Import patterns from file
cm trauma import shared-traumas.yaml
Install safety hooks
cm guard --install           # Claude Code pre-tool hook
cm guard --git               # Git pre-commit hook
cm guard --install --git     # Both
cm guard --status            # Check installation status

Command Output Modes

All commands support multiple output formats:

🔬 The ACE Pipeline

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  GENERATOR   │ ──▶ │  REFLECTOR   │ ──▶ │  VALIDATOR   │ ──▶ │   CURATOR    │
│              │     │              │     │              │     │              │
│ Pre-task     │     │ LLM pattern  │     │ Evidence     │     │ Deterministic│
│ context      │     │ extraction   │     │ gate against │     │ delta merge  │
│ hydration    │     │ from diary   │     │ cass history │     │ (NO LLM!)    │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘

Hydrates the agent with relevant rules before starting a task.

async function generateContext(task: string): Promise<ContextResult> {
  // 1. Extract keywords from task
  const keywords = extractKeywords(task);
// 2. Relevance: BM25 over the playbook (IDF-weighted share of the query a
  //    bullet covers, 0..10), blended with embedding similarity when enabled
  const lexical = scoreLexicalRelevance(bullets, keywords);
  const scored = bullets.map(b => {
    const relevanceScore = blend(lexical.get(b.id), cosine(taskEmbedding, b.embedding) * 10);
    // 3. Track record only reorders within a bounded band: [1 - w, 1 + w],
    //    damped while a bullet has few marks (feedbackWeight, default 0.25)
    return { ...b, relevanceScore, finalScore: relevanceScore * getFeedbackMultiplier(b) };
  }).sort(byFinalScore);
// 4. Keep what is relevant and fits: absolute + relative relevance floors,
  //    maxBulletsInContext, then contextTokenBudget
  const { selected, stats } = selectContextBullets(scored, config);
// 5. Search cass for historical context
  const historySnippets = await safeCassSearch(task, {
    limit: config.maxHistoryInContext,
    days: config.sessionLookbackDays
  });
return {
    task,
    relevantBullets: selected.filter(isRule).map(toContextBullet),  // compact: no event log
    antiPatterns: selected.filter(isAntiPattern).map(toContextBullet),
    historySnippets,
    retrieval: stats,  // candidates / returned / dropped by relevance, limit, budget
    suggestedCassQueries: generateSuggestedQueries(task, keywords)
  };
}

Processes unprocessed sessions to extract new rules.

How It Works:

1. Find unprocessed sessions via cass timeline API
2. Generate diary entries - structured summaries of each session:

1. Run LLM reflector - multi-iteration pattern extraction
2. Output deltas - add/helpful/harmful/deprecate operations

Analyze this session diary and extract actionable rules.
For each pattern you identify:
Formulate as an imperative rule ("Always...", "Never...", "When X, do Y")
Categorize (testing, debugging, git, architecture, etc.)
Assess scope (global, workspace, language, framework)
Provide reasoning for why this is valuable
Output format: JSON array of proposed rules

Stage 3: Validator

Scientific gate ensuring rules have evidence.

async function validateRule(rule: ProposedRule): Promise<ValidationResult> {
  // 1. Evidence count gate - fast pre-filter
  const evidenceCount = await countEvidenceInCass(rule);
  if (evidenceCount < MIN_EVIDENCE_COUNT) {
    return { verdict: 'NEEDS_MORE_EVIDENCE', evidenceCount };
  }
// 2. LLM validation - deep analysis
  const llmVerdict = await llmValidate(rule, evidenceCount);
// 3. Final verdict
  return {
    verdict: llmVerdict.valid ? 'ACCEPT' : 'REJECT',
    reasoning: llmVerdict.reasoning,
    evidenceCount
  };
}

Stage 4: Curator

Critical: NO LLM in this stage - pure deterministic logic to prevent context collapse.

Why No LLM? LLMs tend to "drift" when iteratively refining their own outputs. By keeping curation deterministic, we:

• Prevent feedback loops that degrade rule quality
• Ensure reproducible behavior
• Avoid expensive redundant LLM calls

function curate(playbook: Playbook, deltas: Delta[]): Playbook {
  for (const delta of deltas) {
    switch (delta.type) {
      case 'add':
        // Conflict detection - find contradicting rules
        const conflicts = findConflicts(playbook, delta.rule);
        if (conflicts.length > 0) {
          resolveConflicts(playbook, conflicts, delta);
        }
// Duplicate detection - hash-based and semantic
        const duplicate = findDuplicate(playbook, delta.rule);
        if (duplicate) {
          mergeDuplicate(duplicate, delta.rule);
          continue;
        }
// Add new rule
        playbook.bullets.push(delta.rule);
        break;
case 'helpful':
        // Update feedback
        addFeedback(playbook, delta.bulletId, 'helpful', delta.timestamp);
        maybePromoteMaturity(playbook, delta.bulletId);
        break;
case 'harmful':
        // Update feedback with harmful multiplier consideration
        addFeedback(playbook, delta.bulletId, 'harmful', delta.timestamp);
        maybeConvertToAntiPattern(playbook, delta.bulletId);
        break;
case 'deprecate':
        deprecateRule(playbook, delta.bulletId, delta.reason);
        break;
    }
  }
// Maturity promotions based on feedback thresholds
  promoteQualifiedRules(playbook);
return playbook;
}

📊 Data Models

Playbook Bullet

The core data structure for rules:

interface PlaybookBullet {
  // Identity
  id: string;                    // "b-{timestamp}-{random}"
  content: string;               // The actual rule
  category: string;              // "testing" | "git" | "debugging" | etc.
// Classification
  scope: "global" | "workspace" | "language" | "framework" | "task";
  type: "rule" | "anti-pattern";
  kind: "project_convention" | "stack_pattern" | "workflow_rule" | "anti_pattern";
  isNegative: boolean;
// Lifecycle
  state: "draft" | "active" | "retired";
  maturity: "candidate" | "established" | "proven" | "deprecated";
// Feedback & Scoring
  helpfulCount: number;          // Raw count
  harmfulCount: number;          // Raw count
  feedbackEvents: FeedbackEvent[];  // Full history with timestamps
  effectiveScore?: number;       // Calculated decay-adjusted score
// Provenance
  sourceSessions: string[];      // Sessions that generated this rule
  sourceAgents: string[];        // Agents involved (claude, codex, cursor, etc.)
  reasoning?: string;            // Why this rule exists
  sourceSession?: string;        // Flexible field for reflection metadata
// Metadata
  tags: string[];
  embedding?: number[];          // Semantic search vector (768 dimensions)
  pinned: boolean;               // Prevent auto-deprecation
  deprecated: boolean;
// Timestamps
  createdAt: string;             // ISO 8601
  updatedAt: string;             // ISO 8601
}

Feedback Event

Immutable record of feedback:

interface FeedbackEvent {
  id: string;                    // UUID
  type: "helpful" | "harmful";
  timestamp: string;             // ISO 8601
  source: "inline" | "manual" | "outcome" | "audit";
  sessionPath?: string;          // Session where feedback was given
  reason?: string;               // Optional explanation
}

Diary Entry

Working memory structure:

interface DiaryEntry {
  id: string;                    // Deterministic hash of content
  sessionPath: string;           // Original cass session
  timestamp: string;             // ISO 8601
  agent: string;                 // "claude" | "codex" | "cursor" | etc.
  workspace?: string;            // Project directory
// Session status
  status: "success" | "failure" | "mixed";
// Core content
  accomplishments: string[];     // What was completed
  decisions: string[];           // Design choices made
  challenges: string[];          // Problems encountered
  keyLearnings: string[];        // Reusable insights
  preferences: string[];         // User style revelations
// Cross-agent enrichment
  relatedSessions?: RelatedSession[];
// Search optimization
  searchAnchors: string[];       // Keywords for retrieval
  tags: string[];                // File/component tags
}

Session Outcome

Explicit outcome recording:

interface SessionOutcome {
  id: string;                    // UUID
  timestamp: string;             // ISO 8601
  status: "success" | "failure" | "mixed";
// Associated rules
  rulesUsed: string[];           // Bullet IDs that were followed
  rulesViolated?: string[];      // Bullet IDs that were ignored
// Context
  task?: string;                 // What was attempted
  summary?: string;              // Brief description
  sessionPath?: string;          // Source session
// Feedback impact
  applied: boolean;              // Whether outcome-apply has processed this
  appliedAt?: string;            // When it was applied
}

📈 Scoring Algorithm

Effective Score Calculation

The effective score determines rule ranking, maturity transitions, and anti-pattern conversion:

function getEffectiveScore(bullet: PlaybookBullet): number {
  const HARMFUL_MULTIPLIER = 4;    // One harmful = 4× one helpful
  const HALF_LIFE_DAYS = 90;       // 90 days for half decay
// Calculate decayed helpful count
  const decayedHelpful = bullet.feedbackEvents
    .filter(e => e.type === "helpful")
    .reduce((sum, event) => {
      const daysAgo = daysSince(event.timestamp);
      const decayFactor = Math.pow(0.5, daysAgo / HALF_LIFE_DAYS);
      return sum + decayFactor;
    }, 0);
// Calculate decayed harmful count
  const decayedHarmful = bullet.feedbackEvents
    .filter(e => e.type === "harmful")
    .reduce((sum, event) => {
      const daysAgo = daysSince(event.timestamp);
      const decayFactor = Math.pow(0.5, daysAgo / HALF_LIFE_DAYS);
      return sum + decayFactor;
    }, 0);
// Effective score with harmful multiplier
  return decayedHelpful - (HARMFUL_MULTIPLIER * decayedHarmful);
}

Score Decay Visualization

Initial score: 10.0 (10 helpful marks today)
After 90 days (half-life):   5.0
After 180 days:              2.5
After 270 days:              1.25
After 365 days:              0.78

Why Time Decay?

1. Codebases evolve - A pattern helpful for React 17 may not apply to React 19
2. Tools change - Agent capabilities improve over time
3. Prevents stale rules - Forces ongoing validation
4. Natural cleanup - Unvalidated rules fade rather than accumulate

Maturity State Machine