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。