에이전트 메모리 엔진 (7/10) — 멀티 에이전트 공유 지식 인프라: wikycore와 Knowledge Graph

-

부제: RRF 하이브리드 검색 + 명시 등록 스킬 레지스트리로 중복 작업을 줄이는 구조

핵심 요약

  • 여러 에이전트가 각자의 CLAUDE.md만으로 동작하면 같은 문제를 반복해서 푼다. 이 글은 그 중복을 제거하는 공유 인프라 두 가지의 설계와 작동 원리를 정리한다.
  • wikycore는 공유 문서 저장소(SQLite 기반, 홈서버 호스팅). 벡터(bge-m3, 1024-dim)와 FTS5 키워드를 RRF로 결합한 하이브리드 검색을 제공한다.
  • Knowledge Graph는 "어떤 도메인의 전문가가 누구인가"를 답하는 스킬 레지스트리. 자동 추론 등록과 명시 등록(docPath 필수)을 분리해 신뢰도를 유지한다.
  • 이 글에서 얻어갈 수 있는 것: 하이브리드 검색을 단일 임계값 튜닝 없이 굴리는 방법, 자기평가형 레지스트리의 거품을 막는 운영 규칙, 공유/사적 메모리 경계를 설정하는 기준.

문제 정의 — 공유 메모리 진입점의 부재

여러 에이전트를 병렬 운영할 때 실제로 비용이 발생하는 지점은 모델 토큰이 아니라 중복 작업이다. 한 에이전트가 해결한 OAuth 토큰 갱신 로직을 다른 에이전트가 처음부터 다시 구현하거나, 한쪽이 끝낸 sqlite-vec macOS 빌드 이슈를 다른 쪽이 동일한 에러 메시지로 재검색하는 상황이 반복된다.

원인은 공유 메모리의 부재가 아니라 공유 메모리를 검색할 진입점의 부재다. 각자 docs/에 기록하더라도 외부 에이전트가 그 위치를 발견할 방법이 없으면 사적 메모리에 머문다. 이 진입점 문제를 두 축으로 분리해 해결한다.

시스템 답하는 질문 단위
wikycore "이 주제에 대해 정리된 문서가 있나?" 내용
Knowledge Graph "이 분야의 전문가는 누구인가?" 사람

wikycore — 하이브리드 검색 기반 공유 문서 저장소

홈서버(Mac mini, Tailscale 내부망)에 SQLite로 구성한 위키. 현재 상태는 다음과 같다.

지표 값
docs 다수
chunks (분할) 다수
임베딩 모델 bge-m3 (oMLX, 1024-dim, fp16)
감사 로그 누적 기록
DB 크기 경량 (수 MB 수준)

벡터 단독·키워드 단독의 한계

운영 중 관찰된 실패 패턴은 두 방향에서 대칭적으로 나타났다.

  • 벡터 단독: "OAuth 토큰 갱신" 질의가 "credential rotation" 문서를 놓친다. 의미적으로는 가깝지만 동의어 매칭이 부족할 때 코사인 거리가 임계값을 넘지 못한다.
  • 키워드 단독: "BM25" 질의가 정확히 "BM25"를 포함한 문서만 잡는다. "하이브리드 검색", "랭킹 결합" 같은 인접 개념 문서가 누락된다.

RRF(Reciprocal Rank Fusion) 결합 방식

두 검색기 결과를 Reciprocal Rank Fusion으로 병합한다. 각 검색기에서 문서의 순위 rank를 1 / (k + rank) 점수로 변환해 합산하는 방식이다. 점수 스케일이 다른 벡터 유사도와 BM25 점수를 직접 더하지 않고 순위만 사용하므로 단일 임계값 튜닝이 불필요하다는 것이 주된 이점이다.

API 인터페이스:

POST /api/wiki/search
{"q": "OAuth 토큰 갱신", "k": 10, "mode": "hybrid"}

mode는 hybrid(기본), vector, keyword 세 가지. 후자 둘은 디버깅·품질 검증용이며 운영 트래픽은 hybrid가 처리한다.

Knowledge Graph — 스킬 레지스트리의 구조

wikycore가 "내용"을 인덱싱한다면 Knowledge Graph는 "누가 해당 도메인에 전문성을 등록했는가"를 인덱싱한다. 현재 상태는 다음과 같다.

지표 값
등록된 스킬 다수
등록 에이전트 여러 팀
카테고리 분포 ai, mobile, content, devops, frontend, backend, misc, infra

자동 등록 vs 명시 등록

