cm

CM - CASS Memory System

AI コーディングエージェント向けの手続き記憶です。散在するセッションを、エージェント間で共有できる永続的なメモリに変換します。人間の専門知識の発達を模した、3 層の認知アーキテクチャを採用しています。

これが必要な理由

AI コーディングエージェントは価値ある知識を蓄積しますが、その知識は次のような状態にあります。

• セッション内に閉じ込められる - セッション終了時にコンテキストが失われます
• エージェント固有 - Claude は Cursor が学んだことを知りません
• 構造化されていない - 生のログは実行可能なガイダンスになりません
• 崩壊しやすい - 単純な要約では重要な詳細が失われます

今月、異なるエージェントを使って認証のバグを 3 回解決したとします。そのたびに、最初からやり直していました。

CM はエージェント間の学習によってこれを解決します。Cursor で発見されたパターンは、すぐに Claude Code からも利用できます。

---

3 層の認知アーキテクチャ

┌─────────────────────────────────────────────────────────────────────┐
│                    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                │
└─────────────────────────────────────────────────────────────────────┘

すべてのエージェントのセッションが共有メモリに取り込まれます。Cursor で発見されたパターンは、次のセッションで Claude Code に自動的に役立ちます。

---

必要なコマンドは 1 つだけ

cm context "<your task>" --json

重要なタスクを始める前に実行してください。 次の情報が返されます。

• relevantBullets - タスクとの関連性に基づいてスコア付けされた、プレイブックのルール
• antiPatterns - 問題を引き起こした事柄
• historySnippets - 過去のセッション（自分および他のエージェントのもの）
• suggestedCassQueries - さらに詳しく調査するための検索クエリ

ソースで履歴を絞り込む

historySnippets[].origin.kind は "local" または "remote" です。リモートの検索結果には 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" }
    }
  ]
}

---

信頼度の減衰システム

ルールは永続するものではありません。再検証されないと信頼度が減衰します。

仕組み	効果
90 日の半減期	フィードバックがないと、90 日ごとに信頼度が半減します
有害度 4 倍の係数	1 回の失敗は 1 回の成功の 4 倍として数えられます
成熟度の進行	candidate → established → proven

スコア減衰の可視化

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

実効スコアの計算式

effectiveScore = decayedHelpful - (4 × decayedHarmful)

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

成熟度ステートマシン

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

遷移ルール：

遷移	条件
candidate → established	3 件以上の有用な評価、有害な評価の割合が 25% 未満
established → proven	10 件以上の有用な評価、有害な評価の割合が 10% 未満
any → deprecated	有害な評価の割合が 25% 超、または明示的な非推奨化

---

アンチパターンの学習

不適切なルールは削除されるだけではありません。警告になります。

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

ルールが有害と複数回判定されると（判定が 3 回以上あり、有害な評価の割合が 50% 超）、自動的に反転されてアンチパターンになります。

---

ACE パイプライン（ルールの作成方法）

Generator → Reflector → Validator → Curator

ステージ	役割	LLM？
Generator	タスク開始前のコンテキスト補完（cm context）	いいえ
Reflector	セッションからパターンを抽出（cm reflect）	はい
Validator	cass の履歴に照らしてエビデンスを確認	はい
Curator	決定論的な差分マージ	いいえ

重要： Curator は、反復的なドリフトによるコンテキスト崩壊を防ぐため、LLM を一切使用しません。LLM はパターンを提案し、決定論的なロジックがそれらを管理します。

科学的な検証

ルールがプレイブックに追加される前に、cass の履歴に照らして検証されます。

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

履歴上のエビデンスがないルールは、実証されるまで候補として扱われます。

---

コマンドリファレンス

コンテキストの取得（主なワークフロー）

# 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"

プレイブックの管理

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

学習とフィードバック

# 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"

オンボーディング（エージェントネイティブ）

既存のエージェントを使って、コストをかけずにプレイブックを作成できます。

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（安全システム）

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

システムコマンド

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

---

スタータープレイブック

空のプレイブックから始めるのは大変です。スターターには、厳選されたベストプラクティスが含まれています。

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

組み込みスターター

スターター	対象分野	ルール数
general	汎用的なベストプラクティス	5
typescript	TypeScript/Node.js のパターン	4
react	React/Next.js の開発	4
python	Python/FastAPI/Django	4
node	Node.js/Express のサービス	4
rust	Rust サービスのパターン	4

