온톨로지와 메모리 시스템 (5/13) — 3계층 메모리 아키텍처: 도메인·행동·세션

-

전체를 로드하지 않는다 — 키워드 매칭으로 필요한 메모리만 꺼내는 구조

핵심 요약

  • AI 에이전트의 메모리를 3계층으로 분리한다: 도메인 지식(영구), 행동 규칙(승격식), 세션 복원(휘발)
  • 전체 메모리를 한 번에 로드하지 않는다. 키워드 인덱스로 필요한 파일만 선택적으로 읽는다
  • 이 구조는 토큰 낭비를 줄이면서도 에이전트가 과거 경험을 활용할 수 있게 한다

배경

LLM 기반 에이전트의 근본적인 한계는 세션이 끝나면 기억이 사라진다는 것입니다. 매 세션이 첫 만남입니다. CLAUDE.md로 정체성은 유지되지만, "지난번에 조사한 내용", "이전에 실패한 패턴", "두 세션 전에 내린 결정"은 별도 구조 없이는 사라집니다.

파일에 저장하면 되지 않느냐고 할 수 있습니다. 맞습니다. 그런데 파일이 50개가 넘어가면 "어떤 파일을 읽어야 하는가"가 문제가 됩니다. 매 세션 시작 시 50개 파일을 전부 읽으면 컨텍스트의 절반이 메모리로 채워집니다.

필요한 것만, 필요할 때만 로드하는 구조가 필요했습니다. 3계층 메모리 아키텍처는 이 문제에 대한 답입니다.

본문

1. Layer 1: 프로젝트 지식 (docs/) — 영구 기억

docs/ 디렉토리에 저장되는 장기 메모리입니다. 한 번 축적되면 삭제하지 않습니다(No decay).

docs/
├── domain/          # 주제별 도메인 지식
├── references/      # 자주 참고하는 출처/기관 정보
├── patterns/        # 반복 패턴
└── risks/           # 리스크

domain/ — 리서치를 통해 축적된 주제별 지식입니다. AI 에이전트에 대한 글을 여러 번 쓰면, 매번 같은 배경 조사를 반복하는 대신 이전 리서치 결과가 여기에 남습니다.

references/ — 자주 인용하는 출처, 기관, 데이터 소스 정보입니다. "이 기관은 신뢰할 수 있는가", "이 출처의 업데이트 주기는 어떠한가" 같은 메타 정보를 포함합니다.

patterns/ — 반복적으로 나타나는 패턴입니다. "이런 유형의 주장은 대체로 출처가 약하다", "이 분야에서는 이 데이터를 먼저 확인해야 한다" 같은 경험칙입니다.

risks/ — 과거에 검증 실패했던 사례, 주의해야 할 데이터 유형, 흔한 오류 패턴입니다.

각 파일은 50줄 이내로 제한합니다. 50줄을 넘으면 분할합니다. 이유는 단순합니다 — 메모리를 로드할 때 파일 하나가 너무 길면 컨텍스트를 과도하게 소비합니다. 짧은 파일 여러 개가 긴 파일 하나보다 선택적 로딩에 유리합니다.

2. Layer 2: 행동 규칙 (lessons.md) — 경험에서 승격된 규칙

tasks/lessons.md는 에이전트의 행동 규칙 저장소입니다. CLAUDE.md의 규칙이 "설계 시점의 판단"이라면, lessons.md의 규칙은 "운영 중 경험에서 추출된 판단"입니다.

승격 메커니즘:

패턴 1회 관찰 → docs/patterns/에 기록 (관찰)
    ↓
같은 패턴 2회 반복 → lessons.md에 규칙으로 승격
    ↓
2개+ 프로젝트에서 동일 패턴 → 글로벌 메모리로 승격 검토

핵심은 2회 반복이 승격 조건이라는 점입니다. 한 번은 우연일 수 있습니다. 같은 실수를 두 번 하거나, 같은 패턴이 두 번 성공하면 그것은 규칙이 될 자격이 있습니다.

