# 메모리

런타임별 자동 메모리의 특성과 팀 규칙과의 차이점 및 관리 주의사항을 다룹니다.

원본 URL: https://abc.noco.kr/harness-basics/memory

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

기준일: 2026-09-30

## 런타임이 남기는 기억

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

[Claude Code](/glossary#claude-code)의 자동 메모리는 기본으로 켜져 있고, 저장 위치는 프로젝트 단위다.

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

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

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

## 기억과 승격 기준

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

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

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

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

## 오래된 기억의 한계

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

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

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

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

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

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

## 비밀값 기록 금지

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

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

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

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

## 정리 루프 만들기

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

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

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

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

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

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

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

## 실무에서 쓰는 기준

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

::: details 보충: 런타임별 자동 메모리의 기본값과 관리 방법
[Claude Code](https://code.claude.com/docs/en/memory)의 자동 메모리는 기본 켜짐이며, 저장 위치는 `~/.claude/projects/<프로젝트>/memory/`다. MEMORY.md 색인과 개별 기억 파일로 나뉘고, 같은 저장소의 worktree가 공유한다. 색인은 매 세션 첫 200줄 또는 25KB까지 읽어들인다. 활성 여부와 내용은 `/memory`에서 관리한다.

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

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