/cass_memory_system

name: cm
description: "CASS Memory System - procedural memory for AI coding agents. Three-layer cognitive architecture with confidence decay, anti-pattern learning, cross-agent knowledge transfer, trauma guard safety system. Bun/TypeScript CLI."

CM - CASS Memory System

Procedural memory for AI coding agents. Transforms scattered sessions into persistent, cross-agent memory. Uses a three-layer cognitive architecture that mirrors human expertise development.

Why This Exists

AI coding agents accumulate valuable knowledge but it's:

• **Trapped in sessions** - Context lost when session ends
• **Agent-specific** - Claude doesn't know what Cursor learned
• **Unstructured** - Raw logs aren't actionable guidance
• **Subject to collapse** - Naive summarization loses critical details

You've solved auth bugs three times this month across different agents. Each time you started from scratch.

CM solves this with cross-agent learning: a pattern discovered in Cursor is immediately available to Claude Code.

---

Three-Layer Cognitive Architecture

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

Every agent's sessions feed the shared memory. A pattern discovered in Cursor **automatically** helps Claude Code on the next session.

---

The One Command You Need

cm context "<your task>" --json

**Run this before starting any non-trivial task.** Returns:

• **relevantBullets** - Rules from playbook scored by task relevance
• **antiPatterns** - Things that have caused problems
• **historySnippets** - Past sessions (yours and other agents')
• **suggestedCassQueries** - Deeper investigation searches

Filtering History by Source

`historySnippets[].origin.kind` is `"local"` or `"remote"`. Remote hits include `origin.host`:

{
  "historySnippets": [
    {
      "source_path": "~/.claude/sessions/session-001.jsonl",
      "origin": { "kind": "local" }
    },
    {
      "source_path": "/home/user/.codex/sessions/session.jsonl",
      "origin": { "kind": "remote", "host": "workstation" }
    }
  ]
}

---

Confidence Decay System

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 4× as much as one success | | **Maturity progression** | `candidate` → `established` → `proven` |

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

Effective Score Formula

effectiveScore = decayedHelpful - (4 × decayedHarmful)

// Where decay factor = 0.5 ^ (daysSinceFeedback / 90)

Maturity State Machine

  ┌──────────┐       ┌─────────────┐    ┌────────┐
  │ candidate│──────▶│ established │───▶│ proven │
  └──────────┘       └─────────────┘    └────────┘
       │                   │                  │
       │                   │ (harmful >25%)   │
       │                   ▼                  │
       │             ┌─────────────┐          │
       └────────────▶│ deprecated  │◀─────────┘
                     └─────────────┘

**Transition Rules:**

| Transition | Criteria | |------------|----------| | `candidate` → `established` | 3+ helpful, harmful ratio <25% | | `established` → `proven` | 10+ helpful, harmful ratio <10% | | `any` → `deprecated` | Harmful ratio >25% OR explicit deprecation |

---

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"

When a rule is marked harmful multiple times (>50% harmful ratio with 3+ marks), it's automatically inverted into an anti-pattern.

---

ACE Pipeline (How Rules Are Created)

Generator → Reflector → Validator → Curator

| Stage | Role | LLM? | |-------|------|------| | **Generator** | Pre-task context hydration (`cm context`) | No | | **Reflector** | Extract patterns from sessions (`cm reflect`) | Yes | | **Validator** | Evidence gate against cass history | Yes | | **Curator** | Deterministic delta merge | **No** |

**Critical:** Curator has NO LLM to prevent context collapse from iterative drift. LLMs propose patterns; deterministic logic manages them.

Scientific Validation

Before a rule joins your playbook, it's validated against cass history:

Proposed rule: "Always check token expiry before auth debugging"
    ↓
Evidence gate: Search cass for sessions where this applied
    ↓
Result: 5 sessions found, 4 successful outcomes → ACCEPT

Rules without historical evidence are flagged as candidates until proven.

---

Commands Reference

Context Retrieval (Primary Workflow)

# THE MAIN COMMAND - run before non-trivial task