# Claude Code 메모리 성능 향상 방법 — GitHub 심층 리서치 보고서

**작성일:** 2026-04-05
**작성팀:** dev6-team (페룬 팀장)
**리서치 담당:** 스바로그(MCP/VectorDB), 라다(CLAUDE.md/커뮤니티), 벨레스(Obsidian/공식가이드)

---

## 1. CLAUDE.md 최적화

### 1.1 동작 원리

CLAUDE.md는 시스템 프롬프트 이후에 **user 메시지로 주입**된다. 강제 설정이 아닌 컨텍스트이며, 실질적인 지시 예산은 **~100-150줄** 수준이다(시스템 프롬프트가 이미 ~50줄을 소비).

### 1.2 @import 시스템

CLAUDE.md 내에서 `@path/to/file` 문법으로 외부 파일을 참조하면 세션 시작 시 자동 확장된다.
- 최대 5단계 재귀 지원
- 상대/절대 경로 모두 허용
- HTML 주석(`<!-- -->`)은 제거됨 — 인간 전용 메모 가능 (토큰 비용 0)

```markdown
# CLAUDE.md
See @README for project overview
@package.json contains npm commands
- git workflow @docs/git-instructions.md
```

### 1.3 경로 스코프 규칙 (.claude/rules/)

`.claude/rules/` 디렉토리에 YAML 프론트매터로 경로 매칭 조건을 지정하면, 해당 파일 작업 시에만 컨텍스트에 로드된다.

```markdown
---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
```

**핵심 이점:** 200줄 제한 압박을 경로 기반으로 분산. 모든 규칙을 CLAUDE.md에 넣을 필요 없음.

### 1.4 실전 사례: HumanLayer

- CLAUDE.md를 60줄 미만으로 유지
- 모든 상세 내용은 `agent_docs/` 디렉토리에 포인터 참조
- 핵심 원칙: "would removing this line cause mistakes?" 테스트

### 1.5 파일 계층

```
우선순위 (구체적 → 일반):
1. 관리 정책: /etc/claude-code/CLAUDE.md (Linux/WSL)
2. 프로젝트: ./CLAUDE.md 또는 ./.claude/CLAUDE.md
3. 사용자: ~/.claude/CLAUDE.md
4. 로컬 (비공개): ./CLAUDE.local.md (.gitignore 대상)
```

---

## 2. Memory MCP 서버 (5개 구현체)

### 2.1 claude-mem (thedotmack) — 가장 완성도 높은 솔루션

- **GitHub:** https://github.com/thedotmack/claude-mem
- **Stars:** 31,800+
- **스택:** TypeScript + Python, Bun, SQLite WAL + ChromaDB
- **라이선스:** AGPL-3.0

**아키텍처 — 이중 DB 전략:**
```
SQLite → 구조화 데이터 원본 (세션, 관찰, 요약)
ChromaDB → 시맨틱 벡터 검색 (프로젝트 횡단)
```

**5개 Lifecycle Hook:**
- SessionStart: MEMORY.md 생성 + 컨텍스트 주입
- UserPromptSubmit: 프롬프트 카운터 추적
- PostToolUse: 관찰 캡처 → SQLite + ChromaDB 동기화
- Stop/Summary: 세션 요약 생성
- SessionEnd: 세션 완료 마킹

**Progressive Disclosure:** 오래된 관찰은 제목만, 최근 것은 전체 내용 표시.

**토큰 절약:** 3계층 워크플로우(search → timeline → get_observations)로 ~10x 절감

**우리 적용성:** 높음. Hook 캡처 + Progressive Disclosure 패턴 직접 참조 가능. 단, AGPL-3.0 라이선스와 35GB RAM 이슈 검토 필요.

### 2.2 basic-memory (basicmachines-co) — 우리 시스템과 가장 유사

- **GitHub:** https://github.com/basicmachines-co/basic-memory
- **Stars:** 2,800
- **스택:** Python, SQLite + FastEmbed, Markdown 파일

