Skip to content

DESIGN.md

Latest commit

 

History

History
210 lines (153 loc) · 6.98 KB

DESIGN.md

File metadata and controls

210 lines (153 loc) · 6.98 KB
Raw

Code Memory — 설계 문서

한 줄 요약

코드 심볼(함수/클래스) 단위로 성공·실패 경험을 기록하고, 위험도가 높은 심볼을 수정할 때 활성 교훈을 Codex/Hermes 프롬프트에 바로 주입하는 극소 시스템.

1. 핵심 원칙

  1. SQLite 파일 1개 + Python 스크립트 1개. MCP 서버, npm, 외부 런타임 의존성 없음.
  2. 모든 로그를 기억하지 않는다. 재사용 가능한 lesson이 있는 경우만 기록.
  3. 기억에서 끝나지 않고 작업 방식을 바꾼다. risk_score >= 10 → query --inject로 활성 교훈 주입.
  4. 식별자는 구체적이어야 한다. 동일 심볼명이라도 파일이 다르면 다른 경험으로 본다.

2. 데이터 모델

symbols 테이블

CREATE TABLE symbols (
    id INTEGER PRIMARY KEY,
    project TEXT NOT NULL,
    name TEXT NOT NULL,          -- "AuthService.validate"
    file TEXT NOT NULL DEFAULT '',-- "auth/service.py"; 미지정 시 ""
    fail_count INTEGER DEFAULT 0,
    success_count INTEGER DEFAULT 0,
    last_fail TEXT,              -- UTC ISO datetime
    last_success TEXT,           -- UTC ISO datetime
    risk_score REAL DEFAULT 0,
    UNIQUE(project, file, name)
);

experiences 테이블

CREATE TABLE experiences (
    id INTEGER PRIMARY KEY,
    symbol_id INTEGER REFERENCES symbols(id),
    type TEXT NOT NULL,          -- 'fail' | 'success'
    lesson TEXT NOT NULL,        -- 한 줄 교훈
    detail TEXT,                 -- 추가 맥락 (선택)
    session_id TEXT,             -- 세션 ID (추적용)
    status TEXT DEFAULT 'active',-- 'active' | 'resolved' | 'inactive'
    created_at TEXT DEFAULT (datetime('now'))
);

운영 프래그마

PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;

기존 DB는 시작 시 v0.3 스키마로 트랜잭션 마이그레이션한다. PRAGMA user_version이 0 또는 1이면 마이그레이션하고, 성공 시 2로 기록한다. user_version = 2인 DB는 스킵한다. 이전 실패 잔재인 symbols_old, experiences_old는 마이그레이션 시작 시 제거하고, 오류가 나면 ROLLBACK 후 종료한다.

기존 file IS NULL 값은 ""로 정규화한다. symbols 또는 experiences 중 하나만 있는 부분 DB는 CREATE TABLE IF NOT EXISTS 경로로 누락 테이블을 만든 뒤 필요한 재구성을 계속한다.

3. CLI 인터페이스

# 조회
cm.py -p drawings-db query AuthService.validate --file auth/service.py
cm.py -p drawings-db query --top 5
cm.py -p drawings-db query AuthService.validate --inject
cm.py -p drawings-db query AuthService.validate --json
cm.py -p drawings-db query AuthService.validate --all

# 기록
cm.py -p drawings-db fail AuthService.validate "JWT 만료 처리 누락" --file auth/service.py -d "refresh_token 확인"
cm.py -p drawings-db ok AuthService.validate "UTC 정규화 후 통과" --file auth/service.py

# lesson 상태
cm.py resolve 12
cm.py deactivate 13

# 통계
cm.py -p drawings-db stats
cm.py -p drawings-db stats AuthService --json

모든 커맨드는 --json을 지원한다. fail, ok, query는 --file을 통해 (project, file, symbol) 식별자를 명시할 수 있다.

