Sleep — 자가학습 메모리 그래프 + 자동 정리
Claude Code 프로젝트별 auto memory 디렉토리를 전수 스캔하고, kb_facts 지식 그래프(SQLite + Ollama 임베딩)로 시맨틱 메모리를 구축합니다. Claude·Codex가 동일한 5개 MCP 툴로 공유. 2시간마다 자동 tick + 매일 자동 dream으로 상시 운영되며, 모든 변경이력이 GitHub Pages에 라이브 게시됩니다.
개요
Claude Code는 각 프로젝트마다 ~/.claude/projects/<cwd>/memory/에 자동 메모리를 저장합니다. 시간이 쌓이면 중복, 오래된 정보, 파편화된 내용이 축적되는데, Sleep이 이를 주기적으로 정리합니다.
Before sleep:
memory/project_session_20260412.md (62 lines)
memory/project_session_20260408.md (70 lines)
memory/feedback_ci_check.md (동일 내용)
memory/feedback_ci_after_push.md (거의 동일)
MEMORY.md (1,333 lines, 많은 링크 깨짐)
After sleep (dream):
memory/project_session_20260412.md (5 lines, 요약본)
memory/project_session_20260408.md (6 lines)
feedback_ci_check.md 삭제
feedback_ci_after_push.md (통합 버전)
MEMORY.md (1,166 lines, 링크 전수 검증)⚡ 자동 루프 (Always-on)
Sleep은 더 이상 "dream" 한 마디가 있어야만 발동되지 않습니다. 두 개의 LaunchAgent가 백그라운드에서 항상 돌고 있습니다.
| 트리거 | 주기 | 하는 일 | LLM 사용 |
|---|---|---|---|
| com.comad.kb-sleep | 매 2시간 | .md → kb_facts 추출 (idempotent) · embedding 갱신 · rule-based consolidation · 변경이력 게시·push | ❌ 무필요 (rule-only) |
| com.comad.auto-dream | 매일 03:15 KST | dream_pending 플래그 확인 → comad-sleep 에이전트 자동 호출 (.md 본격 압축) | ✅ Claude (mutex 가드 포함) |
| SessionStart hook | 세션 시작 시 | dream_pending=true이면 적극 알림 ("🌙 정리 권장") | — |
임계 조건: .md 총 라인 ≥ 3,500 또는 마지막 dream 후 7일 경과 시 dream_pending=true. 두 LaunchAgent가 협력해서 사용자 명시 호출 없이도 메모리가 비대해지지 않게 유지합니다.
📊 kb_facts 지식 그래프
메모리 본문(~/.claude/.comad/memory/facts.sqlite)에 5개 kb_* 테이블로 저장되는 시맨틱 그래프. memory-bank 패턴을 zero external dependency로 내제화한 것이 핵심입니다.
| 테이블 | 역할 |
|---|---|
kb_facts | 원자적 fact (kind=decision/preference/pattern/knowledge/constraint) |
kb_relations | 엣지 6종 (INFLUENCES / SUPPORTS / SUPERSEDES / CONTRADICTS / REFINES / RELATED) |
kb_ontology | Domain → Category 분류 (frontend, devops, memory 등) |
kb_embeddings | Ollama nomic-embed-text (768d float32 BLOB) — 시맨틱 검색용 |
kb_provenance | 출처 추적 (transcript / commit / mdfile / manual) |
파이프라인 (모두 stdlib 외 deps 없음 · 로컬 Ollama만 사용):
~/.claude/skills/comad-memory/bin/
extract-facts.py # .md / transcript / stdin → kb_facts (regex / LLM)
embed.py # 새 fact만 incremental embedding (nomic-embed-text)
consolidate.py # DUPLICATE/CONTRADICTION/EVOLUTION 자동 판정 (선택: --llm)
semantic-search.py # 자연어 → cosine 유사도 → top-K facts
traverse.py # 멀티홉 BFS (1-N hops) 그래프 탐색
kb-trace.py # fact_id → 본문 + provenance + 엣지
kb-stats.py # 그래프 헬스 (kind / scope / domain / relation 분포)
kb-cross-scope.py # 도메인이 여러 scope 걸치는 facts (cross-project insights)MEMORY.md 인덱스
자동 메모리는 4가지로 분류됩니다. Sleep은 유형별로 다른 정리 정책을 적용합니다.
| 유형 | 내용 | 정리 정책 |
|---|---|---|
| user | 사용자의 역할, 선호, 지식 수준 | 거의 변하지 않음. 중복만 제거 |
| feedback | 사용자가 준 피드백 (하지 마/계속 이렇게 해) | 유사 항목 통합, 왜 & 언제 적용 명시 |
| project | 진행 중인 작업, 목표, 데드라인, 기술 결정 | 시간 지난 세션 요약 압축, 최근 3-5개만 상세 유지 |
| reference | 외부 시스템 포인터 (Linear 프로젝트 URL 등) | 링크 깨짐 확인, 중복 제거 |
dream 실행
아무 Claude Code 세션에서 "dream" 또는 "정리해줘" 등 트리거 문구를 입력하면 comad-sleep 에이전트가 발동됩니다.
You: dream
Claude (comad-sleep):
ComadSleep Report — 2026-04-13T03:13Z
Scanned: 6 projects, 47 files
Backup: ~/.claude/memory-backup-2026-04-13T031330
Stale locks removed: 3
Changes (13):
· project_improvement_status.md 58줄 → 44줄 (현행화)
· project_session_20260412.md 62줄 → 5줄 (04-13이 후속 세션이라 압축)
· feedback_ci_check.md 삭제 (ci_after_push와 중복)
· feedback_ci_after_push.md CI 정책 통합본으로 재작성
· reference_neo4j_shared.md eye 포트 7688→7687 (PR #1 반영)
· ... (8건 더)
결과:
주요 프로젝트 메모리: 693줄 → 533줄 (-23%)
전체 메모리: 47 files, 1,166줄
22개 MEMORY.md 링크 전수 검증: 전부 OK~/.claude/memory-backup-<timestamp>/에 복사됩니다. 잘못된 병합으로 정보가 사라지면 언제든 복원.
MEMORY.md 인덱스
각 프로젝트의 memory/MEMORY.md는 세부 메모리 파일들을 한 줄 요약으로 엮은 인덱스입니다. Sleep이 항상 이 인덱스의 일관성을 유지합니다.
# memory/MEMORY.md
- [Session 2026-04-13](project_session_20260413.md) — GraphRAG recall 93%, 크론 OAuth 해결, LaunchAgent 마이그레이션
- [Session 2026-04-12](project_session_20260412.md) — 자가진화 6 Phase, 스코어 84/100
- [Pending tasks](project_pending_tasks.md) — meta-edge 분할 · 50K 그래프 성장
- [/search skill](project_search_skill_plan.md) — 멀티소스 + Neo4j 저장 + 주간 CRON 구현 완료
- [Design simplicity](feedback_design_simplicity.md) — Karpathy 기준 심플리시티 선호
- ...MCP 서버 — Claude·Codex 공용 7툴
comad-brain MCP 서버에 통합 등록되어 Claude(claude/ccc/ccd)와 Codex(cdx)가 동일한 툴로 같은 SQLite 메모리에 접근합니다. 코드는 단일 SoT(01-comad/comad-world/brain) — 한 군데 수정하면 양쪽 즉시 반영.
📊 kb_facts 그래프 도구 (5개)
| 도구 | 용도 |
|---|---|
comad_kb_search | 자연어 시맨틱 검색 (Ollama 임베딩 → cosine 유사도) |
comad_kb_trace | fact_id → 본문 + provenance + 엣지 + ontology |
comad_kb_explore | BFS 멀티홉 그래프 탐색 (relation 타입 필터) |
comad_kb_cross_scope | 한 도메인이 여러 프로젝트(scope)에 걸친 패턴 발견 |
comad_kb_stats | 그래프 헬스 (active/archived facts, 임베딩 커버리지, relation 분포) |
📁 dream 이력 도구 (2개, 기존)
| 도구 | 용도 |
|---|---|
comad_sleep_info | 마지막 dream 실행 시각, 다음 권장 실행 일정 |
comad_sleep_history | 최근 N회의 dream 리포트 (무엇이 바뀌었나) |
📰 변경이력 라이브 게시
매 2시간 tick 마다 메타정보(파일/카운트/엣지/임계치)가 GitHub Pages에 자동 게시됩니다. 본문은 비공개 — 사용자 정보, API 키, 프로젝트 디테일은 노출되지 않고, 시스템이 정상 작동하는지를 외부에서 검증할 수 있는 메타 통계만 게시.
/memory-log/YYYY-MM-DD/
# 게시되는 정보 (예시)
## 2026-05-04 03:14 KST (tick #5)
**KB 변화**
| 항목 | 이전 | 이후 | Δ |
| active facts | 94 | 98 | +4 |
| relations | 5 | 8 | +3 |
| embeddings | 94 | 98 | +4 |
**워커 단계**
- extract: +4 new (87 idempotent skip, 0 fail)
- embed: 4 embedded — ok
- consolidate: 3 candidates (5 buckets)
**메모리 임계치**
- .md 총 라인: 3,761 / threshold 3,500 → 🌙 dream pending
- 마지막 dream: 4.4일 전 / threshold 7일git push는 stash → pull --rebase --autostash → add → commit → push 순서로 진행되며, 충돌 시 abort 후 다음 tick에 재시도. KB_SLEEP_NO_PUSH=1 환경변수로 push만 비활성화 가능.
정리 정책
Sleep이 자동으로 판단하는 규칙들:
무엇을 저장하지 말 것 (중복되는 기억)
- 코드 패턴/컨벤션/아키텍처 —
git log/소스가 진실 - 디버깅 해결책 — 커밋 메시지에 이미 있음
- 현재 대화 중인 task 상태 — 일시적 정보
- CLAUDE.md에 이미 명시된 것
세션 파일 압축 타이밍
- 같은 작업의 후속 세션이 있으면 이전 세션을 5-10줄로 압축 (링크와 핵심 결정만)
- 30일 이상 지난 세션은 자동 요약 후보
- "How to apply" 섹션이 있는 기억은 TTL이 명시된 경우에만 삭제
관련 파일: sleep/, sleep/mcp-server/, ~/.claude/projects/*/memory/