**데이터 구조 (Observation/Relation 패턴):**
```markdown
---
title: "Auth System Design"
type: "decision"
permalink: "auth-system-design"
tags: [backend, security]
---
## Observations
- [decision] JWT over session cookies for stateless scaling #auth
- [constraint] Token expiry set to 15min #security
## Relations
- implements [[User Authentication]]
- requires [[Redis Setup]]
```

**하이브리드 검색:** FTS5 전체 텍스트 + FastEmbed 벡터 유사도 결합.

**우리 적용성:** 매우 높음. Markdown + SQLite 인덱싱은 우리 시스템의 자연 확장. Observation 구조화 포맷 즉시 도입 가능.

### 2.3 claude-memory-mcp (WhenMoon-afk) — 미니멀 설계

- **GitHub:** https://github.com/WhenMoon-afk/claude-memory-mcp
- **Stars:** 64
- **스택:** TypeScript, SQLite FTS5

**3개 도구만 제공 (토큰 효율 최대화):**
- `memory_store`: 자동 요약 + 중요도 점수 + TTL
- `memory_recall`: FTS5 키워드 검색
- `memory_forget`: 소프트 삭제 (감사 이력 보존)

**관련성 스코어링:** 최신성 + 중요도 + 빈도 3요소 하이브리드

**우리 적용성:** 높음. 3-도구 미니멀 접근은 토큰 예산이 제한적인 환경에 적합.

### 2.4 mcp-knowledge-graph (shaneholloman) — JSONL 지식 그래프

- **GitHub:** https://github.com/shaneholloman/mcp-knowledge-graph
- **Stars:** 837
- **스택:** TypeScript, JSONL

Anthropic 공식 memory server의 포크. 엔티티-관계-관찰 트리플렛을 JSONL로 저장.

```jsonl
{"type":"entity","name":"AuthService","entityType":"service","observations":["Handles JWT tokens"]}
{"type":"relation","from":"AuthService","relationType":"requires","to":"RedisService"}
```

**우리 적용성:** 중간. 엔티티 간 관계 추적이 필요한 경우 보조 도구로 활용 가능.

### 2.5 mcp-memory-keeper (mkreyman) — 채널 기반 분류

- **GitHub:** https://github.com/mkreyman/mcp-memory-keeper
- **Stars:** 111
- **스택:** TypeScript, SQLite WAL

Git 브랜치에서 자동으로 토픽 채널을 파생 (예: `feature/auth-system` → `auth-system` 채널). 도구 프로파일로 컨텍스트 오버헤드 조절 (minimal: 8도구, standard: 22도구, full: 38도구).

**우리 적용성:** 중간. 채널 개념은 프로젝트별 메모리 격리에 참고 가능.

---

## 3. 커뮤니티 패턴

### 3.1 claude-diary (rlancemartin) — 자동 학습 루프

- **GitHub:** https://github.com/rlancemartin/claude-diary
- **Stars:** 353
- **스택:** Shell 100%, PreCompact hook

Generative Agents 논문 영감. 3단계: Observation → Reflection → Retrieval

**핵심 워크플로우:**
```
/diary → 세션 내용 분석 → ~/.claude/memory/diary/YYYY-MM-DD-session-N.md 저장
/reflect → 누적 다이어리 패턴 분석 (2회+ 반복) → CLAUDE.md 자동 업데이트
  6개 카테고리: PR 피드백, 선호도, 설계 결정, 안티패턴, 효율성 교훈, 프로젝트별 패턴
```

**우리 적용성:** 매우 높음. 순수 Shell, 의존성 없음. /reflect가 CLAUDE.md 자동 규칙 추가.

### 3.2 post_compact_reminder (Dicklesworthstone)

- **GitHub:** https://github.com/Dicklesworthstone/post_compact_reminder
- SessionStart 훅 + `compact` 매처로 압축 이후 AGENTS.md/MEMORY.md 재읽기 강제

### 3.3 centminmod/my-claude-code-setup — 메모리 뱅크 아키텍처

- **GitHub:** https://github.com/centminmod/my-claude-code-setup
- **Stars:** 2,200