스킬 등록은 두 계층으로 분리된다.

  • 자동 등록: 프로젝트가 사용하는 언어·프레임워크를 추론해 등록. "Flutter 쓴다" 수준의 메타데이터.
  • 명시 등록: 전문가 수준 + docPath 필드를 요구. "Hive 암호화 파이프라인을 구현했고 문서는 여기에 있다" 수준의 주장.

명시 등록 예시:

에이전트 명시 등록 스킬
마인스위퍼 firebase-auth, flutter-hive-encryption, linear-design-tokens
영상 제작 디렉터 shorts-production-pipeline, comfyui-remote-image-gen, ffmpeg-ken-burns-clip
라우팅 관리 llm-multi-provider-routing, llm-proxy-optimization, oauth-token-lifecycle
글 작성 디렉터 research-verification, blogger-publish-pipeline, content-wiki-synthesis

조회 흐름

새 문제가 도착하면 해당 도메인에 expert로 등록된 에이전트의 docPath를 먼저 읽는다. 직접 해결에 착수하기 전 한 번 조회하는 단계를 추가하는 것이다. 조회 비용이 재구현 비용보다 작다는 전제에서 성립하는 패턴이다.

적용 패턴 — 실제 조회 흐름

블로그 publish 스킬에 ComfyUI 연동을 추가하는 작업을 예로 들면 호출 순서는 다음과 같다.

  1. wikycore 검색: "comfyui SDXL Tailscale" → 영상 제작 디렉터의 comfyui-windows-setup.md 슬러그 반환.
  2. Knowledge Graph 조회: comfyui-remote-image-gen 스킬 보유자 = 영상 제작 디렉터, 레벨 expert.
  3. 해당 에이전트의 docPath를 읽고 호출 패턴을 그대로 재사용.
  4. 새로 추가된 지식은 wikycore에 다시 등록 → 다음 질의는 1단계에서 종결.

즉, Knowledge Graph가 "읽을 문서의 출처"를 지정하고, wikycore가 "그 문서 자체"를 저장한다. 두 시스템은 포인터와 컨텐츠 관계다.

운영 규칙 — 자주 부딪히는 판단 지점

공유(wikycore) vs 사적(docs/) 경계

원칙: 다른 에이전트가 읽었을 때 가치가 있는 도구·유틸리티·패턴이면 wikycore, 프로젝트 내부 컨벤션·작업 로그면 docs/. 판단이 애매하면 "옆 에이전트가 본다고 가정했을 때 의미가 있는가"라는 질문으로 환원한다. 없으면 사적.

자기평가형 레지스트리의 레벨 거품

명시 등록은 본질적으로 자기평가다. 레벨 인플레이션을 막기 위해 운영 규칙에 한 줄을 추가했다 — expert 레벨은 docPath의 파일이 실존해야 한다. 등록 메타데이터는 과장될 수 있어도 참조된 파일의 내용은 검증 가능하다.

문서 stale화

위키 문서는 작성 시점의 사실이다. 코드는 바뀐다. 사용 규칙에 명시한 원칙: 메모리가 코드와 충돌하면 코드를 신뢰한다. 위키는 출발점이지 결론이 아니다. 이 규칙이 없으면 오래된 위키가 적극적으로 잘못된 방향을 가리키는 리스크가 생긴다.

적용 가능 범위와 열린 질문

이 구조는 다음 조건에서 유효하다.

  • 여러 에이전트를 병렬 운영하며 작업 도메인이 부분적으로 겹침.
  • 공유 저장소를 호스팅할 상시 가용 노드가 존재 (홈서버, VPS, 사내망 어디든).
  • 각 에이전트가 공유 API를 호출할 수 있는 권한·네트워크 경로 확보.

반대로 단일 에이전트 또는 완전히 독립된 도메인만 다루는 구성이라면 오버헤드가 이득을 넘을 수 있다.

열린 질문:

  • 위키 stale 검출을 자동화하려면 무엇을 측정해야 하는가 (문서 마지막 참조 일시, 링크된 코드 경로의 최근 커밋 시점 등).
  • Knowledge Graph의 레벨 표기는 자기평가 외에 어떤 신호로 보정 가능한가 (타 에이전트의 참조 빈도를 역신호로 쓸 수 있는가).
  • RRF의 k 파라미터를 도메인별로 자동 조정할 가치가 있는가, 아니면 단일 값으로 충분한가.

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

댓글

댓글 쓰기

이 블로그의 인기 게시물

"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 »