/memory

name: memory
description: 메모리를 기록·정리할 때 사용. 세션을 넘기기 전 인계, 교정·의외를 메모로 남길 때, 세션 시작의 "메모리 점검"이 정리를 권할 때, 주 1회 정리, 기존 프로젝트의 AGENTS.md(명령·지식 지도)를 갖출 때, Codex·Copilot과 메모리를 함께 쓰게 할 때. Triggers - 메모리 정리, 기억해, 인계, handoff, 지식 지도, AGENTS.md 정리, memory.

메모리

이 하네스의 메모리는 Claude Code auto memory를 그대로 쓰고 넓힌다. 저장소는 하나다: 세션 시작 문맥의 "메모리 폴더"(기본 `~/.claude/projects/<저장소 경로>/memory/`, `autoMemoryDirectory` 설정이 있으면 그 폴더). Claude Code는 `MEMORY.md` 앞 200줄을 스스로 읽고, Codex·Copilot은 이 하네스의 SessionStart hook이 같은 색인을 넣어 준다.

| 층 | 어디 | 수명 | 읽히는 방식 | |---|---|---|---| | 단기 | `handoff.md` — 지금·다음·막힘 | 작업 1건 | hook이 본문을 넣음(1,500자) | | 중기 | 메모 파일 + `MEMORY.md` 색인 | 수 주~수 개월 | 색인은 매 세션, 본문은 필요할 때 | | 장기·팀 | 프로젝트 `AGENTS.md`(`## 명령`·`## 자주 틀리는 것`·`## 지식 지도`) | 기한 없음 | 세 호스트가 매 세션 | | 장기·개인 | `~/.claude/CLAUDE.md` | 기한 없음 | Claude가 모든 프로젝트에서 | | 원본 | `docs/`, `docs/work/*/` | 프로젝트 | 지식 지도를 보고 필요할 때 |

원칙은 두 가지다. **늘 읽히는 곳에는 코드로 알 수 없는 것만 짧게 둔다.** 늘 로드되는 개요는 성공률을 올리지 못하고 비용만 늘린다. **고칠 때는 항목 단위로만 고친다.** 파일을 통째로 다시 쓰면 내용이 무너진다.

메모 형식

---
name: <kebab-case 이름>
description: <한 줄 요약 — 색인과 회상에 쓰인다>
metadata:
  type: user | feedback | project | reference
  hits: 1
---

<사실 하나. feedback·project는 이어서 **Why:**와 **How to apply:** 한 줄씩. 관련 메모는 [[이름]]으로 잇는다.>

색인 `MEMORY.md`에는 `- [제목](파일.md) — 한 줄` 형식으로 한 줄만 둔다. `## 진행 중`(handoff), `## Feedback`, `## Project`, `## Reference`, `## User` 절로 묶는다. Claude Code가 저장할 때 `modified` 시각을 붙이므로 날짜는 따로 적지 않는다.

A. 기록

1. **쓸 것인가:** 코드만 봐서는 알 수 없고, 오래 유효하며, 잊으면 손해인 교정·의외·결정만 쓴다. 테스트·타입·코드 주석·커밋 메시지로 남길 수 있으면 그쪽이 먼저다. 그 지식을 가진 docs가 있으면 docs를 고친다(문서 동기화). 2. **이미 있나:** 색인에서 같은 내용을 찾는다. 있으면 그 파일을 고치고 `hits`를 1 올린다. 틀린 메모는 고치거나 지운다. 새로 쓸 때만 색인에 한 줄을 더한다. 3. **바로 장기로:** 사용자가 "항상/절대"라고 했으면 메모를 거치지 않고 D-1로 올린다.

B. 인계 (세션을 넘기거나 `/clear` 전)

`handoff.md`(type project)를 다섯 줄 이내로 고쳐 쓴다: 지금 하던 것, 다음 한 걸음, 막힌 점·확인할 것, 관련 파일·plan 경로. 대화 요약이 아니라 다음 세션이 바로 움직일 정보만 쓴다. 색인 `## 진행 중`에 한 줄을 둔다. 작업이 끝나면 파일과 색인 줄을 지운다.