```
CLAUDE-activeContext.md     # 현재 세션 상태
CLAUDE-patterns.md          # 패턴 카탈로그
CLAUDE-decisions.md         # ADR
CLAUDE-troubleshooting.md   # 알려진 이슈 + 해결책
```

**우리 적용성:** 높음. 주제별 파일 분리 패턴 즉시 도입 가능.

### 3.4 claude_memory (codenamev) — FTS5 + 벡터

- **GitHub:** https://github.com/codenamev/claude_memory
- SQLite FTS5 (97.5% recall@5) + 로컬 벡터 임베딩
- 10x 토큰 절감 via 선택적 주입
- `<no-memory>content</no-memory>` 프라이버시 태그 지원

### 3.5 Auto Dream — 공식 메모리 통합 프로세스

**활성화 조건:** 마지막 통합 이후 24h+ 경과 AND 5개+ 새 세션 누적

**4단계:**
1. Orientation: MEMORY.md 읽기 → 현재 맵 구축
2. Gather Signal: JSONL 세션 파일에서 수정사항/반복/결정 추출
3. Consolidation: 상대→절대 날짜 변환, 모순 제거, stale 삭제, 중복 병합
4. Prune and Index: 200줄 이하 유지 (구식 포인터 제거, 관련성 순 재정렬)

**실제 효과:** 280줄 → 142줄 (깔끔한 인덱스)

---

## 4. Hooks 활용

### 4.1 claude-code-hooks-mastery (disler) — 13개 훅 레퍼런스

- **GitHub:** https://github.com/disler/claude-code-hooks-mastery
- **Stars:** 3,500

**메모리 관련 핵심 훅:**

| 훅 이벤트 | 용도 | 제어 |
|-----------|------|------|
| SessionStart | 컨텍스트 자동 로드 (git status + MEMORY.md) | exit 0 + stdout |
| UserPromptSubmit | 매 프롬프트 전 규칙 주입 (10,000자 cap) | exit 2 = 차단 |
| PreToolUse | MEMORY.md 읽기 전 쓰기 차단 | exit 2 = 차단 |
| PostToolUse | 변경 캡처 | 정보성 |
| Stop | 메모리 쓰기 강제 | exit 2 = 계속 |
| PreCompact | 트랜스크립트 백업 | 정보성 |

**SessionStart 컨텍스트 로딩 패턴:**
```python
import subprocess, json
context = {
    "git_status": subprocess.check_output(["git", "status"]).decode(),
    "recent_commits": subprocess.check_output(["git", "log", "--oneline", "-10"]).decode(),
}
print(json.dumps({"additionalContext": format_context(context)}))
```

**핵심 규칙:**
- exit code 2 = block + stderr를 Claude에 피드백으로 전송
- exit code 0 = proceed; stdout가 컨텍스트로 주입
- `async: true` 플래그로 논블로킹 훅 설정 (로깅, 백업)
- `type: "prompt"` 훅은 Haiku로 경량 판단
- `type: "agent"` 훅은 서브에이전트 (60초 타임아웃, 50턴)

### 4.2 PreCompact 훅 생태계

**패턴 A — 트랜스크립트 백업 (claudefa.st):**
- 3파일: backup-core.mjs + statusline-monitor.mjs + conv-backup.mjs
- 50K 토큰 소비 시 첫 백업, 이후 10K마다 업데이트

**패턴 B — 다이어리 자동 저장 (claude-diary):**
```bash
#!/bin/bash
claude run /diary  # PreCompact에서 자동 실행
```

---

## 5. 옵시디언/지식관리 도구 연동

### 5.1 obsidian-claude-code-mcp (iansinnott)

- **GitHub:** https://github.com/iansinnott/obsidian-claude-code-mcp
- Obsidian 내부 MCP 서버 실행, WebSocket + HTTP/SSE 이중 전송
- Claude Code에서 `/ide` 커맨드로 볼트 연결

### 5.2 obsidian-mcp-tools (jacksteamdev)

- **GitHub:** https://github.com/jacksteamdev/obsidian-mcp-tools
- Smart Connections 플러그인 연동 **시맨틱 검색** 제공
- 키워드가 아닌 의미 기반 볼트 탐색