--file은 저장/조회 전에 정규화한다.

  1. None 또는 ""는 ""
  2. \는 /
  3. os.path.normpath()로 ./, ../ 정리
  4. 선행 ./ 제거
  5. 절대경로는 현재 작업 디렉터리 기준 상대경로로 변환

따라서 src/auth.py, ./src/auth.py, src\auth.py, .\src\auth.py는 같은 파일 식별자로 저장된다.

4. Lesson 상태

experiences.status 값:

status 의미 기본 query --inject
active 아직 반복 방지에 필요한 교훈 표시 주입
resolved 코드/테스트가 바뀌어 해결된 교훈 숨김 (--all에서 표시) 제외
inactive 더 이상 유효하지 않거나 노이즈인 교훈 숨김 (--all에서 표시) 제외

상태 변경 시 위험도를 다시 계산한다. fail_count, success_count, last_fail, last_success, risk_score는 active 경험만 반영하며, resolved/inactive 경험은 카운터와 위험도 입력에서 제외한다.

5. 위험도

fail, ok, resolve, deactivate 시 자동 재계산한다.

risk_score = fail_count * 1.0
           + recency_weight * 1.5
           + consecutive_fails * 1.5
           - success_count * 0.3
  • fail_count, success_count: active 상태인 fail/success 경험 수
  • recency_weight: 최근 active 실패가 7일 이내면 1.0, 30일 이내면 0.5, 그 이상이면 0.2
  • consecutive_fails: 마지막 active 성공 이후의 active fail 경험 수. 마지막 active 성공이 없으면 전체 active fail_count
  • 최소값: 0
risk_score 등급 동작
0-4 낮음 필요 시 조회만
5-9 보통 수정 전 active lesson 확인
10-14 주의 query --inject 권장
15+ 높음 주입 필수, 검증 강화

6. 민감정보 마스킹

fail/ok 기록 시 lesson과 detail에 다음 패턴이 있으면 저장 전에 ***REDACTED***로 바꾼다.

r'(sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|Bearer\s+\S{10,}|AKIA[A-Z0-9]{16})'

7. Hermes/Codex 통합

코드 수정 전

  1. 대상 함수/클래스와 파일을 식별한다.
  2. cm.py -p <프로젝트> query <심볼명> --file <파일> 실행.
  3. risk_score >= 10이면 cm.py -p <프로젝트> query <심볼명> --file <파일> --inject 출력 블록을 작업 프롬프트에 붙인다.

주입 포맷

[PAST EXPERIENCE — <symbol> (risk: <score>, <level>)]
- <lesson 1>
- <lesson 2>
Apply these lessons. Do not repeat these mistakes.

코드 수정 후

검증 실패면 fail, 검증 성공이면 ok로 재사용 가능한 한 줄 교훈을 기록한다.

8. 파일 구조

~/workspaces/code-memory/
├── DESIGN.md
├── STATE.md
├── README.md
├── cm.py
├── code_memory.db      # gitignore 대상
├── tests/
│   └── test_cm.py
└── skills/
    └── code-memory.md

9. 구현 단계

Phase Scope Status
v0.1 query / fail / ok / stats, SQLite, skill file 완료
v0.2 JSON, --inject, composite identifier, lesson status, risk scoring, WAL, masking, pytest 완료
v0.3 트랜잭션 마이그레이션, user_version, 경로 정규화, 동시 쓰기 테스트, Hermes 설치 문서 완료
v0.4 lesson 병합, pruning, CodeGraph 영향도, 대시보드 예정

10. 안 하는 것

포기 이유
MCP 서버 터미널 CLI로 충분하고 도구 슬롯을 쓰지 않음
벡터 DB/RAG 정확한 심볼 조회와 SQLite LIKE로 시작
파일 워처 수동 기록이 품질을 높임
자동 lesson 병합 데이터가 더 쌓인 뒤 도입
호출관계 그래프 v0.3에서 CodeGraph 등과 연동 가능