메모리

에이전트는 같은 취향을 매번 다시 배우지 않는다. 런타임이 스스로 남기는 기억이 여기 해당한다. 다만 이 기억은 개인 환경에 머물고, 팀이 공유하는 룰이나 스킬과 역할이 다르다.

기준일: 2026-09-30

런타임이 남기는 기억

기억은 대화가 아니라 런타임이 관리하는 별도 기능이다. 켜고 끄는 위치, 저장되는 파일 이름, 읽어들이는 길이가 런타임마다 다르다.

Claude Code의 자동 메모리는 기본으로 켜져 있고, 저장 위치는 프로젝트 단위다.

~/.claude/projects/<프로젝트 경로>/memory/
  MEMORY.md      ← 색인
  <개별 기억 파일>

같은 저장소의 여러 작업 트리가 이 디렉터리를 함께 쓴다. 색인은 매 세션의 앞부분만 읽어들이므로, 첫 줄에 자주 쓰는 정보를 모으는 편이 유리하다. 켜짐 여부와 내용은 /memory에서 확인하고 정리한다.

Codex의 로컬 메모리는 기본으로 꺼져 있고, 설에서 켠 뒤 ~/.codex/memories/에 만들어진다. 대화 중 백그라운드로 생성되며, 생성 시 비밀값은 가려진다. 생성된 상태 파일로 취급하라고 안내하므로 손으로 고치기보다 다시 생성되는 것을 기다리는 쪽이 안전하다.

기억과 승격 기준

메모리의 쓰임은 하나가 아니다. 개인의 취향과 피드백, 그리고 다음 작업에 필요한 사실이 섞여 들어간다.

남길 내용	두는 곳	이유
말투·코드 스타일·선호	로컬 메모리	팀에 맞추지 않아도 되는 개인 설정
같은 실수를 반복한다는 지적	로컬 메모리	개인에게만 해당하는 피드백
파일 경로와 실행 명령	저장소 문서	프로젝트에 따라 바뀌는 값이라 기억보다 파일이 정확하다
반드시 지킬 규칙	룰	세션마다 읽혀야 하는 강제 지시
반복되는 작업 절차	스킬	필요할 때 불러 쓰는 절차
중요한 결정과 이유	문서	사람이 읽고 나중에 이유를 확인한다

기준은 하나다. 모두가 알아야 하는 내용이면 메모리에 두지 않는다. 개인에게만 의미 있는 내용이면 공유 문서로 올리지 않는다. 올릴 때 무엇으로 바꿀지는 하네스 스스로 개선하기 페이지에서 더 다룬다.

공유 문서로 올릴 때는 문장만 옮기지 말고 왜 그렇게 정했는지도 함께 적는다. 이유가 없으면 다음에 같은 질문이 다시 나온다.

오래된 기억의 한계

기억에는 시점이 있다. 파일을 옮기거나 명령 이름을 바꾸면 기억은 틀린 상태로 남는다.

1주 전    메모리: "빌드는 pnpm build 로 한다"
이번 주   빌드 명령이 pnpm docs:build 로 바뀜
다음 세션 메모리를 믿고 pnpm build 실행 → 실패

확인하는 순서는 간단하다. 기억이 말하는 파일과 명령이 지금 존재하는지 저장소에서 확인한다. 없으면 기억을 고치는 것이 아니라 다시 확인한 결과를 남긴다. 파일이 없는 대상을 계속 기억에 두면 나중에 그 기억이 근거로 인용된다.

정리는 주기적으로 한다. 다음과 같은 항목을 훑어본다.

• 이미 옮겼거나 지운 파일을 가리키는 기억
• 다른 문서로 옮겨 더 이상 필요 없는 기억
• 같은 내용이 여러 번 쌓인 기억
• 지금 확인해 보니 틀린 기억

삭제와 수정은 사람이 한다. 아무도 모르게 사라지면 무엇이 사라졌는지 나중에 확인할 수 없다.