### 5.3 graphthulhu (skridlevsky) — 37개 도구

- **GitHub:** https://github.com/skridlevsky/graphthulhu
- Logseq + Obsidian 이중 지원
- `.md` 파일 직접 파싱 (Obsidian 미설치도 가능)
- 고아 콘텐츠 탐지, 토픽 클러스터 분석
- **우리 적용성:** 높음. .md 직접 파싱 방식이 우리 파일 기반 시스템과 호환.

---

## 6. 벡터 DB 연동

### 6.1 claude-code-vector-memory (christian-byrne)

- **GitHub:** https://github.com/christian-byrne/claude-code-vector-memory
- **스택:** Python, ChromaDB + sentence-transformers

**하이브리드 스코어링:**
```python
final_score = (semantic_similarity * 0.70) + (recency_score * 0.20) + (complexity_score * 0.10)
```

세션 종료 시 요약 → ChromaDB 저장 → 새 세션에서 시맨틱 검색으로 관련 과거 세션 자동 주입.

### 6.2 engram (199-biotechnologies) — 3중 병렬 검색

- **GitHub:** https://github.com/199-biotechnologies/engram
- **스택:** TypeScript, SQLite FTS5 + Jina v5 + Knowledge Graph

```
BM25 (FTS5) → 정확한 키워드
Jina v5 Semantic → 개념적 유사도 (~9ms/query on M1)
Knowledge Graph → 엔티티 관계 확장
    ↓ Reciprocal Rank Fusion ↓
Ebbinghaus 망각 곡선 시간적 감쇠
```

**성능:** 저장 ~100ms, 검색 ~50ms, 그래프 ~5ms

### 6.3 mem0-mcp-selfhosted (elvismdev) — 완전 자가 호스팅

- **GitHub:** https://github.com/elvismdev/mem0-mcp-selfhosted
- **스택:** Qdrant + Ollama + 선택적 Neo4j

```
텍스트 → LLM 사실 추출 → Ollama 임베딩 (bge-m3 1024dim) → Qdrant 벡터 저장
        → [그래프 활성화 시] Neo4j 엔티티/릴레이션
```

11개 MCP 도구 + 세션 경계 자동화 훅 (`mem0-install-hooks`)

### 6.4 claude-context (zilliztech) — 코드베이스 인덱싱

- **GitHub:** https://github.com/zilliztech/claude-context
- **Stars:** 5,800
- Milvus 하이브리드 검색 (BM25 + dense vectors)
- **~40% 토큰 절감** 효과
- VoyageAI voyage-code-3 코드 특화 임베딩

---

## 7. 자동 컨텍스트 관리

### 7.1 Auto Memory 공식 구조

```
~/.claude/projects/<project>/memory/
├── MEMORY.md          # 인덱스 (200줄 또는 25KB 제한)
├── debugging.md       # 토픽 파일 (온디맨드 로드)
└── api-conventions.md
```

- MEMORY.md 첫 200줄만 세션 시작 시 자동 로드
- `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`로 비활성화
- `autoMemoryDirectory` 설정으로 커스텀 경로

### 7.2 서브에이전트 메모리 스코프

```yaml
---
name: project-memory-agent
description: 프로젝트 패턴과 결정 추적
memory: project  # user | project | local
---
```

| 스코프 | 경로 | Git 커밋 | 용도 |
|--------|------|---------|------|
| user | ~/.claude/agent-memory/<name>/ | X | 전 프로젝트 공통 |
| project | .claude/agent-memory/<name>/ | O | 팀 공유 |
| local | .claude/agent-memory-local/<name>/ | X | 개인 |

### 7.3 marble_origami 내부 압축

Claude Code 내부적으로 오래된 상세 도구 결과를 자동 압축 (3턴 이전의 500줄 출력 → 짧은 표현으로 축약).

---

## 8. Anthropic 공식 가이드

### 8.1 공식 메모리 문서

- **URL:** https://code.claude.com/docs/en/memory

