---
id: adr-0002-memory-layer-separation
title: "ADR-0002 5계층 메모리 분리"
category: "Architecture_Decision"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["ADR memory layers", "왜 메모리를 분리", "메모리 계층 결정"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.9
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["adr", "memory", "decision", "ai", "astraai"]
raw_sources: ["AstraAI/src/memory/index.ts", "AstraAI/src/memory/types.ts"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[ADR-0002 5계층 메모리 분리]]

## 🎯 한 줄 통찰 (One-line insight)
에이전트의 "기억"을 단일 저장소가 아니라 **시간 범위·용도가 다른 5계층(단기·장기·프로젝트·절차·일화)**으로 분리하기로 결정했다 — 계층마다 검색·만료·승급 정책이 달라야 하기 때문 [S1].

## 🧠 핵심 개념 (Core concepts)
- **결정:** MemoryManager 가 5개 독립 계층을 보유, 각 계층이 query 에 대해 관련도를 매겨 컨텍스트에 합침.
- 구현 상세는 [[5계층 메모리 시스템]] 참조.

## 📖 세부 내용 (Details · ADR)
### Problem
모든 기억을 한 통에 넣으면 "현재 대화"·"사용자 영구 취향"·"프로젝트 결정"·"반복 절차"·"과거 세션 요약"이 같은 정책으로 다뤄진다. 그러나 이들은 수명·만료·우선순위·검색 방식이 전부 다르다 [S1].

### Context
- 로컬 작은 모델은 컨텍스트 한도가 작아, 무엇을 넣을지 *정교한 선별* 이 필수.
- 시한부 지식(분기 계획)과 영구 지식(사용자 선호)이 공존.
- 과거 세션을 "지난번에 한 일"로 떠올릴 수 있어야 한다.

### Options Considered
1. **단일 메모리 버퍼(최근 N 메시지)** — 단순하나 장기·프로젝트·절차 기억 불가.
2. **벡터 DB 단일 저장** — 의미 검색은 좋지만 만료·승급·계층별 정책 표현이 어렵고 인프라 부담.
3. **역할별 5계층 분리 + 통합 매니저** — 계층별 정책 + 단일 진입점.

### Chosen Solution
3번. 단기(FIFO)·장기(category/confidence/expiresAt)·프로젝트(workspace별 ADR/버그)·절차(trigger→steps)·일화(세션 요약, distillation 승급) [S1][S2].

### Why It Was Chosen
계층마다 다른 정책을 자연스럽게 표현(만료, 승급, lazy 생성). 컨텍스트 예산이 빠듯한 작은 모델에 "관련도 높은 계층부터" 선별 주입 가능. 인간 인지 메타포로 이해·확장 용이.

### Benefits
정밀한 컨텍스트 선별, 시한부/영구 지식 공존, 일화→장기 증류로 자동 정리, RAG 소스로 통합 가능.

### Drawbacks
계층 경계의 모호성(장기 decision vs 프로젝트 ADR), 매니저 조립 복잡도, 계층별 저장 파일 증가.

### Future Risks
계층이 더 늘면(예: 감정/사회적 기억) 관리 폭증. 관련도 점수가 휴리스틱이라 잘못 선별 시 핵심 기억 누락 가능.

### Alternative Approaches
의미 검색이 핵심이면 각 계층 *내부* 에 임베딩을 도입(하이브리드)하거나, 계층 수를 3개(작업·세션·영구)로 단순화. 대규모면 벡터 DB + 메타데이터 필드로 계층을 표현.

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
계층이 많을수록 표현력은 커지나 "어디에 저장할지" 결정 비용도 커진다 — 명확한 분류 규칙([[아키텍처 휴리스틱]])이 없으면 오히려 혼란.

## 🛠️ 적용 사례 (Applied in summary)
`AstraAI/src/memory/index.ts`, `types.ts` [S1][S2].

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[AstraAI 아키텍처 개요]]
- **관련 개념:** [[5계층 메모리 시스템]], [[Memory Pattern]], [[아키텍처 휴리스틱]], [[엔지니어링 트레이드오프 분석]]
- **참조 맥락:** 로컬 LLM 이 에이전트 메모리 구조를 설계할 때 "한 통 vs 계층 분리" 판단에 참조.

## 📚 출처 (Sources)
- [S1] AstraAI/src/memory/index.ts — MemoryManager 5계층 통합
- [S2] AstraAI/src/memory/types.ts — 계층별 타입·만료·승급 필드

## 📝 변경 이력 (Change history)
- 2026-06-13: AstraAI 코드 분석 기반 ADR 작성.
