메모리 시스템

메모리 시스템은 "무엇을 오래 기억할지"를 분리해 다루는 계층형 구조입니다. 자동 메모리는 대화에서 반복되는 선호와 규칙을 뽑아 장기 기억으로 남기고, 세션 메모리는 긴 대화를 압축하며, 팀 메모리는 여러 팀메이트가 공유해야 하는 규칙을 동기화합니다.

• 자동 메모리: 놀랍거나 반복되는 선호, 팀 규칙, 프로젝트 사실을 토픽 파일로 저장
• 세션 메모리: 현재 세션의 긴 문맥을 압축한 요약본
• 팀 메모리: 팀 전체에 적용되는 기억을 서버와 동기화
• 어시스턴트 일지: 어시스턴트 모드에서 최근 작업 흐름을 날짜별로 이어 붙이는 보조 기억

MEMORY.md는 모든 토픽 파일의 짧은 인덱스입니다. 여기에는 각 메모리의 이름, 설명, 연결된 파일 경로가 요약되고, 실제 내용은 개별 토픽 파일에 들어갑니다.

인덱스 크기 제한

• 200줄 / 25KB 캡: 초과 시 자동 압축 대신 잘라내고 경고를 남깁니다
• 역할 분리: 인덱스는 찾기용이고, 세부 내용은 토픽 파일이 담당합니다

토픽 파일 프론트매터 모델

토픽 파일은 name, description, type 세 필드를 중심으로 구성됩니다. 이전 예시처럼 scope나 날짜 필드를 핵심 모델처럼 두는 설명은 맞지 않습니다.

# 토픽 파일 프론트매터 예시
---
name: testing-conventions
description: Use the real database for integration tests unless the user asks for a lighter path.
type: feedback
---

# 테스트 관례
실제 DB를 기본값으로 사용합니다. 목은 속도를 위해 예외적으로만 허용합니다.

메모리는 저장 위치보다 먼저 내용의 성격으로 분류됩니다. 이 타입이 리콜과 병합의 기준이 됩니다.

• user: 개인 작업 선호와 습관. 예: 커밋 메시지 스타일, 선호 언어
• feedback: 반복해서 주어진 수정 요청이나 팀 규칙. 예: 테스트는 실제 DB 우선
• project: 프로젝트 자체의 구조적 사실. 예: 모노레포, 특정 디렉터리 규칙
• reference: 자주 다시 보는 참고 지식이나 문서 연결

저장하지 않는 것

• 코드 패턴과 아키텍처 해설: 현재 코드에서 다시 파생할 수 있고 빨리 낡습니다
• 임시 상태: 이번 주 PR 목록, 잠깐의 TODO, 일회성 진행 상황
• 비밀 정보: 토큰, 비밀번호, 인증서, 키

자동 메모리는 사용자가 매번 다시 설명하지 않아도 될 정보를 대화에서 골라 저장하는 층입니다. 핵심 기준은 "반복 가치가 있는가"와 "다음 세션에서도 도움이 되는가"입니다.

자동 메모리가 잘 잡는 것

• 개인 선호: 답변 언어, 테스트 방식, 작업 순서 선호
• 팀 피드백: 문서 톤, 커밋 규칙, 리뷰 관례
• 프로젝트 사실: 반복해서 참조되는 구조적 제약

자동 메모리가 일부러 피하는 것

• 직접 읽으면 되는 코드 사실: 함수 이름, 파일 내용, 현재 클래스 구조
• 금방 변하는 진행 상황: 오늘 처리한 작업 목록 같은 일시 정보
• 사용자가 명시적으로 파일에 적어둔 기억: 메인 에이전트가 직접 메모리를 쓴 경우 중복 추출을 피합니다

# 자동 메모리의 판단 예시
# 저장 적합
사용자는 문서 설명을 한국어로, 코드 주석은 영어로 유지하길 원한다.

# 저장 부적합
오늘은 src/api/user.ts를 먼저 고쳤다.

# 경계 사례
이번 주에 병합한 PR 목록은 보통 저장하지 않고,
그 안에서 반복되는 규칙이나 놀라운 제약만 추려서 기억한다.

자동 메모리는 대화와 분리된 백그라운드 흐름으로 추출됩니다. 응답 자체를 늦추지 않으면서, 새로 생긴 턴만 커서 기반으로 훑어 메모리 후보를 만들고 필요한 경우 토픽 파일을 갱신합니다.

추출 단계