カスタムスターター

~/.cass-memory/starters/ に YAML ファイルを作成します。

# ~/.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]

---

作業中のインラインフィードバック

コードコメントにフィードバックを記述します。振り返りの際に解析されます。

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

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

---

エージェントプロトコル

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.

以下の作業は不要です：

• cm reflect を実行する（自動化によって処理されます）
• 手動で cm mark を実行する（インラインコメントを使用します）
• プレイブックにルールを手動で追加する

---

ギャップ分析のカテゴリ

カテゴリ	キーワード
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

カテゴリのステータスしきい値：

ステータス	ルール数	優先度
critical	0 ルール	高
underrepresented	1～2 ルール	中
adequate	3～10 ルール	低
well-covered	11 件以上	なし

---

トラウマガード：安全システム

「熱いコンロ」の原則です。過去のインシデントから学び、再発を防ぎます。

仕組み

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│
└─────────────────┘         └─────────────────┘         └─────────────────┘

組み込みの危険パターン（20 件以上）

カテゴリ	例
ファイルシステム	rm -rf /、rm -rf ~、再帰的な削除
データベース	DROP DATABASE、TRUNCATE、WHERE 句のない DELETE FROM
Git	main/master への git push --force、git reset --hard
インフラストラクチャ	terraform destroy -auto-approve、kubectl delete namespace
クラウド	aws s3 rm --recursive、破壊的な CloudFormation 操作

パターンの保存場所

スコープ	場所	目的
グローバル	~/.cass-memory/traumas.jsonl	個人用パターン
プロジェクト	.cass/traumas.jsonl	チーム用にリポジトリへコミット

パターンのライフサイクル

• 有効：一致するコマンドをブロックします
• 解除：一時的に回避されます（理由とタイムスタンプ付き）
• 削除済み：削除されます（再追加できます）

---

MCP サーバー

エージェント連携用の MCP サーバーとして実行します。

# 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

公開されるツール

ツール	目的	パラメーター
cm_context	ルールと履歴を取得	task, limit?, history?, days?, workspace?
cm_feedback	フィードバックを記録	bulletId, helpful?, harmful?, reason?
cm_outcome	セッションの結果を記録	sessionId, outcome, rulesUsed?
memory_search	プレイブック／cass を検索	query, scope?, limit?, days?
memory_reflect	振り返りを開始	days?, maxSessions?, dryRun?

公開されるリソース

URI	目的
cm://playbook	現在のプレイブックの状態
cm://diary	最近の日記エントリー
cm://outcomes	セッションの結果
cm://stats	プレイブックの健全性指標

クライアントの設定

Claude Code（~/.config/claude/mcp.json）：

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

---

グレースフルデグラデーション

条件	動作
cass がない	プレイブックのみでスコアを算出し、履歴の抜粋は表示しません
プレイブックがない	空のプレイブックを使用しますが、コマンドは引き続き動作します
LLM がない	決定論的な振り返りを行い、意味的な拡張は行いません
オフライン	キャッシュされたプレイブックとローカルの日記を使用します

---

出力形式

すべてのコマンドで、機械可読な出力を得るために --json を使用できます。

設計原則： stdout は JSON のみ、診断情報は stderr に出力します。

成功レスポンス

{
  "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
}

エラーレスポンス

{
  "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"
}

終了コード

コード	意味
1	内部エラー
2	ユーザー入力／使用方法
3	設定
4	ファイルシステム
5	ネットワーク
6	cass エラー
7	LLM／プロバイダーエラー

---

トークン予算の管理

フラグ	効果
--limit N	ルール数の上限を設定します
--min-score N	しきい値を超えるルールのみを対象にします
--no-history	履歴の抜粋を省略します（高速化）
--json	構造化出力

---

設定

設定は ~/.cass-memory/config.json（グローバル）と .cass/config.json（リポジトリ）にあります。

優先順位： CLI フラグ > リポジトリ設定 > グローバル設定 > デフォルト

セキュリティ： リポジトリ設定で、機密性の高いパスやユーザーレベルの同意設定を上書きすることはできません。

主なオプション

