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 tasks
cm context "implement user authentication" --json

# Limit results for token budget
cm context "fix bug" --json --limit 5 --no-history

# With workspace filter
cm context "refactor" --json --workspace /path/to/project

# Self-documenting explanation
cm quickstart --json

# System health
cm doctor --json
cm doctor --fix  # Auto-fix issues

# Find similar rules
cm similar "error handling best practices"

Playbook Management

cm playbook list                              # All rules
cm playbook get b-8f3a2c                      # Rule details
cm playbook add "Always run tests first"      # Add rule
cm playbook add --file rules.json             # Batch add from file
cm playbook add --file rules.json --session /path/session.jsonl  # Track source
cm playbook remove b-xyz --reason "Outdated"  # Remove
cm playbook export > backup.yaml              # Export
cm playbook import shared.yaml                # Import
cm playbook bootstrap react                   # Apply starter to existing

cm top 10                                     # Top effective rules
cm stale --days 60                            # Rules without recent feedback
cm why b-8f3a2c                               # Rule provenance
cm stats --json                               # Playbook health metrics

Learning & Feedback

# Manual feedback
cm mark b-8f3a2c --helpful
cm mark b-xyz789 --harmful --reason "Caused regression"
cm undo b-xyz789                              # Revert feedback

# Session outcomes (positional: status, rules)
cm outcome success b-8f3a2c,b-def456
cm outcome failure b-x7k9p1 --summary "Auth approach failed"
cm outcome-apply                              # Apply to playbook

# Reflection (usually automated)
cm reflect --days 7 --json
cm reflect --session /path/to/session.jsonl   # Single session
cm reflect --workspace /path/to/project       # Project-specific

# Validation
cm validate "Always check null before dereferencing"

# Audit sessions against rules
cm audit --days 30

# Deprecate permanently
cm forget b-xyz789 --reason "Superseded by better pattern"

Onboarding (Agent-Native)

Zero-cost playbook building using your existing agent:

cm onboard status                             # Check progress
cm onboard gaps                               # Category gaps
cm onboard sample --fill-gaps                 # Prioritized sessions
cm onboard sample --agent claude --days 14    # Filter by agent/time
cm onboard sample --workspace /path/project   # Filter by workspace
cm onboard sample --include-processed         # Re-analyze sessions
cm onboard read /path/session.jsonl --template  # Rich context
cm onboard mark-done /path/session.jsonl      # Mark processed
cm onboard reset                              # Start fresh

Trauma Guard (Safety System)

cm trauma list                                # Active patterns
cm trauma add "DROP TABLE" --description "Mass deletion" --severity critical
cm trauma heal t-abc --reason "Intentional migration"
cm trauma remove t-abc
cm trauma scan --days 30                      # Scan for traumas
cm trauma import shared-traumas.yaml

cm guard --install                            # Claude Code hook
cm guard --git                                # Git pre-commit hook
cm guard --install --git                      # Both
cm guard --status                             # Check installation

System Commands

cm init                                       # Initialize
cm init --starter typescript                  # With template
cm init --force                               # Reinitialize (creates backup)
cm starters                                   # List templates
cm serve --port 3001                          # MCP server
cm usage                                      # LLM cost stats
cm privacy status                             # Privacy settings
cm privacy enable                             # Enable cross-agent enrichment
cm privacy disable                            # Disable enrichment
cm project --format agents.md                 # Export for AGENTS.md

Starter Playbooks

Starting with an empty playbook is daunting. Starters provide curated best practices:

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

Built-in Starters

Starter	Focus	Rules
general	Universal best practices	5
typescript	TypeScript/Node.js patterns	4
react	React/Next.js development	4
python	Python/FastAPI/Django	4
node	Node.js/Express services	4
rust	Rust service patterns	4

Custom Starters

Create YAML files in ~/.cass-memory/starters/:

# ~/.cass-memory/starters/django.yaml
name: django
description: Django web framework best practices
bullets:
  - content: "Always use Django's ORM for database operations"
    category: database
    maturity: established
    tags: [django, orm]