| | CLAUDE.md | Auto Memory |
|--|--|--|
| 작성자 | 사용자 | Claude |
| 내용 | 지시와 규칙 | 학습과 패턴 |
| 로드 | 매 세션 전체 | 첫 200줄/25KB |

### 8.2 Anthropic 팀 실사용

- 인프라팀: CLAUDE.md로 데이터 파이프라인 의존성 파악
- 보안팀: 다수 문서를 마크다운 런북으로 통합
- 디자인팀: 자율 루프 (코드→테스트→반복)

---

## 9. 우리 시스템 적용 평가

### 현재 시스템

파일 기반 MEMORY.md 인덱스 + 프론트매터 (type: user/feedback/project/reference). 이는 Anthropic 공식 Auto Memory와 동일한 구조.

### 적용 가능성 종합 평가

| 기법 | 출처 | 적용성 | 구현 복잡도 | 효과 |
|------|------|--------|-----------|------|
| .claude/rules/ 경로 스코핑 | 공식 | 매우 높음 | 낮음 | 높음 |
| @import 계층 구조 | 공식 | 매우 높음 | 낮음 | 중간 |
| SessionStart 훅 컨텍스트 로드 | hooks-mastery | 매우 높음 | 낮음 | 높음 |
| PreCompact 훅 자동 백업 | claude-diary | 매우 높음 | 낮음 | 높음 |
| /diary + /reflect 자동 학습 | claude-diary | 매우 높음 | 낮음 | 매우 높음 |
| 메모리 파일 분리 아키텍처 | centminmod | 높음 | 낮음 | 중간 |
| Observation/Relation 구조화 | basic-memory | 높음 | 중간 | 높음 |
| SQLite FTS5 인덱싱 | claude-memory-mcp | 높음 | 중간 | 높음 |
| ChromaDB 시맨틱 검색 | vector-memory | 높음 | 중간 | 매우 높음 |
| Ebbinghaus 시간적 감쇠 | engram | 중간 | 중간 | 중간 |
| 완전 MCP 메모리 서버 도입 | claude-mem | 중간 | 높음 | 매우 높음 |
| 지식 그래프 (Neo4j) | mem0-selfhosted | 낮음 | 높음 | 중간 |

---

## 10. 추천 Top 3 방안

### Top 1: Hook 기반 자동 컨텍스트 관리 (즉시 적용)

**구현 복잡도:** 낮음 (settings.json 수정 + Shell 스크립트 2-3개)
**예상 효과:** 세션 간 컨텍스트 손실 80% 감소

**실행 내용:**
1. SessionStart 훅: MEMORY.md 핵심 섹션 + git status 자동 주입
2. PreCompact 훅: /diary 자동 실행으로 세션 요약 보존
3. Stop 훅: 메모리 쓰기 강제 (exit 2 패턴)
4. .claude/rules/ 경로 스코핑으로 200줄 제한 분산

**참조 구현체:**
- claude-code-hooks-mastery (disler)
- claude-diary (rlancemartin)
- post_compact_reminder (Dicklesworthstone)

### Top 2: basic-memory 패턴 도입 (중기)

**구현 복잡도:** 중간 (Python 스크립트 + SQLite 인덱서)
**예상 효과:** 메모리 검색 정확도 3-5x 향상

**실행 내용:**
1. Observation/Relation 구조화 포맷 도입 (`[category] content #tag`)
2. memory/ 파일들을 SQLite FTS5로 인덱싱하는 스크립트 작성
3. 인덱스 기반 키워드 검색 MCP 도구 구현 (3개: store, recall, forget)
4. FastEmbed 벡터 검색 추가 (FTS5와 하이브리드)

**참조 구현체:**
- basic-memory (basicmachines-co)
- claude-memory-mcp (WhenMoon-afk)

### Top 3: claude-mem 핵심 패턴 선택 도입 (장기)

**구현 복잡도:** 높음 (Worker 서비스 + 이중 DB)
**예상 효과:** 10x 토큰 절감, 완전 자동 메모리

