장기 기억 (Session Memory)

Claude Code 세션 간 컨텍스트 유지 — 곧 출시됩니다

unreleasedmemorycontext

v2.0.72 소스에서 숨겨진 기능 발굴함. 조만간 공개될 듯 — 연말 대기 타세요

Claude Code에 장기 메모리가 생깁니다.

Session Memory는 대화에서 중요한 정보를 자동으로 캡처해서 디스크에 저장합니다. 작업 명세, 파일 참조, 워크플로우 패턴, 발생한 에러 — 모두 저장되고 다음 세션에서 복원됩니다.

긴 세션 끝나고 프로젝트를 처음부터 다시 설명해야 했던 적 있죠? 이제 그럴 필요 없어요.

어떻게 작동하나요

Session Memory는 백그라운드에서 실행되며, 주기적으로 중요한 정보를 구조화된 마크다운 파일로 추출합니다. 명령어 입력도, 수동 저장도 필요 없습니다.

트리거 조건:

저장 위치:

~/.claude/session-memory/
├── config/
│   ├── template.md      # 커스텀 템플릿 (선택)
│   └── prompt.md        # 커스텀 추출 프롬프트 (선택)
└── [session-id].md      # 세션 노트

파일은 일반 마크다운입니다. 읽고, 수정하고, 삭제할 수 있습니다.

뭘 기억하나요

Claude가 기억을 정리할 때 쓰는 템플릿입니다:

# Session Title
짧고 구별되는 5-10단어 설명

# Current State
현재 작업 중인 내용. 대기 중인 작업. 바로 다음 할 일.

# Task Specification
사용자가 요청한 빌드 내용. 설계 결정. 배경 설명.

# Files and Functions
중요한 파일, 파일 내용, 관련성.

# Workflow
주로 실행하는 Bash 명령어와 순서. 출력 해석 방법.

# Errors & Corrections
발생한 에러와 해결 방법. 실패한 접근 방식.

# Codebase and System Documentation
중요한 시스템 컴포넌트. 상호 작용 방식.

# Learnings
효과적이었던 것. 안 됐던 것. 피해야 할 것.

# Key Results
사용자가 특정 출력을 요청한 경우 — 답변, 테이블, 문서 —
정확한 결과가 여기에 보존됨.

# Worklog
단계별로 시도하고 수행한 내용. 간결한 요약.

복잡해 보여도 걱정 마세요 — 전부 자동입니다. 이런 구조로 기억한다는 것만 알면 돼요.

궁금한 분들을 위해 — Claude가 실제로 받는 지시입니다:

위의 사용자 대화를 기반으로 (이 노트 작성 지시 메시지와 시스템 프롬프트,
claude.md 항목, 또는 과거 세션 요약은 제외), 세션 노트 파일을 업데이트하세요.

{{notesPath}} 파일은 이미 읽혔습니다. 현재 내용:
<current_notes_content>
{{currentNotes}}
</current_notes_content>

당신의 유일한 작업은 Edit 도구를 사용해 노트 파일을 업데이트한 후 멈추는 것입니다.
여러 번 편집할 수 있습니다 (필요한 모든 섹션 업데이트) - 모든 Edit 도구 호출을
단일 메시지에서 병렬로 수행하세요. 다른 도구는 호출하지 마세요.

편집 시 중요 규칙:
- 파일은 모든 섹션, 헤더, 이탤릭 설명이 포함된 정확한 구조를 유지해야 함
- '#'으로 시작하는 섹션 헤더를 절대 수정, 삭제, 추가하지 말 것
- 이탤릭 _섹션 설명_ 줄을 절대 수정하거나 삭제하지 말 것
- 이탤릭 설명 아래에 나타나는 실제 내용만 업데이트할 것
- 상세하고 정보 밀도 높은 내용 작성 - 파일 경로, 함수명, 에러 메시지 등 구체적으로
- "Key results"에는 사용자가 요청한 완전하고 정확한 출력 포함
- 각 섹션은 ~2000 토큰/단어 이하로 유지
- 중요: 항상 "Current State"를 가장 최근 작업을 반영하도록 업데이트

Edit 도구 사용 시 file_path: {{notesPath}}

다음 세션에서 불러오기

새로 시작하면 과거 메모리가 조용히 로드됩니다. Claude는 멈춘 데서 바로 이어가죠.

터미널에선 안 보이지만, 이런 내용이 주입됩니다:

<session-memory>
이 세션 요약은 현재 작업과 관련 없을 수 있고 오래된 정보일 수 있는
과거 세션에서 온 것입니다. 사용자 메시지가 관련성을 나타내거나 유사한
작업을 참조할 때까지 현재 작업이 이 요약과 관련 있다고 가정하지 마세요.
각 메모리의 미리보기만 표시됩니다 - 세션이 관련될 때 제공된 경로로
Read 도구를 사용해 전체 세션 메모리에 접근하세요.

[과거 세션 메모리 미리보기]
</session-memory>

요점은 — 이전 세션 기억이 알아서 따라온다는 것.

내 맘대로 설정

다른 섹션을 원하시나요? 다른 추출 로직? 둘 다 커스터마이징 가능합니다.

각 섹션은 너무 길어지지 않도록 ~2,000 토큰으로 제한됩니다.

그래서 뭐가 달라지나요

컨텍스트 손실은 Claude Code의 가장 흔한 불만 중 하나였습니다 — 긴 대화는 압축되고, 디테일은 사라지고, 이미 다룬 내용을 다시 설명해야 했습니다.

Session Memory가 이걸 해결합니다 — 세션이 끝나도, 컨텍스트가 압축돼도, 시간이 지나도 살아남는 영구적인 컨텍스트 레이어.

파일은 여러분 것입니다. 디스크에 있고, 일반 마크다운이고, 편집하고 삭제할 수 있습니다. Claude는 거기서 학습하지만, 제어권은 여러분에게 있습니다.

다음: Claude Code에 멀티 에이전트 스웜도 추가됩니다. 계속 지켜봐주세요.

← 목록으로