어제인가 이미 소개글을 올렸습니다만, 써보다보니 컨텍스트가 길어지는 문제가 있어서 버전업했습니다.

## 설치는 prompt 한 줄

이게 핵심 UX입니다. 본인이 쓰는 에이전트(Claude Code든 Cursor든 어느 거든)에

이 한 줄만 던지세요.

> Fetch https://raw.githubusercontent.com/daystar7777/agent-work-mem/main/prompt.md and apply it to this project.

(한글로는 에이전트에게 '깃헙에서 daystar7777/agent-work-mem 이거 받아서 설치해줘' 하면 됩니다/다른 에이전트에게는 프로젝트 구조 파악해줘 한번씩 해주심 되구요)

에이전트가 알아서:

1. 자기 정체(model-id, vendor, capability) 선언

2. AIMemory/ 폴더 + PROTOCOL.md + INDEX.md + PROJECT_OVERVIEW.md +

   work.log 생성

3. 첫 이벤트 기록

4. (옵션) Obsidian 자동 감지/설치

5. 이후 모든 턴에서 protocol 따르겠다고 commit

## 기존 사용자 업그레이드

이전 버전(단순 work.log + PROTOCOL.md만 있던 분) → v2 마이그레이션도

한 줄로 끝:

> Fetch https://raw.githubusercontent.com/daystar7777/agent-work-mem/main/upgrade.md and execute it on this project.

(한글로는 에이전트에게 '깃헙에서 daystar7777/agent-work-mem 이거 업그레이드해줘' 하면 됩니다)

비파괴적입니다. 기존 work.log는 한 바이트도 안 손실되고, 추가로 가치

있는 부분 — **기존 work.log 통째로 읽고 PROJECT_OVERVIEW.md 자동

합성**해주기 때문에 신규 유저보다 오히려 풍성한 onboarding이 됩니다.

혹시 처음 써보시려는 분들은 아래와 같이 하시면 됩니다. (에이전트간 복사 붙여넣기 할일이 사라집니다)

## 사용법은 자연어로

여러 LLM 협업이 핵심 기능인데, 사용은 의외로 평범합니다.

**보내는 에이전트(예: Claude Code)에게**:

> 이 작업 끝나면 gpt-5-codex에게 핸드오프해줘.

→ Claude가 `handoff_<topic>.claude-opus-4-5.md`에 구조화된 AICP 메시지

작성 + work.log에 HANDOFF 이벤트 기록.

**받는 에이전트(Codex CLI)에게** (다른 세션):

> claude-opus-4-5가 핸드오프한 거 받아서 검토해줘.

→ Codex가 work.log 보고 open HANDOFF 발견 → 핸드오프 파일 읽고 →

REVIEW_RESPONSE 작성 + 다시 work.log에 기록.

핸드오프 파일 양식이나 메시지 타입을 외울 필요 없습니다. 자연어 명령이

내부 구조를 trigger합니다.

이번에 크게 바뀐 내용이 다음과 같습니다.

## 며칠 써본 끝에 추가한 것: 티어드 메모리

처음에 단순하게 work.log 하나만 두고 만들었는데, 며칠 쓰니 누적이

커져서 매 세션 다 읽다가 컨텍스트 너무 먹는 문제가 생겼습니다.

그래서 hot/warm/cold 3-tier로 나눴습니다.

- **Hot** = `work.log` (최근 50개 이벤트, 매 세션 필독)

- **Warm** = `archive/work-YYYY-MM-DD.log` (날짜별 보관)

- **Cold** = `cold/digest-YYYY-MM.md` (월별 요약, 명시적 요청시만)

회전(rotation)은 자동입니다. work.log가 임계값(기본 50, 사용자 설정

가능) × 1.5를 넘으면 다음 세션이 알아서 오래된 이벤트를 archive로

옮기고 INDEX 갱신. POSIX O_APPEND atomicity + flock로 race-safe.

**INDEX.md에 Topic 검색 인덱스**:

    auth          → archive/work-2026-04-26.log

    jwt           → archive/work-2026-04-26.log

    bootstrap     → archive/work-2026-04-25.log

"두 달 전 auth 어디까지 했더라?" 물으면 에이전트가 `grep INDEX.md` 한

번으로 어떤 archive 로드할지 결정. 전체 안 뒤집니다.

**PROJECT_OVERVIEW.md = 새로 합류하는 LLM의 60초 브리핑**:

도중에 새로 추가한 LLM(예: Gemini)이 프로젝트 무엇 / 기술 스택 /

locked-in 결정 / 현재 진행중 / open 핸드오프를 1스크린에 파악할 수

있는 onboarding primer. cold digest를 쓸 때마다 자동 갱신됩니다.

## 솔직한 한계

- 순전히 convention 기반입니다. 에이전트가 규칙 안 지키면 "너 work.log

  안 적었네" 나무라야 합니다 (코드 리뷰처럼). 신뢰할 수 있는 agent

  플랫폼끼리 쓸 때 가장 잘 작동.

- 일부 LLM은 자기 model-id를 정확히 모릅니다. 사용자가 알려줘야 할 때

  있음.

- AIMemory에 민감 정보 들어갈 수 있으니 public repo면 .gitignore 또는

  private repo 분리 권장.

- 채팅 전용 LLM(웹 ChatGPT 무료, 모바일앱 등)은 파일 시스템 접근이

  없어서 직접 수행 불가. 일회성 의견 들을 때만 사용 권장.

## 정리

- **신규 설치**: `Fetch https://raw.githubusercontent.com/daystar7777/agent-work-mem/main/prompt.md and apply it to this project.`

- **기존 업그레이드**: `Fetch https://raw.githubusercontent.com/daystar7777/agent-work-mem/main/upgrade.md and execute it on this project.`

- **깃헙**: https://github.com/daystar7777/agent-work-mem

README에 mermaid 도식 두 개 + 실전 시나리오 7개 + AICP handoff 샘플

파일 + INDEX.md / PROJECT_OVERVIEW.md 샘플 들어있습니다. 한 프로젝트에서

Claude / GPT / Gemini 같이 굴리면서 며칠 동안 실제 또 다듬은 거라 모서리들은

대충 깎여있는 상태입니다.

부족한 부분이나 "이 케이스는?" 지적 환영합니다. 이슈/PR도 환영.

이상입니다.

저도 써보고 상당히 편리함을 느낀거라 여러분도 경험해보시길 권합니다.

써보고 괜찮으시면 주변에 추천해주세요 +ㅁ+b