
MadoHub에 영구 기억(Memory)을 부여하는 방법: 설계 철학과 인간 검증 방어선
MadoHub 장기 기억 시스템의 내부 구조를 살펴봅니다: 6가지 원자적 기억 유형, 페르소나 및 워크스페이스 네임스페이스 격리, 그리고 '인간의 승인을 거치지 않은 기억은 결코 영구화되지 않는다'는 핵심 원칙.
대부분의 AI 에이전트 세션은 빈 도화지에서 시작됩니다. 월요일에 Claude Code에게 "이 프로젝트는 npm이 아니라 pnpm을 사용한다"고 분명히 전달했더라도, 목요일에 새 세션을 열면 그 중요한 합의는 흔적도 없이 사라져 있습니다. 매번 같은 프롬프트를 반복해서 입력하지 않는 한 말입니다.
이 문제를 해결하기 위해 MadoHub가 지난 몇 번의 릴리스에 걸쳐 구축해 온 핵심 기능이 바로 세션과 프로젝트를 초월하여 지속되는 장기 메모리(Memory) 시스템입니다. 이 시스템은 에이전트에게 경험을 기록하고 계승할 수 있는 능력을 부여합니다.
이 글에서는 이 메모리 시스템이 구축된 과정과 그 중심에 자리 잡은 가장 중요한 설계 결정을 공유합니다: 모델이 자동으로 추출한 기억 후보는 인간이 직접 승인하기 전까지 결코 실제 영구 기억이 될 수 없습니다.
MadoHub의 아키텍처 접근법
1. 6가지 원자적 메모리 유형 (Kind)
모호한 자유 서식 태그로 인한 데이터 오염을 막기 위해, MadoHub의 메모리 항목은 엄격히 다음 6가지 결정론적 유형으로만 분류됩니다.
| 유형 (Kind) | 의미 및 역할 | 예시 |
|---|---|---|
preference | 확인된 사용자의 작업 선호도 | "설명은 간결하게, 코드 위주로 응답" |
fact | 프로젝트에 대한 지속적이고 검증 가능한 사실 | "백엔드 서비스는 Node 22 환경에서 구동됨" |
decision | 내린 결정과 그 배경 이유 | "번들 크기와 성능을 고려하여 Electron 대신 Tauri 채택" |
pattern | 프로젝트에서 반복 적용되는 코드 스타일/패턴 | "모든 비동기 호출은 apiClient 미들웨어를 통일 적용" |
postmortem | 장애 분석 및 재발 방지 교훈 | "특정 모듈 수정 시 경계값 회귀 테스트 필수 수행" |
event | 기억해 둘 가치가 있는 주요 프로젝트 마일스톤 | "6월 핵심 아키텍처 개편 완료" |
7번째 모호한 선택지나 자유 텍스트 필드는 존재하지 않습니다. 이는 의도된 제약입니다. Memory Dashboard는 이러한 유형을 바탕으로 필터링과 태그 조회를 수행하므로, 규격화되지 않은 '유령 유형'이 시스템에 침투하는 것을 원천 차단합니다.
2. 네임스페이스를 통한 이중 격리: Persona와 Workspace
기억에는 명확한 유효 범위가 필요합니다.
persona:네임스페이스: 개발자 개인의 작업 성향 및 커뮤니케이션 선호도를 페르소나에 결속시킵니다.workspace:네임스페이스: 특정 리포지토리나 코드베이스의 고유한 규칙을 해당 프로젝트에 한정시킵니다.
에이전트가 네임스페이스를 지정하지 않고 메모리를 기록하면 활성 페르소나에 기본 귀속됩니다. 기억을 회상할 때에도 특정 프로젝트 네임스페이스로 범위를 좁힐 수 있어, A 프로젝트의 독자적 규칙이 B 프로젝트로 흘러 들어가 혼선을 빚는 일을 방지합니다.
3. 메모리 후보가 생성되는 4가지 경로
개발자가 직접 수동 등록하는 경로 외에도, MadoHub은 백그라운드에서 대화 맥락을 조용히 관찰합니다.
- 명시적 기록 (Explicit Remember): 에이전트가 대화 도중 중요한 규칙임을 인지하고 스스로 기록을 제안합니다.
- 턴 종료 후 스캔 (Post-turn Pass): 각 대화 턴이 끝날 때마다 경량 모델이 직전 교환을 스캔합니다. 많은 유의미한 합의는 의도적인 선언보다 일상적인 피드백 과정에서 자연스럽게 드러나기 때문입니다.
- 컨텍스트 압축 전 구조 (Pre-compaction Rescue): 긴 대화 창이 토큰 절약을 위해 요약되기 직전, 버려질 위기에 처한 메시지들로부터 기억을 적극 추출합니다. 압축은 본질적으로 손실을 수반하므로, 이때 추출하지 못한 맥락은 영구히 사라집니다.
- 대시보드 수동 입력: 개발자가 Settings → Memory에서 언제든 고신뢰도 기억을 직접 등록할 수 있습니다.
4. 인간 검토가 필수적인 이유: 왜 자동 반영하지 않는가?
이것이 시스템의 가장 중요한 방어 원칙입니다. 위의 4가지 경로 중 어느 것도 에이전트가 검색하는 실제 메모리 저장소에 곧바로 쓰이지 않습니다.
추출된 모든 항목은 먼저 '대기(Pending)' 상태의 후보 큐로 들어갑니다. 사람이 직접 내용을 확인하고 승인(Approved)한 항목만이 정식 기억으로 승격되며, 30일간 방치된 항목은 자동으로 보관소로 이동합니다.
이러한 수동 검토가 작업을 지연시킨다고 생각할 수 있지만, 이는 환각의 영구화를 막기 위한 의도적인 브레이크입니다. 만약 모델의 자의적인 판단을 그대로 영구 메모리에 기록하도록 허용한다면, 단 한 번의 잘못된 추론이 이후의 모든 미래 대화에서 반복적으로 회상되어 오류를 복리로 증폭시키게 됩니다.
특히 가중치가 높은 decision과 postmortem 항목의 경우, 잘못된 기억이 초래하는 피해는 기억이 없는 것보다 훨씬 큽니다. 인간 검증은 AI의 일시적 오류가 프로젝트의 영구 지식으로 굳어지는 것을 막는 유일한 방어벽입니다.
실무 권장 사항
- Memory Dashboard를 지식 정제소로 활용하세요: 주기적으로 대기 큐를 살펴보고 타당한 지식들을 승인하세요.
- 고급 자동 승인 옵션 (선택 사항): 동일한 지식이 높은 신뢰도로 여러 차례 독립적으로 관측된 경우에만 자동으로 승격시키는 옵션을 제공하지만, 완벽한 통제를 위해 기본적으로 꺼져 있습니다.
- 자연스러운 대화를 유지하세요: 기억을 만들기 위해 인위적인 프롬프트를 짤 필요 없이 평소처럼 코딩하면, MadoHub가 배후에서 지식을 정제하여 검토 목록에 올려놓습니다.