MEMORY.md 운영 원칙

한 줄 정의

AI 에이전트의 장기적인 컨텍스트 유지를 위해, 아키텍처 결정 사항, 지식 자산, 제약 사항 및 시행착오(Dead Ends)를 마크다운 기반으로 정리하여 세션 로드 시 자동 반영하는 지식 보존(Knowledge Persistence) 운영 매뉴얼이다.

핵심 요지

1. 장기 지식 보존: 임시 TODO나 일회성 로그를 철저히 배제하고, 여러 세션에 걸쳐 유효할 기술적 결정 배경 및 아키텍처 맥락을 집중 아카이빙한다.
2. 지식(WHAT)과 지침(HOW)의 격리: CLAUDE.md가 에이전트가 어떻게 준수해야 할지 지침(HOW)을 담는 운영 매뉴얼이라면, MEMORY.md는 에이전트가 무엇을 알고 있어야 할지 프로젝트 상태와 결정(WHAT)을 보존한다.
3. 세션 자동 로딩: 대화가 시작될 때마다 MEMORY.md 파일의 앞부분 200줄 또는 25KB 용량 중 먼저 도달하는 분량을 자동으로 로드하여 에이전트의 단기 기억상실 한계를 극복하고 빠른 컨텍스트 정합성을 제공한다.
4. 자동 메모리 설정: autoMemoryEnabled: true 설정을 활용하여 AI 에이전트가 핵심 정보를 스스로 기록하도록 관리하되, 정기적인 정리(Prune)를 통해 노이즈를 걸러낸다.

상세

1. MEMORY.md의 디렉터리 아키텍처

기본적인 설정과 인덱스는 프로젝트 루트가 아니라 별도의 전역 에이전트 프로젝트 공간 하위 디렉터리 내에 위치한다.

• 디렉터리 구조:

  ~/.claude/projects/<project>/memory/
  ├── MEMORY.md          # 모든 세션 시작 시 로드되는 간결한 전체 인덱스 파일
  ├── debugging.md       # 디버깅 패턴에 대한 상세 로그
  ├── design-conventions.md # UX/UI 디자인 결정 사항
  └── ...                # 기타 에이전트가 자동 생성하는 주제별 파일
  

• 인덱스 작동: MEMORY.md 파일은 전체 memory 디렉터리의 허브/색인 역할을 하며, AI 에이전트가 새 파일의 존재와 위치를 빠르게 추적할 수 있도록 돕는다.
• 설정 활성화: .clauderc 또는 설정 JSON 파일에 아래와 같이 구성하여 자동 기록 기능을 켠다.

  {
    "autoMemoryEnabled": true
  }

2. CLAUDE.md 대 MEMORY.md 역할 비교

구분	CLAUDE.md (운영 규칙)	MEMORY.md (지식 보존)
핵심 성격	에이전트가 어떻게(HOW) 동작해야 하는지 지시	에이전트가 무엇을(WHAT) 기억하고 있어야 하는지 보존
주요 내용	기술 스택, 컴포넌트 크기 제약, 테스트 지침, 선호 도구, 출력 포맷	아키텍처/제품 결정 사항, 기술적 교훈, 제약 사항, 실패한 시행착오
작성 주체	주로 사람이 작성 및 고정	에이전트가 세션 완료 시 자동 업데이트 (autoMemoryEnabled: true)
구체적 예시	Next.js 사용, 컴포넌트 250줄 이하 제한, 유효성 검사에 Zod 활용 등	Stripe 웹훅 Edge 함수 타임아웃 해결을 위해 AWS Lambda 우회 등

3. MEMORY.md 운영 모범 사례 (5대 수칙)

1. 장기적 가치를 지닌 지식만 저장: “한 달 후에도 이 정보가 여전히 유효할 것인가?”를 판단 기준으로 삼는다. 단기 TODO, 일회성 리팩토링 로그, 수명이 짧은 실험적 시도는 철저히 배제한다.
2. 운영 지침(Operational Instructions) 배제: 에이전트에게 “항상 TypeScript를 써라”와 같은 명령형 규칙은 CLAUDE.md에 선언하고, MEMORY.md에는 “Supabase 마이그레이션이 완료됨”과 같은 지식/사실적 정보를 기술한다.
3. WHAT뿐 아니라 WHY(추론 과정) 설명: 단순 “Redis로 전환함” 대신 “서버리스 콜드 스타트로 인한 메모리 리셋 세션 불안정을 피하기 위해 Redis로 전환함”과 같이 의사결정의 컨텍스트를 제공한다.
4. 간결한 구조 유지: AI 에이전트가 효율적으로 구문을 파싱할 수 있도록 글머리 기호(불릿), 짧고 명확한 구조화 섹션으로 작성하며, 방대한 줄글 에세이는 피한다.
5. 시행착오(Dead Ends) 기록: 시도했으나 모바일 연결 신뢰성 등 다양한 부작용으로 인해 취소한 설계나 실패 사례를 기록하여, 미래에 동일한 오동작이나 실패 방안을 시도하지 않도록 제약한다.

예시

• MEMORY.md 템플릿:

  # 프로젝트 메모리 (MEMORY.md)
   
  ## 제품/아키텍처 결정 사항
  - 2026년 3월: 벤더 종속을 방지하기 위해 Firebase에서 Supabase로 마이그레이션 완료.
  - 다크 모드 채택률이 70% 이상이므로, UI 컴포넌트 추가 시 다크 모드를 우선 대응한다.
   
  ## 알려진 기술 제약
  - 분석 API 호출 제한은 분당 최대 100회로 고정되어 있음.
  - Vercel Edge Functions 환경에서 Stripe 결제 웹훅 타임아웃(10초 초과) 문제가 확인되어 전용 서버리스 람다로 우회 적용함.
   
  ## 시행착오 (Dead Ends)
  - **WebSocket 실시간 알림**: 모바일 저전력/슬립 모드 진입 시 연결 재수립 실패율이 40%에 달해 도입을 반려하고, HTTP 2 Server-Sent Events(SSE)로 전면 선회함.

충돌

• 자동 메모리 갱신 vs 컨텍스트 오버헤드:
  • autoMemoryEnabled: true로 설정할 경우 에이전트가 매 세션 종료 시마다 메모리를 자동으로 갱신하여 지식 누락을 줄인다. 그러나 필터링 없이 너무 많은 시도와 디버깅 이력이 기록되면 25KB 용량 제한을 초과하고 노이즈(Context Rot)가 늘어나게 된다.
  • 해결책: 30일 주기로 인간 개발자가 쓸모없어진 가정, 이미 완전히 해결된 골칫거리, 레거시 아키텍처 정보를 린팅하고 리팩토링하여 고농도 응축 메모리를 유지해야 한다.

관련 노트

• Claude.md 운영 원칙
  • 에이전트 세션의 규칙 및 개발 표준을 고정하는 원칙과의 상호 관계.
• Agent Harness
  • 에이전트의 실행 컨텍스트와 영구 메모리(Memory layer)를 바인딩하는 구조.
• Context Engineering
  • 에이전트 세션 개시 시 적절한 컨텍스트 정보를 주입하고 소음을 줄이는 기술.
• Claude Code 스킬 관리
  • 로컬 환경의 스키마와 토큰 캐싱을 조율하는 관리 원칙.