비밀값 기록 금지

기억은 요청문이나 저장소 밖의 파일에도 남을 수 있다. 그래서 API 키와 개인 토큰, 자격 증명은 남기지 않는다.

남겨도 되는 것: 도구 이름, 자주 쓰는 명령, 설정 키 이름
남기지 않는 것: API 키, 개인 토큰, 비밀번호, 계정 식별자

비밀값이 필요하면 보안 페이지처럼 환경 변수로 전달한다. 기억 파일을 커밋하는 저장소에 비밀값이 남아 있으면 나중에 전체 이력을 함께 노출된다.

한 번 들어간 비밀값은 전체 이력에서 지우기 어렵다. 넣지 않는 편이 빠르다.

정리 루프 만들기

기억은 자동으로 정리되지 않는다. 사람이 결과를 확인하는 순간을 정해 두는 편이 좋다.

작업이 끝난 뒤
  → 이번 세션에서 새로 쌓인 기억 확인
  → 현재 저장소와 대조
  → 팀이 알아야 할 내용만 문서로 승격
  → 틀린 기억과 중복 기억 삭제

요청으로 맡기면 이렇게 물을 수 있다.

이번 세션에서 쌓인 로컬 기억 목록을 보여 줘.
각 항목마다 현재 저장소와 대조해
- 지금도 맞는지
- 파일이나 명령이 실제로 존재하는지
를 확인해 줘.

팀이 알아야 할 내용만 따로 모아 주고,
그 외에는 삭제하거나 수정이 필요한 항목을 구분해 줘.
수정은 하지 말고 목록만 보여 줘.

확인 없이 승격하거나 삭제하게 두지 않는다. 개인 취향이 팀 문서에 섞이는 일과, 팀 규칙이 개인 기억으로만 남는 일은 둘 다 나중에 곤란해진다.

기억이 문제가 될 때 가장 흔한 경우는 세 가지다. 경로와 명령이 바뀌었는데 기억이 갱신되지 않은 경우, 한 번의 피드백을 일반 규칙처럼 확대해 적용한 경우, 정리하지 않아 같은 내용이 쌓인 경우다. 셋 다 사람이 확인하는 순간이 있어야 발견된다.

실무에서 쓰는 기준

• 개인 취향과 반복 지적은 로컬 메모리에 둔다.
• 프로젝트 값은 저장소 문서에 두고 기억에서 뺀다.
• 기억이 말하는 파일과 명령은 쓰기 전에 존재 여부를 확인한다.
• 팀 규칙이 필요한 순간에 기억만 보고 넘어가지 않는다.
• 정리한 목록은 남겨 두고 다음에 무엇을 고쳤는지 확인한다.

보충: 런타임별 자동 메모리의 기본값과 관리 방법

Claude Code의 자동 메모리는 기본 켜짐이며, 저장 위치는 ~/.claude/projects/<프로젝트>/memory/다. MEMORY.md 색인과 개별 기억 파일로 나뉘고, 같은 저장소의 worktree가 공유한다. 색인은 매 세션 첫 200줄 또는 25KB까지 읽어들인다. 활성 여부와 내용은 /memory에서 관리한다.

Codex의 로컬 메모리는 기본 꺼짐이며, 켠 뒤 ~/.codex/memories/에 이전 대화에서 만들어진 상태 파일이 저장된다. 생성 과정에서 비밀값은 가려지며, 상태 파일을 손으로 고치는 것을 주 관리 수단으로 삼지 않는다. 팀에 필요한 지침은 AGENTS.md나 저장소 문서에 둔다.

두 런타임 모두 자동 메모리의 주기적 삭제 주기와 보존 기간에 대한 공통 권장은 확인되지 않았다. 정리 시점과 남길 기준은 사람이 정하는 운영 지침으로 둔다. 이 저장소에서는 정리 시점을 작업 단위의 끝으로 잡고, 승격은 룰·스킬·문서로 나누어 한다. 기준일: 2026-09-30.