**실행 내용:**
1. SQLite + ChromaDB 이중 DB 아키텍처
2. PostToolUse 훅으로 비동기 관찰 캡처
3. Progressive Disclosure (오래된 것은 제목만, 최근 것은 전체)
4. AI 기반 세션 요약 압축

**주의:** AGPL-3.0 라이선스, 복잡도 높음 → 핵심 패턴만 선택 도입 권장

**참조 구현체:**
- claude-mem (thedotmack)
- engram (199-biotechnologies)

---

## 부록: 전체 리서치 소스 목록

### MCP 메모리 서버
- [claude-mem](https://github.com/thedotmack/claude-mem) — 31.8K stars, SQLite+ChromaDB 이중 DB
- [basic-memory](https://github.com/basicmachines-co/basic-memory) — 2.8K stars, Markdown+SQLite+FastEmbed
- [mcp-knowledge-graph](https://github.com/shaneholloman/mcp-knowledge-graph) — 837 stars, JSONL 지식 그래프
- [mcp-memory-keeper](https://github.com/mkreyman/mcp-memory-keeper) — 111 stars, 채널 기반 분류
- [claude-memory-mcp](https://github.com/WhenMoon-afk/claude-memory-mcp) — 64 stars, 3도구 미니멀
- [memorious-mcp](https://github.com/cedricvidal/memorious-mcp) — ChromaDB 기반 시맨틱
- [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) — REST API 하이브리드

### 벡터 DB 연동
- [claude-code-vector-memory](https://github.com/christian-byrne/claude-code-vector-memory) — ChromaDB 세션 검색
- [engram](https://github.com/199-biotechnologies/engram) — BM25+ColBERT+KG 3중 검색
- [claude-context](https://github.com/zilliztech/claude-context) — 5.8K stars, Milvus 하이브리드
- [mem0-mcp-selfhosted](https://github.com/elvismdev/mem0-mcp-selfhosted) — Qdrant+Ollama 자가호스팅
- [mcp-vector-search](https://github.com/bobmatnyc/mcp-vector-search) — LanceDB AST 파싱

### 커뮤니티 패턴
- [claude-diary](https://github.com/rlancemartin/claude-diary) — /diary+/reflect 자동 학습
- [claude-code-hooks-mastery](https://github.com/disler/claude-code-hooks-mastery) — 3.5K stars, 13개 훅 레퍼런스
- [my-claude-code-setup](https://github.com/centminmod/my-claude-code-setup) — 2.2K stars, 메모리 뱅크
- [post_compact_reminder](https://github.com/Dicklesworthstone/post_compact_reminder) — 압축 후 재읽기 강제
- [claude_memory](https://github.com/codenamev/claude_memory) — FTS5+벡터 10x 절감

### Obsidian/지식관리
- [obsidian-claude-code-mcp](https://github.com/iansinnott/obsidian-claude-code-mcp) — 볼트 MCP 연결
- [obsidian-mcp-tools](https://github.com/jacksteamdev/obsidian-mcp-tools) — 시맨틱 검색
- [graphthulhu](https://github.com/skridlevsky/graphthulhu) — 37도구, Logseq+Obsidian

### 큐레이션 목록
- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code)
- [awesome-claude-code-toolkit](https://github.com/rohitg00/awesome-claude-code-toolkit)
- [Awesome-Claude-MCP-Servers](https://github.com/win4r/Awesome-Claude-MCP-Servers)
- [awesomeclaude.ai](https://awesomeclaude.ai/mcp/knowledge-memory)

### 공식 문서
- [How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Create custom subagents](https://code.claude.com/docs/en/sub-agents)
- [How Anthropic teams use Claude Code](https://claude.com/blog/how-anthropic-teams-use-claude-code)
- [Automate workflows with hooks](https://code.claude.com/docs/en/hooks-guide)
- [Auto Dream 분석](https://claudefa.st/blog/guide/mechanics/auto-dream)
- [Claude Code Memory: 4 Layers](https://dev.to/chen_zhang_bac430bc7f6b95/claude-codes-memory-4-layers-of-complexity-still-just-grep-and-a-200-line-cap-2kn9)