tkersey/cass-memory

<!-- TOC: Quick Start | THE EXACT PROMPT | Architecture | Commands | References -->

cass-memory — CASS Memory System (cm)

Core Capability: Transforms scattered agent sessions into persistent, cross-agent procedural memory. A pattern discovered in Cursor automatically helps Claude Code on the next session.

Quick Start

# Initialize with a starter playbook
cm init --starter typescript

# THE ONE COMMAND: run before any non-trivial task
cm context "implement user authentication" --json

# Check system health
cm doctor --json

---

THE EXACT PROMPT — Session Start

Before starting this task, run:

cm context "<task description>" --json

Read the output carefully:
- relevantBullets: Rules from playbook scored by relevance
- antiPatterns: Things that have caused problems before
- historySnippets: Past sessions (yours and other agents')
- suggestedCassQueries: Deeper investigation if needed

Reference rule IDs when following them (e.g., "Following b-8f3a2c...")

---

THE EXACT PROMPT — Rule Feedback

# When a rule helped
cm mark b-8f3a2c --helpful

# When a rule caused problems
cm mark b-xyz789 --harmful --reason "Caused regression"

# Or leave inline comments (parsed during reflection)
// [cass: helpful b-8f3a2c] - this saved me from a rabbit hole
// [cass: harmful b-x7k9p1] - wrong for our use case

---

THE EXACT PROMPT — Trauma Guard Setup

# Install safety hooks to prevent dangerous commands
cm guard --install       # Claude Code hook
cm guard --git          # Git pre-commit hook
cm guard --status       # Check installation

# Add custom trauma patterns
cm trauma add "DROP TABLE" --description "Mass deletion" --severity critical

# Scan past sessions for trauma patterns
cm trauma scan --days 30

---

Three-Layer Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    EPISODIC MEMORY (cass)                           │
│   Raw session logs from all agents — the "ground truth"             │
└───────────────────────────┬─────────────────────────────────────────┘
                            │ cass search
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    WORKING MEMORY (Diary)                           │
│   Structured session summaries: accomplishments, decisions, etc.    │
└───────────────────────────┬─────────────────────────────────────────┘
                            │ reflect + curate (automated)
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    PROCEDURAL MEMORY (Playbook)                     │
│   Distilled rules with confidence tracking and decay                │
└─────────────────────────────────────────────────────────────────────┘

---

Essential Commands

| Command | Purpose | |---------|---------| | cm context "<task>" --json | Get rules + history for task | | cm mark <id> --helpful/--harmful | Record feedback | | cm playbook list | View all rules | | cm top 10 | Top effective rules | | cm doctor --json | System health | | cm guard --install | Install safety hooks |

---

Agent Protocol

1. START:    cm context "<task>" --json
2. WORK:     Reference rule IDs when following them
3. FEEDBACK: Leave inline comments when rules help/hurt
4. END:      Just finish. Learning happens automatically.

You do NOT need to:

• Run cm reflect (automation handles this)
• Run cm mark manually (use inline comments)
• Manually add rules to the playbook

---

Confidence Decay

Rules aren't immortal. Confidence decays without revalidation:

| Mechanism | Effect | |-----------|--------| | 90-day half-life | Confidence halves every 90 days without feedback | | 4x harmful multiplier | One mistake counts 4x as much as one success | | Maturity progression | candidate → established → proven |

---

Anti-Pattern Learning

Bad rules don't just get deleted. They become warnings:

"Cache auth tokens for performance"
    ↓ (3 harmful marks)
"PITFALL: Don't cache auth tokens without expiry validation"

---

Starter Playbooks

cm starters                    # List available
cm init --starter typescript   # Initialize with starter
cm playbook bootstrap react    # Apply to existing playbook

| Starter | Focus | |---------|-------| | general | Universal best practices | | typescript | TypeScript/Node.js | | react | React/Next.js | | python | Python/FastAPI/Django | | rust | Rust service patterns |

---

Token Budget Management

| Flag | Effect | |------|--------| | --limit N | Cap number of rules | | --min-score N | Only rules above threshold | | --no-history | Skip historical snippets | | --json | Structured output |

---

Graceful Degradation

| Condition | Behavior | |-----------|----------| | No cass | Playbook-only scoring, no history | | No playbook | Empty playbook, commands still work | | No LLM | Deterministic reflection | | Offline | Cached playbook + local diary |

---

Installation

# One-liner
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/cass_memory_system/main/install.sh \
  | bash -s -- --easy-mode --verify

# From source
git clone https://github.com/Dicklesworthstone/cass_memory_system.git
cd cass_memory_system
bun install && bun run build
sudo mv ./dist/cass-memory /usr/local/bin/cm

---

Troubleshooting

| Error | Solution | |-------|----------| | cass not found | Install cass first | | API key missing | Set ANTHROPIC_API_KEY | | Playbook corrupt | Run cm doctor --fix |

---

References

| Topic | Reference | |-------|-----------| | Full command reference | COMMANDS.md | | Cognitive architecture | ARCHITECTURE.md | | Trauma guard system | TRAUMA-GUARD.md | | MCP server integration | MCP-SERVER.md | | Onboarding workflow | ONBOARDING.md |