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 (CLI로 cm로 노출)는 AI 기반 코드 에이전트(Claude Code, Cursor, Codex, Aider, Gemini, ChatGPT 등)를 위한 크로스에이전트 지식 기반입니다. 어떤 에이전트에서든 생성된 원시 세션 로그를 수신하여 구조화된 일기 항목으로 변환하고, 새로운 작업 전에 질의할 수 있는 절차적 규칙(플레이북 항목)으로 정제합니다. 시스템은 인간의 기억 계층(에피소딕, 워킹, 절차적)을 모방하며, 시간이 지남에 따라 감소하는 신뢰도 점수를 유지합니다.

핵심 개념

계층	목적	구현
에피소딕 기억	모든 코드 에이전트의 원시 세션 로그	로컬 `cass` 검색 엔진에 저장
워킹 기억	각 세션의 구조화된 요약(무엇이 수행되었는지, 결정사항, 결과)	자동 생성되는 "일기" 항목
절차적 기억	신뢰도 추적, 악성 패턴, 성숙도 수준이 있는 실행 가능한 규칙	에이전트가 질의하는 "플레이북"(YAML/JSON)

주요 기능 (README에 기술됨)

크로스에이전트 학습 – 지원되는 어떤 에이전트의 세션도 자동으로 공유 플레이북을 풍부하게 합니다.
신뢰도 감소 – 규칙은 90일간 비활성 상태가 되면 신뢰도가 감소합니다; 해로운 피드백은 유익한 피드백보다 4배 더 큰 가중치를 가집니다; 성숙도는 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을 통해 설치 가능.
리포지토리는 알파로 표시되어 있으며, 자주 변경될 수 있습니다.

일반적인 워크플로우 (에이전트 중심)

# 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 쿼리.

제한 사항 및 현재 상태

알파 단계 – 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를 갖추고 있습니다.