{
  "provider": "anthropic",
  "model": "claude-sonnet-5",
  "budget": {
    "dailyLimit": 1.00,
    "monthlyLimit": 20.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"}]
  },
  "embeddingModel": "Xenova/all-MiniLM-L6-v2",
  "dedupSimilarityThreshold": 0.85
}

semanticSearchEnabled は意図的に上記に含まれていません。これは三値の設定です。未設定（デフォルト）の場合、埋め込みバックエンドがオフラインですでに埋め込みを実行できるとき（ローカルモデルがキャッシュされている場合、または embeddingBackend: "ollama" が設定され、デーモンがモデルのダウンロード済み状態で応答する場合）はセマンティック検索を実行し、それ以外の場合はキーワード検索のみを実行します。どちらかに固定するには、true または false を設定してください。cm doctor は現在の状態を報告し、cm context --json は semanticError（失敗）または semanticNotice（バックエンドの準備がまだできていない）を使って、キーワード検索結果になった理由を説明します。

環境変数

変数	用途
ANTHROPIC_API_KEY	Anthropic（Claude）の API キー
OPENAI_API_KEY	OpenAI の API キー
GOOGLE_GENERATIVE_AI_API_KEY	Google Gemini の API キー
CASS_PATH	cass バイナリへのパス
CASS_MEMORY_LLM	LLM を使用しないモードにするには none を設定
MCP_HTTP_TOKEN	ループバック以外の MCP サーバー用認証トークン

---

データの保存場所

~/.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

---

振り返りの自動化

Cron ジョブ

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

Claude Code フック

.claude/hooks.json：

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

---

プライバシーとセキュリティ

ローカル優先の設計

• すべてのデータはお使いのマシンに保存されます
• クラウド同期やテレメトリーはありません
• エージェント間の情報拡充は、明示的な同意によるオプトインです
• 情報拡充イベントの監査ログを記録します

シークレットのサニタイズ

処理の前に、コンテンツをサニタイズします：

• OpenAI／Anthropic／AWS／Google の API キー
• GitHub トークン
• JWT
• 設定パターン内のパスワードとシークレット

プライバシー管理

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

---

パフォーマンス特性

操作	典型的なレイテンシ
cm context（キャッシュあり）	50-150ms
cm context（コールド）	200-500ms
cm context（cass なし）	30-80ms
cm reflect（1 セッション）	5-15s
cm reflect（5 セッション）	20-60s
cm playbook list	<50ms
cm similar（キーワード）	20-50ms
cm similar（セマンティック）	100-300ms

LLM のコスト見積もり

操作	典型的なコスト
Reflect（1 セッション）	$0.01-0.05
Reflect（7 日間）	$0.05-0.20
Validate（1 ルール）	$0.005-0.01

デフォルトの予算（$0.10/日、$2.00/月）では、1 日あたり約 5-10 セッションです。

---

ルールの一括追加

セッションを分析した後、複数のルールを一度に追加できます：

# 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 は、ルール抽出に役立つ豊富なコンテキストを提供します：

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

返される内容：

• metadata：パス、ワークスペース、メッセージ数、トピックのヒント
• context：関連ルール、プレイブックの不足項目、推奨される重点項目
• extractionFormat：スキーマ、カテゴリ、例
• sessionContent：実際のセッションデータ

---

CASS との統合

CASS はエピソード記憶（生のセッション）を提供します。 CM は手続き記憶（ルールとプレイブック）を抽出します。

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

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

---

トラブルシューティング

エラー	解決方法
cass not found	cass リポジトリからインストールします
cass search failed	cass index --full を実行します
API key missing	ANTHROPIC_API_KEY、OPENAI_API_KEY、または GOOGLE_GENERATIVE_AI_API_KEY を設定します
Playbook corrupt	cm doctor --fix を実行します
Budget exceeded	cm usage を確認し、上限を調整します

診断コマンド

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 を使用しないモード

CASS_MEMORY_LLM=none cm context "task" --json

---

インストール

# 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

---

Flywheel との統合

ツール	統合
CASS	CM は cass のエピソード記憶を読み込み、手続き記憶を書き込みます
NTM	ロボットモードはエージェント作業の前に、cm と統合してコンテキストを取得します
Agent Mail	ルールでは、出典としてメールスレッドを参照できます
BV	タスクのコンテキストを、関連するプレイブックのルールで充実させます