Inline Feedback (During Work)

Leave feedback in code comments. Parsed during reflection:

// [cass: helpful b-8f3a2c] - this rule saved me from a rabbit hole

// [cass: harmful b-x7k9p1] - this advice was wrong for our use case

Agent Protocol

1. START:    cm context "<task>" --json
2. WORK:     Reference rule IDs when following them (e.g., "Following b-8f3a2c...")
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

Gap Analysis Categories

Category	Keywords
`debugging`	error, fix, bug, trace, stack
`testing`	test, mock, assert, expect, jest
`architecture`	design, pattern, module, abstraction
`workflow`	task, CI/CD, deployment
`documentation`	comment, README, API doc
`integration`	API, HTTP, JSON, endpoint
`collaboration`	review, PR, team
`git`	branch, merge, commit
`security`	auth, token, encrypt, permission
`performance`	optimize, cache, profile

Category Status Thresholds:

Status	Rule Count	Priority
`critical`	0 rules	High
`underrepresented`	1-2 rules	Medium
`adequate`	3-10 rules	Low
`well-covered`	11+ rules	None

Trauma Guard: Safety System

The "hot stove" principle—learn from past incidents and prevent recurrence.

How It Works

Session History              Trauma Registry              Runtime Guard
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│ rm -rf /* (oops)│ ──────▶ │ Pattern: rm -rf │ ──────▶ │ BLOCKED: This   │
│ "sorry, I made  │  scan   │ Severity: FATAL │  hook   │ command matches │
│  a mistake..."  │         │ Session: abc123 │         │ a trauma pattern│
└─────────────────┘         └─────────────────┘         └─────────────────┘

Built-in Doom Patterns (20+)

Category	Examples
Filesystem	`rm -rf /`, `rm -rf ~`, recursive deletes
Database	`DROP DATABASE`, `TRUNCATE`, `DELETE FROM` without WHERE
Git	`git push --force` to main/master, `git reset --hard`
Infrastructure	`terraform destroy -auto-approve`, `kubectl delete namespace`
Cloud	`aws s3 rm --recursive`, destructive CloudFormation

Pattern Storage

Scope	Location	Purpose
Global	`~/.cass-memory/traumas.jsonl`	Personal patterns
Project	`.cass/traumas.jsonl`	Commit to repo for team

Pattern Lifecycle

Active: Blocks matching commands
Healed: Temporarily bypassed (with reason and timestamp)
Deleted: Removed (can be re-added)

MCP Server

Run as MCP server for agent integration:

# Local-only (recommended)
cm serve --port 3001

# With auth token (for non-loopback)
MCP_HTTP_TOKEN="<random>" cm serve --host 0.0.0.0 --port 3001

Tools Exposed

Tool	Purpose	Parameters
`cm_context`	Get rules + history	`task, limit?, history?, days?, workspace?`
`cm_feedback`	Record feedback	`bulletId, helpful?, harmful?, reason?`
`cm_outcome`	Record session outcome	`sessionId, outcome, rulesUsed?`
`memory_search`	Search playbook/cass	`query, scope?, limit?, days?`
`memory_reflect`	Trigger reflection	`days?, maxSessions?, dryRun?`

Resources Exposed

URI	Purpose
`cm://playbook`	Current playbook state
`cm://diary`	Recent diary entries
`cm://outcomes`	Session outcomes
`cm://stats`	Playbook health metrics

Client Configuration

Claude Code (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "cm": {
      "command": "cm",
      "args": ["serve"]
    }
  }
}

Graceful Degradation

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

Output Format

All commands support --json for machine-readable output.

Design principle: stdout = JSON only; diagnostics go to stderr.

Success Response

{
  "success": true,
  "task": "fix the auth timeout bug",
  "relevantBullets": [
    {
      "id": "b-8f3a2c",
      "content": "Always check token expiry before auth debugging",
      "effectiveScore": 8.5,
      "maturity": "proven",
      "relevanceScore": 0.92,
      "reasoning": "Extracted from 5 successful sessions"
    }
  ],
  "antiPatterns": [...],
  "historySnippets": [...],
  "suggestedCassQueries": [...],
  "degraded": null
}

Error Response

{
  "success": false,
  "code": "PLAYBOOK_NOT_FOUND",
  "error": "Playbook file not found",
  "hint": "Run 'cm init' to create a new playbook",
  "retryable": false,
  "recovery": ["cm init", "cm doctor --fix"],
  "docs": "README.md#-troubleshooting"
}

Exit Codes

Code	Meaning
1	Internal error
2	User input/usage
3	Configuration
4	Filesystem
5	Network
6	cass error
7	LLM/provider error

Token Budget Management

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

Configuration

Config lives at ~/.cass-memory/config.json (global) and .cass/config.json (repo).

Precedence: CLI flags > Repo config > Global config > Defaults

Security: Repo config cannot override sensitive paths or user-level consent settings.

Key Options

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "budget": {
    "dailyLimit": 0.10,
    "monthlyLimit": 2.00
  },
  "scoring": {
    "decayHalfLifeDays": 90,
    "harmfulMultiplier": 4
  },
  "maxBulletsInContext": 50,
  "maxHistoryInContext": 10,
  "sessionLookbackDays": 7,
  "crossAgent": {
    "enabled": false,
    "consentGiven": false,
    "auditLog": true
  },
  "remoteCass": {
    "enabled": false,
    "hosts": [{"host": "workstation", "label": "work"}]
  },
  "semanticSearchEnabled": false,
  "embeddingModel": "Xenova/all-MiniLM-L6-v2",
  "dedupSimilarityThreshold": 0.85
}

Environment Variables

Variable	Purpose
`ANTHROPIC_API_KEY`	API key for Anthropic (Claude)
`OPENAI_API_KEY`	API key for OpenAI
`GOOGLE_GENERATIVE_AI_API_KEY`	API key for Google Gemini
`CASS_PATH`	Path to cass binary
`CASS_MEMORY_LLM`	Set to `none` for LLM-free mode
`MCP_HTTP_TOKEN`	Auth token for non-loopback MCP server

Data Locations

~/.cass-memory/                  # Global (user-level)
├── config.json                  # Configuration
├── playbook.yaml                # Personal playbook
├── diary/                       # Session summaries
├── outcomes/                    # Session outcomes
├── traumas.jsonl                # Trauma patterns
├── starters/                    # Custom starter playbooks
├── onboarding-state.json        # Onboarding progress
├── privacy-audit.jsonl          # Cross-agent audit trail
├── processed-sessions.jsonl     # Reflection progress
└── usage.jsonl                  # LLM cost tracking

.cass/                           # Project-level (in repo)
├── config.json                  # Project-specific overrides
├── playbook.yaml                # Project-specific rules
├── traumas.jsonl                # Project-specific patterns
└── blocked.yaml                 # Anti-patterns to block

Automating Reflection

Cron Job

# Daily at 2am
0 2 * * * /usr/local/bin/cm reflect --days 7 >> ~/.cass-memory/reflect.log 2>&1

Claude Code Hook

.claude/hooks.json:

{
  "post-session": ["cm reflect --days 1"]
}

Privacy & Security

Local-First Design

All data stays on your machine
No cloud sync, no telemetry
Cross-agent enrichment is opt-in with explicit consent
Audit log for enrichment events

Secret Sanitization

Before processing, content is sanitized:

OpenAI/Anthropic/AWS/Google API keys
GitHub tokens
JWTs
Passwords and secrets in config patterns

Privacy Controls

cm privacy status    # Check settings
cm privacy enable    # Enable cross-agent enrichment
cm privacy disable   # Disable enrichment

Performance Characteristics

Operation	Typical Latency
`cm context` (cached)	50-150ms
`cm context` (cold)	200-500ms
`cm context` (no cass)	30-80ms
`cm reflect` (1 session)	5-15s
`cm reflect` (5 sessions)	20-60s
`cm playbook list`	<50ms
`cm similar` (keyword)	20-50ms
`cm similar` (semantic)	100-300ms

LLM Cost Estimates

Operation	Typical Cost
Reflect (1 session)	$0.01-0.05
Reflect (7 days)	$0.05-0.20
Validate (1 rule)	$0.005-0.01

With default budget ($0.10/day, $2.00/month): ~5-10 sessions/day.

Batch Rule Addition

After analyzing a session, add multiple rules at once:

# Create JSON file
cat > rules.json << 'EOF'
[
  {"content": "Always run tests before committing", "category": "testing"},
  {"content": "Check token expiry before auth debugging", "category": "debugging"},
  {"content": "AVOID: Mocking entire modules in tests", "category": "testing"}
]
EOF

# Add all rules
cm playbook add --file rules.json

# Track which session they came from
cm playbook add --file rules.json --session /path/to/session.jsonl

# Or pipe from stdin
echo '[{"content": "Rule", "category": "workflow"}]' | cm playbook add --file -

Template Output for Onboarding

--template provides rich context for rule extraction:

cm onboard read /path/to/session.jsonl --template --json

Returns:

metadata: path, workspace, message count, topic hints
context: related rules, playbook gaps, suggested focus
extractionFormat: schema, categories, examples
sessionContent: actual session data

Integration with CASS

CASS provides episodic memory (raw sessions). CM extracts procedural memory (rules and playbooks).

# CASS: Search raw sessions
cass search "authentication timeout" --robot

# CM: Get distilled rules for a task
cm context "authentication timeout" --json

Troubleshooting

Error	Solution
`cass not found`	Install from cass repo
`cass search failed`	Run `cass index --full`
`API key missing`	Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_GENERATIVE_AI_API_KEY`
`Playbook corrupt`	Run `cm doctor --fix`
`Budget exceeded`	Check `cm usage`, adjust limits

Diagnostic Commands

cm doctor --json           # System health
cm doctor --fix            # Auto-fix issues
cm usage                   # LLM budget status
cm stats --json            # Playbook health
cm why <bullet-id>         # Rule provenance

LLM-Free Mode

CASS_MEMORY_LLM=none cm context "task" --json

Installation

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

# Specific version
install.sh --version v0.2.2 --verify

# System-wide
install.sh --system --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

Integration with Flywheel

Tool	Integration
CASS	CM reads from cass episodic memory, writes procedural memory
NTM	Robot mode integrates with cm for context before agent work
Agent Mail	Rules can reference mail threads as provenance
BV	Task context enriched with relevant playbook rules

Ask in your favorite AI

Documentation

CM - CASS Memory System

Why This Exists

Three-Layer Cognitive Architecture

The One Command You Need

Filtering History by Source

Confidence Decay System

Score Decay Visualization

Effective Score Formula

Maturity State Machine

Anti-Pattern Learning

ACE Pipeline (How Rules Are Created)

Scientific Validation

Commands Reference

Context Retrieval (Primary Workflow)

Playbook Management

Learning & Feedback

Onboarding (Agent-Native)

Trauma Guard (Safety System)

System Commands

Starter Playbooks

Built-in Starters

Custom Starters

Inline Feedback (During Work)

Agent Protocol

Gap Analysis Categories

Trauma Guard: Safety System

How It Works

Built-in Doom Patterns (20+)

Pattern Storage

Pattern Lifecycle

MCP Server

Tools Exposed

Resources Exposed

Client Configuration

Graceful Degradation

Output Format

Success Response

Error Response

Exit Codes

Token Budget Management

Configuration

Key Options

Environment Variables

Data Locations

Automating Reflection

Cron Job

Claude Code Hook

Privacy & Security

Local-First Design

Secret Sanitization

Privacy Controls

Performance Characteristics

LLM Cost Estimates

Batch Rule Addition

Template Output for Onboarding

Integration with CASS

Troubleshooting

Diagnostic Commands

LLM-Free Mode

Installation

Integration with Flywheel

Individual skills in this repo

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS

bg-szy/TOP-SKILLS