lessons.md의 규칙 예시:

- 수치 데이터는 원본 출처를 추적하지 않으면 2차 요약에서 왜곡되는 경우가 많다
- 팩트체크 시 "상식적으로 맞는 것 같다"는 판단을 내리지 않는다
- 트위터 초안은 한 트윗에 하나의 메시지만 담는다

lessons.md는 매 세션 시작 시 자동으로 로드됩니다. docs/의 파일과 다른 점입니다. docs/는 선택적으로 로드하지만, lessons.md는 항상 로드합니다. 행동 규칙은 어떤 작업을 하든 적용되어야 하기 때문입니다.

3. Layer 3: 세션 복원 (sessions/) — 휘발성 기억

tasks/sessions/에 저장되는 세션 스냅샷입니다. 최신 1개만 유효합니다.

세션이 길어지면 /compact 명령으로 컨텍스트를 압축합니다. 이때 현재 세션의 상태를 스냅샷으로 저장합니다:

## Session Snapshot
- Task: [현재 작업]
- Progress: [완료된 것 / 남은 것]
- Key Decisions: [이번 세션에서 내린 결정]
- Open Questions: [아직 해결 안 된 것]
- Next: [다음 행동]

다음 세션이 시작되면 이 스냅샷을 읽고 작업을 이어갑니다. 새 세션이 시작되면 이전 스냅샷은 자동으로 만료됩니다.

왜 최신 1개만 유효한가? 세션 스냅샷은 "지금 하고 있는 작업"의 맥락입니다. 오래된 세션 스냅샷은 의미가 없습니다. 그 세션에서 얻은 지식이 가치 있다면 Layer 1(docs/)이나 Layer 2(lessons.md)에 이미 승격되어 있어야 합니다.

4. 메모리 로딩 프로토콜 — 전체를 읽지 않는다

이 아키텍처의 핵심은 로딩 전략입니다. "무엇을 저장하느냐"보다 "무엇을 읽느냐"가 더 중요합니다.

세션 시작 시 자동 로드 (항상): - CLAUDE.md (글로벌 + 프로젝트) - tasks/lessons.md (행동 규칙) - tasks/sessions/의 최신 스냅샷 (있으면)

작업 시작 시 선택적 로드:

1. memory-map.md의 키워드 테이블 스캔
2. 현재 작업과 관련된 키워드 매칭
3. 매칭된 파일만 로드
4. 매칭 없으면 → 로드 스킵 (토큰 절약)

이 프로토콜의 규칙은 하나입니다: 전체 카테고리를 한 번에 로드하지 않는다.

"AI 에이전트에 대한 글을 쓴다"고 해서 docs/domain/의 모든 파일을 읽지 않습니다. memory-map.md에서 "AI 에이전트" 키워드에 매핑된 특정 파일만 읽습니다.

5. memory-map.md — 키워드 인덱스

memory-map.md는 메모리 시스템의 색인(index)입니다. 어떤 키워드가 어떤 파일에 매핑되는지를 기록합니다.

## Keyword → File Mapping
| Keyword | Category | File |
|---|---|---|
| AI 에이전트, agent, LLM | domain | docs/domain/ai-agent-landscape.md |
| 팩트체크, 검증, fact-check | patterns | docs/patterns/fact-check-failures.md |
| Blogger, API, 발행 | references | docs/references/blog-agent-config.md |

검색 프로토콜: 1. 키워드 테이블에서 관련 키워드를 찾는다 2. 매칭된 파일만 읽는다 3. 매칭이 없으면 메모리 로딩을 건너뛴다

저장 프로토콜: 1. 새 메모리 파일 생성 시 docs/{category}/에 저장 2. frontmatter에 title, keywords, created, last_used 필수 3. 반드시 memory-map.md에 행을 추가 — 인덱스에 없는 메모리는 존재하지 않는 것과 같다

이 인덱스가 없으면 에이전트는 docs/ 디렉토리를 매번 전체 탐색해야 합니다. 파일이 10개일 때는 괜찮지만, 50개가 넘으면 그 탐색 자체가 토큰을 소모합니다.

