Memory Engine
수동 메모리 시스템을 위한 강화 레이어입니다. 이 스킬은 기존 자동 메모리 동작을 대체하지 않습니다 — 그 위에 구조, 예산 인식, 세션 종료 체크포인트를 추가합니다.
핵심 철학: 제안만 하고, 자동 저장하지 않습니다. 사람이 무엇을 보관할 가치가 있는지 결정합니다.
메모리 디렉토리
모든 메모리 파일은 ~/.claude/projects/-Users-coni/memory/에 있습니다.
인덱스 파일: MEMORY.md (항상 로드되며, 순수 포인터만 포함, 내용 없음).
1단계: 메모리 캡처
메모리를 저장할 때(사용자 트리거 또는 세션 체크포인트로 인해) 매번 다음 흐름을 따릅니다:
1단계 — 분류
다섯 가지 유형. 해당하는 것을 선택합니다:
| 유형 | 캡처 대상 | 신호 |
|---|---|---|
user | 신원, 선호도, 가치관, 지식 | "저는...", "저는 ...를 선호합니다", 성격 변화 |
feedback | 사용자와 협업하는 방법 — 수정 사항 및 확인 사항 | "그렇게 하지 마", "맞아 그렇게 해", 접근 방식 검증됨 |
project | 활성 작업 컨텍스트, 마감일, 목표 | "목요일까지 X를 하고 있어요", 이정표 달성 |
reference | 외부 지식, 도구 설정, 참조 포인트 | 새 도구 발견, API 설정됨 |
decision | X 대신 Y를 선택한 이유 | "X 대신 Y를 선택", 절충 비교, 아키텍처 결정 |
decision 유형의 경우: references/decision-type-spec.md에서 머리말 스키마와 본문 구조(컨텍스트 → 옵션 → 결정 → 재검토 시기)를 읽습니다.
2단계 — 중복 제거
쓰기 전에 MEMORY.md 인덱스를 스캔하여 중복 항목을 확인합니다:
- 같은 주제가 이미 다루어졌습니까? → 기존 파일을 업데이트하고 새 파일을 만들지 않습니다.
- CLAUDE.md 규칙과 중복됩니까? → 저장하지 않습니다(규칙이 권위 있음).
- 일시적인 작업 세부 정보입니까? → 저장하지 않습니다(git 로그/코드가 진실 공급원).
feedback-memory-hygiene.md의 모든 규칙을 적용합니다 — 해당 규칙이 권위를 유지합니다.
3단계 — 토큰 비용 추정
계산: file_bytes / 3.2 (정수, 내림). 이는 외부 종속성 없이 혼합 CJK/영어 콘텐츠에 대해 합리적인 근사치를 제공합니다.
4단계 — 쓰기
- YAML 머리말(이름, 설명, 유형)로 메모리 파일을 생성합니다.
- MEMORY.md 인덱스 업데이트 — 올바른 섹션 제목 아래에 항목을 추가합니다.
- 인덱스 줄 끝에 토큰 추정치를 추가합니다:
`~NNNNtk`
인덱스 줄 예시:
- [decision-deploy-cloudflare.md](decision-deploy-cloudflare.md) — 국내 배포는 Vercel 대신 CF Pages 선택 `~280tk`
저장하지 말아야 할 것
다음 규칙은 절대적입니다(메모리 위생 + 자동 메모리 시스템에서):
- 코드 패턴, 아키텍처, 파일 경로 — 코드에서 파생 가능
- Git 히스토리, 최근 변경 사항 —
git log가 권위 있음 - 디버그 솔루션 — 수정 사항은 코드에 있음
- 이미 CLAUDE.md 또는
~/cc-personal/rules/에 있는 것 - 일시적인 작업 상태 — 현재 세션에서만 유용함
- 프로젝트 상태 스냅샷 — 코드와 git에서 읽음
2단계: 메모리 유지보수
/memory-check
감사 스크립트를 실행하고 결과를 제시합니다:
bash ~/.claude/skills/memory-engine/scripts/memory-health-check.sh
스크립트는 다음을 포함하는 구조화된 보고서를 출력합니다:
- 예산: 총 토큰 대 40,000tk 한도(200K 컨텍스트의 20%)
- 유형 분포: 유형별 개수 및 토큰
- 크기 상위 5개: 가장 많은 예산을 소비하는 가장 큰 파일
- 문제: 오래된 파일(>30일), 고아, 끊어진 링크, 빈 유형, 예산 경고
보고서 제시 후, 발견된 각 문제에 대한 특정 조치를 제안합니다:
| 문제 | 조치 |
|---|---|
| STALE | "검토 또는 보관: {파일} — 여전히 관련 있습니까?" |
| ORPHAN | "MEMORY.md 인덱스에 추가하거나, 쓸모없으면 삭제" |
| BROKEN LINK | "MEMORY.md에서 제거하거나, 파일을 다시 생성" |
| NO ENTRIES | 정보 제공 — 모든 유형이 항상 항목을 필요로 하지는 않음 |
| BUDGET WARNING | "가장 큰 파일: ... — 압축 또는 분할 고려" |
문제 해결 후 MEMORY.md 예산 주석을 업데이트합니다:
<!-- budget: ~NNNNtk / 40000tk (NN%) | updated: YYYY-MM-DD -->
토큰 주석 형식
모든 MEMORY.md 인덱스 항목은 토큰 추정 접미사를 가집니다:
- [filename.md](filename.md) — 설명 `~NNNNtk`
예산 주석은 MEMORY.md의 맨 위(제목 앞)에 위치합니다. HTML 주석이므로 렌더링된 마크다운에서는 보이지 않지만 스크립트로 파싱 가능합니다.
3단계: 7차원 통합 체크포인트
트리거 (이중 안전장치)
주 트리거 — 프롬프트 기반 (CLAUDE.md 규칙): 대화에서 다음 신호를 감지하면 적극적으로 7차원 스캔을 실행합니다:
- 도구 호출이 많음 (>15회 도구 호출)
- 실질적인 산출물(코드, 분석, 솔루션) 완료
- 주제가 크게 전환됨
- 사용자가 "정리", "복기", "요약"을 명시적으로 말함
백업 트리거 — Stop 후크 (settings.json):
consolidation-trigger.sh는 agent가 멈출 때마다 실행되어 stop 횟수와 시간 간격을 추적합니다.
stop 횟수 ≥ 20이고 마지막 트리거 이후 ≥ 30분이 경과하면 7차원 스캔 프롬프트를 출력합니다.
상태 파일: ~/.claude/projects/-Users-coni/memory/.consolidate-state
7차원 스캔
현재 대화를 한 줄씩 스캔하여 적중 여부를 판단합니다:
| # | 차원 | 적중 신호 | 해당 메모리 유형 |
|---|---|---|---|
| 1 | 작업 완료 | 전체 작업이 요청부터 전달까지 완료됨 | project (이정표) |
| 2 | CLAUDE.md 업데이트 | 새로운 일반 동작 규칙 발견됨 | 직접 CLAUDE.md에 작성 |
| 3 | Rules 정리 | 도메인/도구/파일 유형 관련 규칙 발견됨 | ~/cc-personal/rules/에 작성 |
| 4 | 아키텍처 결정 | 도구 선택, 기술 솔루션, 배포 전략 등 명확하지 않은 선택이 이루어짐 | decision |
| 5 | 프로젝트 이정표 | 프로젝트 상태가 실질적으로 진전됨(출시, 배포, 주요 기능 완료) | project |
| 6 | 협업 조정 | 사용자가 접근 방식을 수정하거나 명확하지 않은 방식을 확인함 | feedback |
| 7 | 고가치 분석 | 세션 간 재사용 가능한 분석 프레임워크, 통찰력, 모델이 산출됨 | reference 또는 user |
실행 흐름
7차원 스캔 → 적중 횟수 집계
적중 0-1 → 자동 건너뜀
적중 2+ → 체크포인트 제안 출력
규칙
- "저장하지 말아야 할 것" 목록을 엄격히 적용합니다 — 체크포인트 시점에도 예외 없음
- 제안하기 전에 기존 MEMORY.md 항목을 확인합니다 — 중복 없음
- 체크포인트당 최대 3개 후보 — 양보다 질
- 적격 항목이 없으면 아무것도 출력하지 않음(자동 건너뜀, 강제 제안 없음)
- 체크포인트 중에는 파일을 절대 쓰지 않음 — 사용자 승인을 위한 후보만 제시
- 각 후보는 적중한 차원 번호를 표시해야 함
출력 형식
[정리 확인] 이번 대화에서 3/7 차원 적중 (④⑥⑦), 정리 제안:
1. [decision] ④ Stop 후크 + 프롬프트 이중 트리거 방식 선택, 순수 후크 아님 — 후크는 대화 의미를 감지할 수 없음
2. [feedback] ⑥ 사용자 확인: 플라이휠의 핵심은 자동 트리거이지 메모리 분류가 아님
3. [reference] ⑦ 주체 생명력 프레임워크: 인간/회사/AI 세 주체의 시간 및 에너지 할당 모델
무엇을 저장할까요? 번호를 입력하세요 (예: 1,2), 또는 "skip"으로 건너뜁니다.
사용자가 번호를 확인하면 선택된 각 항목에 대해 1단계 저장 흐름을 실행합니다. 사용자가 "skip" 또는 이와 동등한 말을 하면 아무것도 하지 않습니다.
주의사항
- 매 저장 시 MEMORY.md 예산 주석을 업데이트하지 마세요 — /memory-check 중에만 업데이트합니다. 자주 업데이트하면 캐시가 깨지고 git diff에 노이즈가 추가됩니다.
- 토큰 추정치는 근사치입니다 — 정확하게 취급하지 마세요. /3.2 방식은 혼합 CJK/EN 콘텐츠에 대해 ~90% 정확하며 예산 인식에 충분히 좋습니다.
- decision 유형은 중요하지 않은 선택이 아닙니다 — "vim 대신 nano를 사용했습니다"는 저장할 가치가 없는 결정입니다. 향후 세션에 영향을 미치는 선택을 위해 남겨두세요.
- Stop 후크는 백업이지 주력이 아닙니다 — 사용자가 Ctrl+C로 종료하면 후크가 트리거되지 않습니다. 적극적인 스캔이 플라이휠의 엔진입니다.
- 적극적인 스캔으로 사용자의 몰입을 방해하지 마세요 — 작업 간 간격(단계 완료, 주제 전환)에 트리거하고 실행 중간에 삽입하지 마세요.