Memory Helpers

BMAD(Belief-Memory-Action-Dialogue) 패턴을 위한 메모리 관리 헬퍼입니다.

파일 구조

.raven/state/
├── memory/
│   ├── belief.json      # 에이전트 신념 상태
│   ├── working.json     # 현재 작업 컨텍스트
│   └── decisions/       # 태스크별 의사결정 기록
│       └── {task_id}.json
└── dialogue/            # 태스크별 대화 히스토리
    └── {task_id}.json

belief-load

프로젝트에 대한 에이전트의 현재 신념 상태를 로드합니다.

사용 시점: 에이전트 시작 시

cat .raven/state/memory/belief.json

반환 구조:

{
  "updated_at": "ISO timestamp",
  "project": { "name", "type", "tech_stack", "structure_summary" },
  "codebase": { "key_files", "patterns", "conventions" },
  "current_focus": { "task_id", "understanding", "blockers" }
}

belief-update

신념 상태의 특정 필드를 업데이트합니다.

사용 시점:

• 새로운 코드베이스 정보 학습 시
• 태스크 포커스 변경 시
• 프로젝트 이해가 깊어질 때

프로세스:

1. .raven/state/memory/belief.json 읽기
2. 해당 필드 업데이트
3. updated_at 갱신
4. 파일 저장

예시 업데이트:

{
  "current_focus": {
    "task_id": "session-persistence",
    "understanding": "BMAD 메모리 시스템 구현 중",
    "blockers": []
  }
}

working-init

새 세션을 위한 working memory를 초기화합니다.

사용 시점: 새 태스크 구현 시작 시

프로세스:

1. UUID 생성 (또는 timestamp 기반 ID)
2. working.json 초기화

초기 구조:

{
  "session_id": "{generated-uuid}",
  "agent": "raven-coding",
  "task_id": "{current_task_id}",
  "started_at": "{ISO timestamp}",
  "last_activity": "{ISO timestamp}",
  "plan": {
    "steps": [],
    "current_step": 0
  },
  "context": {
    "files_read": [],
    "files_modified": [],
    "key_findings": []
  },
  "notes": [],
  "handoff": null
}

working-update

현재 세션의 진행 상태를 업데이트합니다.

사용 시점:

• 구현 단계 완료 시
• 파일 읽기/수정 시
• 중요 발견 시

업데이트 가능 필드:

• plan.steps[n].status: "pending" | "in_progress" | "completed"
• plan.current_step: 현재 단계 번호
• context.files_read: 읽은 파일 경로 추가
• context.files_modified: 수정한 파일 경로 추가
• context.key_findings: 중요 발견 추가
• notes: 메모 추가
• last_activity: 항상 갱신

working-load

이전 세션의 working memory를 로드하여 재개합니다.

사용 시점: /raven:code resume 실행 시

프로세스:

1. .raven/state/memory/working.json 읽기
2. session_id가 null이 아니면 활성 세션 존재
3. 사용자에게 재개 여부 확인
4. 재개 시 last_activity 갱신하고 계속

재개 정보 표시:

📂 이전 세션 발견

태스크: {task_id}
에이전트: {agent}
시작: {started_at}
마지막 활동: {last_activity}

진행 상황:
{plan.steps 표시}

이전 세션을 재개하시겠습니까?

decision-log

의사결정을 기록합니다.

사용 시점: 중요한 기술적/설계적 결정 시

프로세스:

1. .raven/state/memory/decisions/{task_id}.json 확인
2. 없으면 생성, 있으면 로드
3. 새 결정 추가
4. 저장

결정 기록 구조:

{
  "id": {auto_increment},
  "timestamp": "ISO timestamp",
  "decision": "결정 내용",
  "rationale": "결정 이유",
  "alternatives": [
    {"option": "대안", "rejected_reason": "거부 이유"}
  ],
  "impact": "low" | "medium" | "high"
}

기록해야 할 결정 예시:

• 라이브러리/프레임워크 선택
• 아키텍처 패턴 선택
• 데이터 구조 설계
• API 설계 결정
• 트레이드오프 선택

dialogue-save

세션의 대화 요약을 저장합니다.

사용 시점: 세션 종료 시 또는 중요 대화 후

프로세스:

1. .raven/state/dialogue/{task_id}.json 확인
2. 없으면 생성, 있으면 로드
3. 새 대화 요약 추가
4. 저장

대화 기록 구조:

{
  "session_id": "{working.session_id}",
  "started_at": "ISO timestamp",
  "ended_at": "ISO timestamp",
  "summary": "세션 요약 (1-2문장)",
  "key_exchanges": [
    {
      "user": "사용자 요청 요약",
      "agent": "에이전트 응답 요약",
      "outcome": "결과/영향"
    }
  ],
  "outcomes": ["완료된 작업들"]
}

session-end

세션을 정상 종료하고 모든 상태를 저장합니다.

사용 시점:

• 태스크 완료 시
• 사용자가 종료 요청 시
• 에이전트 전환(핸드오프) 시

프로세스:

1. working.json 최종 상태 저장
2. belief.json 학습 내용 반영
3. dialogue/{task_id}.json에 세션 요약 추가
4. 핸드오프인 경우 working.handoff 작성
5. 태스크 완료인 경우 working.json 초기화

handoff-write

다음 에이전트를 위한 핸드오프 노트를 작성합니다.

사용 시점: 에이전트 전환 시

프로세스:

1. working.json의 handoff 필드에 작성
2. 다음 에이전트가 알아야 할 정보 포함

핸드오프 구조:

{
  "from_agent": "raven-coding",
  "to_agent": "raven-tester",
  "timestamp": "ISO timestamp",
  "context": "현재 상태 요약",
  "completed": ["완료된 작업들"],
  "pending": ["남은 작업들"],
  "notes": ["참고사항"],
  "files_to_check": ["확인해야 할 파일들"]
}

handoff-read

이전 에이전트의 핸드오프 노트를 읽습니다.

사용 시점: 에이전트 시작 시 핸드오프가 있는 경우

프로세스:

1. working.json의 handoff 필드 확인
2. 있으면 내용 파싱 및 표시
3. 컨텍스트 파악 후 작업 시작

통합 워크플로우

에이전트 시작 시

1. working-load → 이전 세션 확인
   ├─ 있으면 → 재개 여부 확인
   └─ 없으면 → 새 세션
2. belief-load → 프로젝트 컨텍스트 복원
3. handoff-read → 핸드오프 확인 (있으면)
4. working-init → 새 세션 초기화 (새 세션인 경우)

작업 중

1. working-update → 진행 상태 업데이트 (매 단계)
2. belief-update → 새 지식 반영 (필요시)
3. decision-log → 중요 결정 기록 (결정 시)

에이전트 종료 시

1. working-update → 최종 상태 저장
2. dialogue-save → 세션 대화 요약
3. belief-update → 학습 내용 반영
4. handoff-write → 핸드오프 노트 (전환 시)
5. session-end → 세션 정리