C. AGENTS.md 갖추기 (기존 프로젝트에 `## 명령`·`## 지식 지도`가 없을 때. 새 프로젝트는 `scaffold`가 만든다)

1. `docs/` 목록, README, 운영 문서(배포·CI), 매니페스트를 훑는다. 본문은 다 읽지 않는다. 2. 매니페스트·CI에서 전체 검사(lint·타입·테스트)와 개발 서버 명령을 찾아 `## 명령`에 적는다. 전체 검사가 명령 하나로 없으면 만들자고 제안한다. AGENTS.md가 없으면 만들고 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 둔다. 3. `## 지식 지도`에 `| 작업 | 먼저 읽을 것 |` 표를 만든다. 문서 내용을 옮기지 않고 위치만 적는다. 집이 없는 지식은 `docs/`에 넣고 지도에 한 줄 더한다. 4. 끝에 `## 하네스 가이드` 절을 둔다(내용은 `scaffold` 스킬 4절의 예와 같다). 흐름이나 하네스 특성을 잊었을 때 `harness-guide`를 읽게 하는 한 줄이다.

D. 정리 (세션 시작의 "메모리 점검"이 권하거나 주 1회)

1. **승격:** `hits` 2 이상이거나 "항상/절대"인 메모를 명령형 한 줄로 올린다. 이 프로젝트 팀이 지킬 것은 `AGENTS.md` `## 자주 틀리는 것`, 모든 프로젝트의 개인 취향은 `~/.claude/CLAUDE.md`(Codex는 `~/.codex/AGENTS.md`), 여러 단계 절차는 스킬 후보로 사용자에게 제안한다. 근거는 그 줄 뒤 `<!-- -->` 주석(컨텍스트 비용 0). 올린 메모와 색인 줄은 지운다. 2. **확인:** 메모가 가리키는 파일·함수·설정이 아직 있는지 확인하고, 없거나 틀렸으면 고치거나 지운다. 3. **삭제:** 코드·설정·린터로 알 수 있게 된 것, 끝난 project 메모, `modified`가 오래됐는데 `hits`가 1인 메모는 지울지 묻는다. 4. **병합:** 같은 뜻의 메모는 하나로 합치고 `hits`를 더한다. 상대 날짜는 절대 날짜로 바꾼다. 5. **AGENTS.md 점검:** 스스로 알 수 있는 줄(디렉터리 구조·설치 패키지·일반 상식)과 두 곳에 겹친 규칙을 지운다. 6. 바뀐 내용을 diff로 보여 준다. 장기 층(AGENTS.md, `~/.claude/CLAUDE.md`) 변경은 승인받고 적용한다.

E. Codex·Copilot과 함께 쓰기

기본 폴더는 저장소 밖이라 Codex 샌드박스에서는 쓰기가 막힌다. 이 프로젝트를 여러 호스트로 쓰면 저장소 안 폴더로 옮긴다: `.claude/settings.local.json`에 `"autoMemoryDirectory": "<저장소 절대경로>/.agents/memory"`를 넣고, 기존 메모를 그 폴더로 옮기고, `.gitignore`에 `.agents/memory/`를 더한다. Claude Code는 다음 세션부터 새 폴더를 쓰고, 이 하네스의 hook도 같은 설정을 읽어 모든 호스트에 같은 메모리를 보여 준다. 경로는 절대 경로나 `~/`로 쓴다(상대 경로는 Claude Code가 무시한다). `settings.local.json`은 git에 없으므로 새 worktree에도 같은 줄을 넣는다. Claude Code는 이 설정을 폴더 신뢰(trust)를 받은 뒤에만 따르고 hook은 항상 따른다. 그래서 처음 여는 폴더에서는 신뢰 확인을 마친 뒤 새 세션을 열어야 둘이 같은 폴더를 본다.