CM - CASS 記憶系統
為 AI 編碼代理提供程序性記憶。將分散的工作階段轉化為持久、跨代理的記憶。採用三層認知架構,模擬人類專業技能的發展過程。
為何存在
AI 編碼代理積累了寶貴的知識,但這些知識往往:
- 被困在工作階段中 — 工作階段結束後上下文即遺失
- 僅限單一代理 — Claude 不知道 Cursor 學到了什麼
- 缺乏結構化 — 原始日誌無法作為可操作指南
- 面臨崩塌風險 — 單純摘要會遺失關鍵細節
一個月內,您可能已在不同代理中解決了三次同樣的認證錯誤,每次都從頭開始。
CM 透過跨代理學習解決此問題:在 Cursor 中發現的模式,可立即供 Claude Code 使用。
三層認知架構
┌─────────────────────────────────────────────────────────────────────┐
│ 情節記憶 (cass) │
│ 來自所有代理的原始工作階段日誌 — 即「基本事實」 │
│ Claude Code │ Codex │ Cursor │ Aider │ PI │ Gemini │ ChatGPT │ ...│
└───────────────────────────┬─────────────────────────────────────────┘
│ cass search
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 工作記憶 (Diary) │
│ 結構化的工作階段摘要:成就、決策等 │
└───────────────────────────┬─────────────────────────────────────────┘
│ reflect + curate (自動化)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 程序性記憶 (Playbook) │
│ 經提煉的規則,附帶信心追蹤與衰減機制 │
└─────────────────────────────────────────────────────────────────────┘
每個代理的工作階段都會餵養共享記憶。在 Cursor 中發現的模式會自動在下次工作階段中幫助 Claude Code。
你只需要一個指令
cm context "<你的任務>" --json
在開始任何非瑣碎任務前執行此指令。 會回傳:
- relevantBullets — 根據任務相關性評分的 Playbook 規則
- 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 倍乘數 | 一次錯誤的影響等同於四次成功 |
| 成熟度進展 | candidate → established → proven |
分數衰減可視化
初始分數:10.0 (今天有 10 次幫助標記)
90 天後 (半衰期): 5.0
180 天後: 2.5
270 天後: 1.25
365 天後: 0.78
有效分數公式
effectiveScore = decayedHelpful - (4 × decayedHarmful)
// 其中衰減因子 = 0.5 ^ (daysSinceFeedback / 90)
成熟度狀態機
┌──────────┐ ┌─────────────┐ ┌────────┐
│ candidate│──────▶│ established │───▶│ proven │
└──────────┘ └─────────────┘ └────────┘
│ │ │
│ │ (harmful >25%) │
│ ▼ │
│ ┌─────────────┐ │
└────────────▶│ deprecated │◀─────────┘
└─────────────┘
轉換規則:
| 轉換 | 條件 |
|---|---|
candidate → established | 3+ 次幫助,有害比率 <25% |
established → proven | 10+ 次幫助,有害比率 <10% |
any → deprecated | 有害比率 >25% 或明確棄用 |
反模式學習
不好的規則不只是被刪除,它們會變成警告:
"快取認證令牌以提升效能"
↓ (3 次有害標記)
"陷阱:不要快取未經驗證有效期的認證令牌"
當一個規則被多次標記為有害(>50% 有害比率且 3+ 次標記),它會自動轉化為反模式。
ACE 管線 (規則的創建方式)
Generator → Reflector → Validator → Curator
| 階段 | 角色 | 使用 LLM? |
|---|---|---|
| Generator | 任務前上下文注入 (cm context) | 否 |
| Reflector | 從工作階段中提取模式 (cm reflect) | 是 |
| Validator | 對照 cass 歷史的證據關卡 | 是 |
| Curator | 確定性差異合併 | 否 |
關鍵: Curator 不使用 LLM,以防止因迭代漂移導致的上下文崩塌。LLM 提出模式;確定性邏輯負責管理它們。
科學驗證
在規則加入你的 Playbook 之前,它會經過 cass 歷史的驗證:
提議規則:"在進行認證除錯前,務必檢查令牌有效期"
↓
證據關卡:搜尋 cass 中此規則適用的工作階段
↓
結果:找到 5 個工作階段,4 次成功結果 → 接受
沒有歷史證據的規則會被標記為候選,直到被證明為止。
指令參考
上下文檢索 (主要工作流程)
# 主要指令 - 在非瑣碎任務前執行
cm context "實作使用者認證" --json
# 限制結果以節省 token 預算
cm context "修復錯誤" --json --limit 5 --no-history
# 搭配工作區過濾
cm context "重構" --json --workspace /path/to/project
# 自我說明
cm quickstart --json
# 系統健康檢查
cm doctor --json
cm doctor --fix # 自動修復問題
# 尋找相似規則
cm similar "錯誤處理最佳實踐"
Playbook 管理
cm playbook list # 所有規則
cm playbook get b-8f3a2c # 規則詳情
cm playbook add "永遠先執行測試" # 新增規則
cm playbook add --file rules.json # 從檔案批次新增
cm playbook add --file rules.json --session /path/session.jsonl # 追蹤來源
cm playbook remove b-xyz --reason "已過時" # 刪除
cm playbook export > backup.yaml # 匯出
cm playbook import shared.yaml # 匯入
cm playbook bootstrap react # 將入門套用至現有 Playbook
cm top 10 # 最有效的規則
cm stale --days 60 # 近期無回饋的規則
cm why b-8f3a2c # 規則來源
cm stats --json # Playbook 健康指標
學習與回饋
# 手動回饋
cm mark b-8f3a2c --helpful
cm mark b-xyz789 --harmful --reason "造成回歸"
cm undo b-xyz789 # 復原回饋
# 工作階段結果 (位置參數:狀態,規則)
cm outcome success b-8f3a2c,b-def456
cm outcome failure b-x7k9p1 --summary "認證方法失敗"
cm outcome-apply # 套用至 Playbook
# 反思 (通常為自動化)
cm reflect --days 7 --json
cm reflect --session /path/to/session.jsonl # 單一工作階段
cm reflect --workspace /path/to/project # 特定專案
# 驗證
cm validate "在取值前務必檢查 null"
# 審計工作階段與規則的比對情況
cm audit --days 30
# 永久棄用
cm forget b-xyz789 --reason "已被更好的模式取代"
入門引導 (代理原生)
使用你現有的代理以零成本建立 Playbook:
cm onboard status # 檢查進度
cm onboard gaps # 類別缺口
cm onboard sample --fill-gaps # 優先處理的工作階段
cm onboard sample --agent claude --days 14 # 按代理/時間過濾
cm onboard sample --workspace /path/project # 按工作區過濾
cm onboard sample --include-processed # 重新分析工作階段
cm onboard read /path/session.jsonl --template # 豐富上下文
cm onboard mark-done /path/session.jsonl # 標記為已處理
cm onboard reset # 重新開始
創傷防護 (安全系統)
cm trauma list # 活躍模式
cm trauma add "DROP TABLE" --description "大量刪除" --severity critical
cm trauma heal t-abc --reason "有意的遷移"
cm trauma remove t-abc
cm trauma scan --days 30 # 掃描創傷
cm trauma import shared-traumas.yaml
cm guard --install # Claude Code 鉤子
cm guard --git # Git pre-commit 鉤子
cm guard --install --git # 兩者
cm guard --status # 檢查安裝狀態
系統指令
cm init # 初始化
cm init --starter typescript # 使用範本
cm init --force # 重新初始化 (建立備份)
cm starters # 列出範本
cm serve --port 3001 # MCP 伺服器
cm usage # LLM 成本統計
cm privacy status # 隱私設定
cm privacy enable # 啟用跨代理知識增強
cm privacy disable # 停用知識增強
cm project --format agents.md # 匯出至 AGENTS.md
入門 Playbook
從空的 Playbook 開始可能令人却步。入門套件提供了精選的最佳實踐:
cm starters # 列出可用的
cm init --starter typescript # 使用入門套件初始化
cm playbook bootstrap react # 套用至現有 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 網頁框架最佳實踐
bullets:
- content: "始終使用 Django 的 ORM 進行資料庫操作"
category: database
maturity: established
tags: [django, orm]
內聯回饋 (工作期間)
在程式碼註解中留下回饋。反思時會解析:
// [cass: helpful b-8f3a2c] - 這條規則讓我免於陷入死胡同
// [cass: harmful b-x7k9p1] - 這個建議不適合我們的用例
代理協定
1. 開始: cm context "<任務>" --json
2. 工作: 遵循規則時引用其 ID (例如「遵循 b-8f3a2c...」)
3. 回饋: 當規則有幫助或造成傷害時,留下內聯註解
4. 結束: 直接完成即可。學習會自動進行。
你不需要:
- 執行
cm reflect(自動化會處理) - 手動執行
cm mark(使用內聯註解) - 手動新增規則至 Playbook
缺口分析類別
| 類別 | 關鍵字 |
|---|---|
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+ 條規則 | 無 |
創傷防護:安全系統
「熱爐灶」原則 — 從過往事件中學習並防止再次發生。
運作方式
工作階段歷史 創傷註冊表 執行時防護
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ rm -rf /* (哎唷) │ ──────▶ │ 模式:rm -rf │ ──────▶ │ 已封鎖:此指令 │
│ 「抱歉,我犯了 │ scan │ 嚴重度:致命 │ hook │ 符合創傷模式 │
│ 一個錯誤...」 │ │ 工作階段:abc123 │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
內建災難模式 (20+)
| 類別 | 範例 |
|---|---|
| 檔案系統 | rm -rf /, rm -rf ~, 遞迴刪除 |
| 資料庫 | DROP DATABASE, TRUNCATE, DELETE FROM 沒有 WHERE |
| Git | git push --force 到 main/master, git reset --hard |
| 基礎設施 | terraform destroy -auto-approve, kubectl delete namespace |
| 雲端 | aws s3 rm --recursive, 具破壞性的 CloudFormation |
模式儲存
| 範圍 | 位置 | 用途 |
|---|---|---|
| 全域 | ~/.cass-memory/traumas.jsonl | 個人模式 |
| 專案 | .cass/traumas.jsonl | 提交至儲存庫供團隊使用 |
模式生命週期
- 活躍: 封鎖匹配的指令
- 已痊癒: 暫時繞過 (帶有原因和時間戳)
- 已刪除: 移除 (可重新新增)
MCP 伺服器
作為 MCP 伺服器執行以整合代理:
# 僅限本機 (建議)
cm serve --port 3001
# 使用認證令牌 (用於非迴路介面)
MCP_HTTP_TOKEN="<random>" cm serve --host 0.0.0.0 --port 3001
公開的工具
| 工具
…
[因翻譯需求而截斷]