6. 토큰 절약 전략 — 왜 이 모든 구조가 필요한가

LLM의 컨텍스트 윈도우는 유한합니다. 메모리에 소비하는 토큰이 늘어나면, 실제 작업에 쓸 수 있는 토큰이 줄어듭니다.

토큰 소비 비교:

전략 세션 시작 시 토큰 소비 문제
전체 로드 모든 docs/ + lessons.md + sessions/ 컨텍스트의 30~50%가 메모리로 채워짐
선택적 로드 lessons.md + 매칭된 docs/ 파일 1~3개 컨텍스트의 5~10%로 충분

차이는 명확합니다. 전체 로드 방식에서는 50개 메모리 파일 x 평균 40줄 = 2000줄이 매 세션 시작 시 컨텍스트에 올라갑니다. 선택적 로드에서는 lessons.md(~30줄) + 매칭 파일 2개(~80줄) = 110줄이면 됩니다.

추가 토큰 절약 규칙: - 이미 읽은 파일은 같은 세션에서 다시 읽지 않는다 - 도구 출력이 50줄을 넘으면 요약만 저장한다 - 메모리 파일은 50줄 상한을 지킨다

설계상 주의사항

  • 행동 규칙은 별도 계층으로 분리해야 한다. docs/에 규칙과 지식이 섞이면 "이건 항상 읽어야 하는 건가, 선택적으로 읽어야 하는 건가?"가 불분명해집니다. 행동 규칙은 항상 읽어야 하고, 도메인 지식은 선택적으로 읽어야 합니다. 성격이 다르면 계층을 나눠야 합니다.

  • memory-map.md 업데이트를 잊으면 메모리가 고아가 됩니다. 파일은 있는데 인덱스에 없으면, 에이전트가 그 파일을 찾지 못합니다. 메모리 저장 시 인덱스 업데이트를 강제하는 규칙이 필요합니다.

  • 세션 스냅샷을 여러 개 유지하는 것은 비효율입니다. "최근 3개를 유지하면 더 풍부한 맥락을 얻을 수 있지 않을까?" — 결과는 세션 복원 시 토큰을 3배 쓰면서 유용한 정보는 거의 늘지 않습니다. 중요한 것은 이미 Layer 1/2에 승격되어 있기 때문입니다.

  • 승격 기준은 2회가 현재 균형점입니다. 1회로 하면 일시적 관찰이 규칙이 되어버리고, 3회로 하면 유용한 규칙이 승격되기까지 너무 오래 걸립니다.

  • 토큰 폭발 사례: OpenClaw 기반 안정 운영 중, 메모리 구조를 전면 재설계한 Hermes로 전환을 시도했습니다. 결과는 토큰 사용량 폭발이었습니다. OpenClaw로 회귀한 후 원인을 분석하고 현재 Hermes를 다시 검증 중입니다(하네스 git PR#12497). 이 사례는 메모리 아키텍처가 토큰 효율에 직접적인 영향을 준다는 것을 보여줍니다.

마무리

3계층 메모리 아키텍처의 핵심은 계층 분리와 선택적 로딩입니다.

  • Layer 1 (docs/) — 영구 지식. 키워드로 검색하여 필요한 것만 로드.
  • Layer 2 (lessons.md) — 행동 규칙. 매 세션 자동 로드. 경험에서 승격.
  • Layer 3 (sessions/) — 세션 복원. 최신 1개만 유효. 휘발성.

전체를 로드하지 않는 원칙만 지키면, 메모리가 100개로 늘어나도 세션 시작 시 토큰 소비는 거의 변하지 않습니다. 에이전트가 과거 경험을 활용하면서도 컨텍스트를 낭비하지 않는 구조입니다.

기억은 양이 아니라 접근성입니다. 많이 기억하는 것보다, 필요한 기억을 빠르게 꺼내는 것이 중요합니다.

시리즈 전체 안내: 시리즈 목차

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »