AI 코딩 에이전트의 기억력: memory.md 패턴

개요

2025년부터 AI 코딩 에이전트들이 본격적으로 도입되면서, 세션 간 컨텍스트를 유지하는 방법이 중요한 과제로 떠올랐다. 

memory.md는 이 문제를 해결하기 위해 등장한 패턴으로, AI가 프로젝트에 대해 학습한 내용을 마크다운 파일에 저장하고 다음 대화에서 자동으로 불러오는 방식이다.

왜 필요한가?

LLM 기반 코딩 에이전트는 대화가 끝나면 모든 컨텍스트를 잃는다. 매번 새 세션마다 동일한 설명을 반복해야 하는 문제가 있다.

• "이 프로젝트는 bun을 사용해"
• "커밋 메시지는 한글로 작성해"
• "테스트는 vitest로 실행해"

memory.md는 이런 정보를 파일 시스템에 영속적으로 저장하여 AI가 매 세션 시작 시 자동으로 참조하게 한다.

주요 도구별 구현

도구파일명위치

Claude Code	CLAUDE.md, memory/MEMORY.md	프로젝트 루트 또는 ~/.claude/
Cursor	.cursorrules, .cursor/rules/	프로젝트 루트
Windsurf	.windsurfrules	프로젝트 루트
GitHub Copilot	.github/copilot-instructions.md	프로젝트 루트
Cline	.clinerules, memory-bank/	프로젝트 루트

Claude Code에서의 memory.md

Claude Code는 두 가지 레벨의 메모리를 제공한다.

1. CLAUDE.md — 프로젝트 지침서 (수동)

사용자가 직접 작성하는 프로젝트 규칙 파일. 매 대화 시작 시 자동으로 컨텍스트에 주입된다.

# Project Rules
- 패키지 매니저: bun
- 커밋 메시지: 한글, Conventional Commits
- 테스트: vitest

2. memory/MEMORY.md — AI 자동 메모리 (자동)

AI가 대화 중 발견한 패턴, 사용자 선호도 등을 스스로 기록/갱신한다. 다음 세션에서 자동 로드되어 컨텍스트로 활용된다.

# 프로젝트 구조
- src/mcp-servers/: MCP 서버 구현체들
- 사용자는 Jira 연동을 자주 사용함

# 사용자 선호
- 응답은 한국어
- git push 전 항상 확인 요청

핵심 설계 원칙

1. 의미 기반 정리 — 시간순이 아닌 토픽별로 구조화
2. 간결성 — 200줄 이내로 유지 (컨텍스트 윈도우 절약)
3. 검증된 정보만 저장 — 한 번의 관찰이 아닌 반복 확인된 패턴만
4. 중복 방지 — 새로 쓰기보다 기존 메모리를 업데이트
5. 별도 파일 분리 — 상세 내용은 debugging.md, patterns.md 등으로 분리

이 패턴이 의미하는 것

memory.md는 단순한 설정 파일이 아니라, AI 에이전트에게 장기 기억(Long-term Memory)을 부여하는 경량 패턴이다.

RAG나 벡터 DB 같은 복잡한 인프라 없이, 마크다운 파일 하나로 세션 간 연속성을 확보할 수 있다는 점에서 실용적이다.

앞으로 AI 코딩 에이전트가 더 널리 쓰이면서, 이 패턴은 "프로젝트에 .gitignore를 두는 것처럼 당연한 관행"이 될 가능성이 높다.