Dicklesworthstone/cass_memory_system

Procedural memory for AI coding agents: transforms scattered session history into persistent, cross-agent memory so every agent learns from every other

cass‑memory (cm) – AI 程式碼代理的程序性記憶

一鍵安裝 (Linux/macOS) ：

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/cass_memory_system/main/install.sh?$(date +%s)" \
  | bash -s -- --easy-mode --verify

或透過 Homebrew (brew install dicklesworthstone/tap/cm) / Scoop (scoop install dicklesworthstone/cm) 安裝。

是什麼

cass‑memory（以 cm CLI 形式公開）是針對 AI 驅動的程式碼代理（Claude Code、Cursor、Codex、Aider、Gemini、ChatGPT 等）的 跨代理知識庫。它接收來自任何代理的原始會話日誌，轉換為結構化的日記項目，再精煉出可查詢的 程序性規則（劇本要點），供新任務前使用。該系統模擬人類記憶層次——情節記憶（原始日誌）、工作記憶（摘要）、程序性記憶（規則），並保持隨時間衰減的信賴度分數。

核心概念

層級	目的	實作
情節記憶	所有程式碼代理的原始會話日誌	存放在本地 `cass` 搜尋引擎中
工作記憶	每個會話的結構化摘要（做了什麼、決策、結果）	自動產生的「日記」項目
程序性記憶	帶信賴度追蹤、反模式、成熟度級別的可執行規則	代理查詢的「劇本」（YAML/JSON）

主要功能（如 README 所述）

跨代理學習 – 任何支援代理的會話都會自動豐富共享劇本。
信賴度衰減 – 規則在 90 天無活動後信賴度下降；有害回饋的權重是有效回饋的四倍；成熟度從 candidate → established → proven 逐步提升。
反模式學習 – 反覆有害的規則會被反轉為警告。
科學驗證 – 規則只有在過往會話證據支持後才會被提升至劇本中。
優雅降級 – 若搜尋引擎、劇本或 LLM 組件遺失，CLI 仍可運作；會回退到確定性行為。
機器可讀 JSON 輸出 – 所有命令支援 --json；stdout 為純資料，診斷資訊輸出至 stderr，便於代理解析。
內嵌回饋語法 – 代理可在程式碼中加入 // [cass: helpful <id>] 或 // [cass: harmful <id>] 注解；系統在反思時解析這些註解。
結果記錄 – 任務完成後，代理可呼叫 cm outcome success|failure <rule‑ids> --summary "…" 更新規則信賴度。
令牌預算控制 – --limit、--min-score、--no-history 等旗標可讓代理保持回應足夠小，以適應 LLM 上下文視窗。
代理原生上手流程 – cm onboard 工作流程允許現有程式碼代理分析歷史會話並提取規則，無需額外 LLM 成本。
差距分析 – 系統追蹤規則在各類別（除錯、測試、安全等）中的覆蓋率，並建議填補不足的會話。

目標使用者

需要在任務開始前快速獲得相關指導的 AI 程式碼代理。
希望在工具和機器間擁有持久、可搜尋的機構記憶的開發者。
使用多個 AI 助手並希望自動共享學習模式的團隊。
依賴規則建議建構自訂工作流程的高階使用者。

安裝與需求

平台：Linux、macOS、Windows。
執行環境：專為 Bun JavaScript 執行環境設計（由徽章所示）。
透過一鍵指令碼、Homebrew 或 Scoop 安裝。
倉儲標記為 alpha；請預期頻繁變更。

典型工作流程（代理導向）

# 1️⃣ 為新任務取得相關記憶
cm context "implement auth rate limiting" --json

# 2️⃣（可選）查看快速自解說
cm quickstart --json

# 3️⃣ 上手歷史會話以擴展劇本
cm onboard status               # 顯示進度
cm onboard sample --fill-gaps   # 取得填補規則缺口的會話
cm onboard read /path/to/session.jsonl --template --json
cm playbook add "Always check token expiry before auth debugging" --category debugging
cm onboard mark-done /path/to/session.jsonl

# 4️⃣ 任務完成後記錄結果
cm outcome success b-8f3a2c --summary "Fixed auth bug"
cm outcome-apply                # 應用信賴度更新

cm context 命令返回包含以下內容的 JSON 物件：

relevantBullets（帶分數和成熟度的規則）
antiPatterns
historySnippets（過去會話的原始摘錄）
深入挖掘的建議 cass 查詢。

限制與目前狀態

Alpha 階段 – API 和資料格式可能變更。
依賴本地 cass 搜尋引擎；若遺失，系統仍可運作，但無法提供歷史摘錄。
無內建 LLM；語意增強為可選，LLM 不可用時為確定性行為。
信賴度衰減與驗證基於規則啟發式；可能需針對特定團隊調整。
需要 Bun 執行環境；非標準 Node.js 環境。

授權

MIT（徽章所示）。

快速參考（JSON 輸出範例）

{
  "success": true,
  "task": "fix the auth timeout bug",
  "relevantBullets": [{
    "id": "b-8f3a2c",
    "content": "Always check token expiry before other auth debugging",
    "effectiveScore": 8.5,
    "maturity": "proven",
    "relevanceScore": 0.92,
    "reasoning": "Extracted from 5 successful sessions"
  }],
  "antiPatterns": [{
    "id": "b-x7k9p1",
    "content": "Don't cache auth tokens without expiry validation",
    "effectiveScore": 3.2
  }],
  "historySnippets": [{
    "source_path": "~/.claude/sessions/session-001.jsonl",
    "agent": "claude",
    "origin": {"kind": "local"},
    "snippet": "Fixed timeout by increasing token refresh interval...",
    "score": 0.87
  }],
  "suggestedCassQueries": ["cass search 'authentication timeout' --robot --days 30"],
  "degraded": null
}

結論：cass‑memory 提供一個結構化、可搜尋、自我更新的知識庫，使 AI 程式碼代理能將彼此的經驗作為程序性規則重複使用，內建信賴度追蹤、反模式處理與完全機器可讀的 CLI。