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) – Procedural memory for AI coding agents

One‑liner install (Linux/macOS) :

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

Or via Homebrew (brew install dicklesworthstone/tap/cm) / Scoop (scoop install dicklesworthstone/cm).

What it is

cass‑memory (exposed as the cm CLI) is a cross‑agent knowledge‑base for AI‑powered coding assistants (Claude Code, Cursor, Codex, Aider, Gemini, ChatGPT, etc.). It ingests raw session logs from any agent, turns them into structured diary entries, and then distills procedural rules (playbook bullets) that can be queried before a new task. The system mimics human memory layers – episodic (raw logs), working (summaries), procedural (rules) – and keeps confidence scores that decay over time.

Core concepts

Layer	Purpose	Implementation
Episodic Memory	All raw session logs from every coding agent	Stored in a local `cass` search engine
Working Memory	Structured summaries of each session (what was done, decisions, outcomes)	“Diary” entries generated automatically
Procedural Memory	Actionable rules with confidence tracking, anti‑patterns, maturity levels	“Playbook” (YAML/JSON) that agents query

Key features (as described in the README)

Cross‑agent learning – sessions from any supported agent automatically enrich a shared playbook.
Confidence decay – rules lose confidence after 90 days of inactivity; harmful feedback counts four times more than helpful feedback; maturity progresses candidate → established → proven.
Anti‑pattern learning – repeatedly harmful rules are inverted into warnings.
Scientific validation – a rule is only promoted to the playbook after evidence from past sessions supports it.
Graceful degradation – the CLI still works if the search engine, playbook, or LLM component is missing; it falls back to deterministic behavior.
Machine‑readable JSON output – all commands support --json; stdout is pure data, diagnostics go to stderr, making it easy for agents to parse.
Inline feedback syntax – agents can annotate code with // [cass: helpful <id>] or // [cass: harmful <id>]; the system parses these comments during reflection.
Outcome recording – after a task, agents can call cm outcome success|failure <rule‑ids> --summary "…" to update rule confidence.
Token‑budget controls – flags like --limit, --min-score, --no-history let agents keep responses small enough for LLM context windows.
Agent‑native onboarding – the cm onboard workflow lets an existing coding agent analyze historic sessions and extract rules without extra LLM costs.
Gap analysis – the system tracks rule coverage across categories (debugging, testing, security, etc.) and suggests sessions that fill under‑represented gaps.

Intended users

AI coding agents that need quick, relevant guidance before starting a task.
Developers who want a persistent, searchable institutional memory across tools and machines.
Teams that use multiple AI assistants and wish to share learned patterns automatically.
Power users building custom workflows that rely on rule‑based suggestions.

Installation & requirements

Platform: Linux, macOS, Windows.
Runtime: Built for the Bun JavaScript runtime (as indicated by the badge).
Install via the one‑liner script, Homebrew, or Scoop.
The repository is marked alpha; expect frequent changes.

Typical workflow (agent‑focused)

# 1️⃣ Pull relevant memory for a new task
cm context "implement auth rate limiting" --json

# 2️⃣ (Optional) See a quick self‑explanation
cm quickstart --json

# 3️⃣ Onboard historic sessions to grow the playbook
cm onboard status               # show progress
cm onboard sample --fill-gaps   # get sessions that fill rule 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️⃣ After finishing, record outcome
cm outcome success b-8f3a2c --summary "Fixed auth bug"
cm outcome-apply                # apply confidence updates

The cm context command returns a JSON object containing:

relevantBullets (rules with scores and maturity)
antiPatterns
historySnippets (raw excerpts from past sessions)
suggested cass queries for deeper digging.

Limitations & current status

Alpha stage – API and data formats may change.
Relies on a local cass search engine; if it is missing the system still works but without historical snippets.
No built‑in LLM; semantic enrichment is optional and deterministic when an LLM is unavailable.
Confidence decay and validation are rule‑based heuristics; they may need tuning for specific teams.
Requires the Bun runtime; not a standard Node.js environment.

License

MIT (as shown by the badge).

Quick reference (JSON output example)

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

Bottom line: cass‑memory provides a structured, searchable, and self‑updating knowledge base that lets AI coding agents reuse each other's experience as procedural rules, with built‑in confidence tracking, anti‑pattern handling, and a fully machine‑readable CLI.