1. 커서 추적: 마지막으로 처리한 턴 이후만 읽습니다
2. 후보 추출: 반복 가치가 있는 선호와 규칙만 고릅니다
3. 타입 분류: user, feedback, project, reference 중 하나로 분류합니다
4. 토픽 병합: 기존 토픽이 있으면 보강하고, 없으면 새 파일을 만듭니다
5. 인덱스 갱신: MEMORY.md에 새 요약을 반영합니다

메인 에이전트 쓰기와의 상호 배제

메인 에이전트가 같은 범위에서 메모리 파일을 직접 수정했다면, 자동 추출기는 그 범위를 다시 쓰지 않고 건너뜁니다. 명시적 기억 쓰기가 자동 추출보다 우선합니다.

# 추출 파이프라인의 핵심 흐름
cursor -> new conversation turns -> extract candidates -> classify
      -> merge into topic files -> refresh MEMORY.md

# 예외
if main-agent wrote memory files in this range:
  skip range
  advance cursor

리콜

새 세션이 시작되면 관련 메모리만 골라 주입합니다. 모든 메모리를 무조건 다시 넣지 않고, 현재 작업과 맞는 토픽만 선택해 컨텍스트 낭비를 줄입니다.

세션 메모리는 긴 대화에서 이미 지나간 부분을 짧게 압축해 두는 내부 요약입니다. 자동 메모리가 장기 기억이라면, 세션 메모리는 현재 세션 안에서 문맥 손실을 막는 압축 계층에 가깝습니다.

• 12,000 토큰 캡: 무한정 커지지 않게 상한을 둡니다
• 템플릿 기반 요약: 진행 상황, 중요한 결정, 남은 일 중심으로 압축합니다
• 장기 기억과 역할 분리: 세션 메모리 전체가 자동 메모리로 승격되는 것은 아닙니다

팀 메모리는 개인 인스턴스를 넘어서 여러 팀메이트가 같은 규칙을 공유할 수 있게 만듭니다. 변경 감지와 비밀 스캐닝이 함께 들어가며, 로컬 파일만 지운다고 서버의 팀 기억이 사라지지는 않습니다.

• 변경 감지: 파일 해시를 비교해 동기화할 항목을 찾습니다
• 비밀 스캐닝: 민감한 값이 팀으로 퍼지는 것을 막습니다
• 서버 우선 복원: 로컬 삭제만으로는 원격 삭제가 되지 않습니다

어시스턴트 모드의 일일 로그는 자동 메모리와 다른 층입니다. 토픽별 장기 기억을 만들기보다, 최근 며칠의 작업 흐름을 날짜 단위로 이어 두는 작업 일지에 가깝습니다.

일일 로그의 성격

• 날짜별 누적: 같은 날의 작업 흐름이 하나의 로그에 이어집니다
• 최근 맥락 보강: "어제 어디까지 했지"를 빠르게 되살립니다
• 자동 메모리 대체 아님: 선호와 규칙은 여전히 토픽 메모리로 관리됩니다

무엇이 잘못 알려지기 쉬운가

일일 로그는 매 세션 종료마다 독립 파일을 하나씩 찍는 식의 단순 이벤트 로그가 아닙니다. 또한 사용자가 별도 공개 커맨드로 강제 생성하는 개념으로 설명하면 과장됩니다. 핵심은 어시스턴트 모드에서 최근 작업 흐름을 날짜별로 유지하고, 리콜 시 최근 로그를 보조 자료로 함께 본다는 점입니다.

# 일일 로그의 개념적 예시
2026-03-28.md

## 진행 중인 흐름
- 인증 모듈 리팩터링 계속 진행 중
- 테스트 전략은 실제 DB 우선

## 다음에 바로 이어갈 점
- flaky 테스트 2건 재현 필요
- PR 설명 문구를 한국어로 다듬기

메모리 기능은 제품 설정과 관리 정책의 조합으로 제어됩니다. 이전 설명처럼 공개된 CLAUDE_MEMORY=0, --no-memory, 혹은 단일 불리언 설정 하나로 전체 시스템을 끄는 식으로 이해하면 맞지 않습니다.

실제 제어 포인트

• 기능 단위 제어: 자동 메모리, 팀 메모리, 어시스턴트 일지처럼 하위 기능이 따로 동작합니다
• 모드 의존성: 어시스턴트 일지는 어시스턴트 모드일 때만 의미가 있습니다
• 관리 정책 우선: 조직 정책이 있으면 개인 설정보다 먼저 적용됩니다
• 동기화 별도 제어: 팀 메모리를 막아도 세션 메모리까지 함께 사라지는 것은 아닙니다