ralph-mem CLAUDE.md

ralph-mem

Claude Code를 위한 Ralph Loop 기반 지속적 컨텍스트 관리 플러그인

프로젝트 개요

ralph-mem은 Ralph Loop의 "성공할 때까지 반복" 철학과 지능적 컨텍스트 관리를 결합한 Claude Code 플러그인입니다.

해결하는 문제:

• Context Rot: 누적된 불필요한 정보로 인한 모델 성능 저하
• Compaction: context window 60-70% 초과 시 출력 품질 급락
• Forgetfulness: 세션 간 작업 맥락 손실
• One-shot 실패: 복잡한 작업에서 단일 시도 성공률 저조

기술 스택

항목	기술
Runtime	Bun
Language	TypeScript (ES2022, strict mode)
Database	SQLite + FTS5
Testing	Vitest
Linting	Biome

프로젝트 구조

ralph-mem/
├── src/
│   ├── index.ts           # 플러그인 엔트리포인트
│   ├── core/              # Core Layer
│   │   ├── db/            # SQLite 클라이언트
│   │   ├── store.ts       # MemoryStore 인터페이스
│   │   └── search.ts      # SearchEngine 인터페이스
│   ├── hooks/             # Lifecycle hooks
│   ├── features/ralph/    # Ralph Loop 엔진
│   ├── skills/            # Slash commands
│   └── utils/             # 유틸리티
├── tests/                 # Vitest 테스트
├── docs/
│   ├── design/            # 설계 문서
│   └── issues/            # 구현 태스크 (폴더별 관리)
│       ├── 001-project-setup/
│       │   ├── README.md      # 이슈 내용
│       │   └── evidence.md    # 완료 검증 증거
│       ├── 002-plugin-manifest/
│       │   └── README.md
│       └── ...
└── .claude/               # Claude Code 설정
    ├── hooks/             # UserPromptSubmit hook
    └── commands/          # Custom skills

아키텍처

3계층 아키텍처로 구성:

1. Core Layer (src/core/)

   • MemoryStore: 세션/관찰 관리
   • SearchEngine: FTS5 전문 검색
   • SQLite 스토리지

2. Hook Layer (src/hooks/)

   • SessionStart: 관련 메모리 자동 주입
   • SessionEnd: 세션 요약 생성 및 저장
   • PostToolUse: 도구 사용 결과 기록
   • UserPromptSubmit: 컨텍스트 자동 주입

3. Feature Layer (src/features/ralph/)

   • Loop Engine: 성공까지 반복 실행
   • Success Criteria: 성공 기준 평가
   • Overbaking Prevention: 과도한 반복 방지

주요 개념

Progressive Disclosure (3계층 검색)

토큰 효율적인 메모리 검색:

Layer	내용	토큰
Layer 1	Index (ID + 점수)	50-100/result
Layer 2	Timeline (시간순 컨텍스트)	200-300/result
Layer 3	Full Details	500-1000/result