Roampal — 결과 기반 영구 메모리 MCP 서버

왜 필요한가요?

AI 코딩 어시스턴트는 세션이 종료되면 모든 것을 잊어버립니다. 아키텍처, 선호도, 규칙 등을 매번 다시 설명해야 합니다. AI가 잘못된 조언을 해도 이를 통해 학습할 메커니즘이 없습니다.

Roampal은 모든 세션에 걸쳐 AI에게 영구적인 결과 기반 메모리를 제공하는 MCP 서버입니다. 좋은 조언은 승격되고, 나쁜 조언은 강등됩니다. 워크플로우 변경 없이 자동으로 AI가 무엇이 효과적이고 무엇이 그렇지 않은지 학습합니다.

벤치마크

LoCoMo에서 85.8% (비적대적, 엔드투엔드 답변 정확도) — 10개의 대화에 걸친 1,986개의 질문에 대해 이중 채점 방식으로 검증되었습니다.

결과	점수
대화형 학습 vs 원시 데이터 주입	+23 포인트 (76.6% vs 53.0%, p<0.0001)
아키텍처 vs 모델 효과	아키텍처가 ~10배 더 큰 기여
독성 저항력 (1,135개의 적대적 메모리)	-2.6 ~ -4.2 포인트 감소에 그침
TagCascade 검색 (태그 우선 + CE 재순위 지정)	+1.9 Hit@1 (순수 CE 대비, p<0.0001)

벤치마크 파이프라인은 클라우드 의존성 없이 단일 GPU에서 실행됩니다. Roampal 자체는 CPU에서 실행되므로 GPU가 필요하지 않습니다. 전체 방법론, 데이터 및 평가 스크립트는 roampal-labs에서 확인하세요.

논문: "Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark" (Logan Teague, 2026년 4월)

빠른 시작

pip install roampal
roampal init

설치된 도구를 자동으로 감지합니다. 에디터를 재시작하고 대화를 시작하세요.

특정 도구 타겟팅: roampal init --claude-code 또는 roampal init --opencode

핵심 루프는 동일합니다. 두 플랫폼 모두 컨텍스트를 주입하고, 교환 내용을 캡처하며, 결과를 점수화합니다. 전달 메커니즘은 다음과 같이 다릅니다:

	Claude Code	OpenCode
컨텍스트 주입	후크 (stdout)	플러그인 (시스템 프롬프트)
교환 캡처	정지 후크	플러그인 `session.idle` 이벤트
점수화	`score_memories` 도구를 통한 메인 LLM	독립적인 사이드카 (선택한 모델 > Zen 무료)
자가 치유	실패 시 후크가 서버 자동 재시작	실패 시 플러그인이 서버 자동 재시작

Claude Code는 메인 LLM이 score_memories 도구를 통해 각 교환을 점수화하도록 프롬프트를 보냅니다. OpenCode는 스스로 점수화하지 않으며, 독립적인 사이드카(별도의 API 호출)가 제3자로서 각 교환을 검토하여 자가 평가 편향을 제거합니다. score_memories 도구는 OpenCode에 등록되지 않습니다. roampal init 또는 roampal sidecar setup 중에 Roampal은 로컬 모델(Ollama, LM Studio 등)을 감지하여 점수화 모델을 선택할 수 있게 합니다. 설정된 경우, 이 모델들이 우선순위를 갖습니다(개인정보 보호를 위해 Zen은 건너뜁니다). 저렴하거나 로컬 모델도 충분히 잘 작동합니다. 점수화에는 강력한 모델이 필요하지 않습니다. 설정을 건너뛰면 기본적으로 Zen 무료 모델(원격, 최선 노력)이 사용됩니다.

작동 방식

메시지를 입력하면 Roampal이 AI가 보기 전에 관련 컨텍스트를 자동으로 주입합니다:

사용자 입력:

fix the auth bug

AI가 보는 내용:

═══ KNOWN CONTEXT ═══
• JWT refresh pattern fixed auth loop [id:patterns_a1b2] (3d, 90% proven, patterns)
• User prefers: never stage git changes [id:mb_c3d4] (memory_bank)
═══ END CONTEXT ═══

fix the auth bug

수동 호출이나 워크플로우 변경이 필요 없습니다. 그냥 작동합니다.

루프

사용자 입력 메시지
Roampal 주입 관련 컨텍스트 자동 (Claude Code의 후크, OpenCode의 플러그인)
AI 응답 기록, 선호도, 이전 성공 사례를 완전히 인식한 상태로 응답
결과 점수화 — 좋은 조언은 승격, 나쁜 조언은 강등
반복 — 모든 교환마다 시스템이 더 똑똑해짐

5가지 메모리 컬렉션

컬렉션	목적	수명
`working`	현재 세션 컨텍스트	24시간 — 유용하면 승격, 아니면 삭제
`history`	과거 대화	30일, 결과 점수화됨
`patterns`	검증된 솔루션	유용한 동안 영구 유지, 기록에서 승격
`memory_bank`	정체성, 선호도, 목표	영구
`books`	업로드된 참조 문서	영구

명령어

roampal init                # Auto-detect and configure installed tools
roampal init --claude-code  # Configure Claude Code explicitly
roampal init --opencode     # Configure OpenCode explicitly
roampal init --no-input     # Non-interactive setup (CI/scripts)
roampal start               # Start the HTTP server manually
roampal stop                # Stop the HTTP server
roampal status              # Check if server is running
roampal status --json       # Machine-readable status (for scripting)
roampal stats               # View memory statistics
roampal stats --json        # Machine-readable statistics (for scripting)
roampal doctor              # Diagnose installation issues
roampal summarize           # Summarize long memories (retroactive cleanup)
roampal score               # Score the last exchange (manual/testing)
roampal context             # Output recent exchange context
roampal ingest <file>       # Add documents to books collection
roampal books               # List all ingested books
roampal remove <title>      # Remove a book by title
roampal sidecar status      # Check scoring model configuration (OpenCode)
roampal sidecar setup       # Configure scoring model (OpenCode)
roampal sidecar test        # Test scoring model response format (OpenCode)
roampal retag               # Re-extract tags on memories using sidecar LLM
roampal sidecar disable     # Remove scoring model configuration (OpenCode)

MCP 도구

AI는 다음과 같은 메모리 도구를 얻게 됩니다:

도구	설명	플랫폼
`search_memory`	모든 컬렉션에 걸친 심층 검색	둘 다
`add_to_memory_bank`	영구적인 사실 저장 (정체성, 선호도, 목표)	둘 다
`update_memory`	기존 메모리 수정 또는 업데이트	둘 다
`delete_memory`	오래된 정보 삭제	둘 다
`score_memories`	이전 교환 결과 점수화	Claude Code
`record_response`	중요한 교환에서 핵심 내용 저장	둘 다

점수화 작동 방식: Claude Code의 후크는 메인 LLM이 매 턴마다 score_memories를 호출하도록 프롬프트를 보냅니다. OpenCode는 백그라운드에서 조용히 점수화하는 독립적인 사이드카를 사용합니다. 모델은 점수화 프롬프트를 보지 않으며 score_memories는 도구로 등록되지 않습니다. 사이드카를 사용할 수 없는 경우, 사용자에게 roampal sidecar setup을 실행하라는 경고가 표시됩니다. roampal init 또는 roampal sidecar setup 중에 점수화 모델을 선택하세요.

Roampal 비교

기능	Roampal Core	Claude Code 내장 (CLAUDE.md / 자동 메모리)	OpenCode 내장
결과 기반 학습	예 — 나쁜 조언 강등, 좋은 조언 승격	아니요	아니요
의미론적 검색	예 — TagCascade + 교차 인코더 재순위 지정	아니요 — 파일 전체 로드, 검색 없음	메모리 시스템 없음
컨텍스트 주입	자동 — 쿼리당 관련 메모리	매 세션 전체 CLAUDE.md, 요청 시 자동 메모리	없음
원자적 사실 추출	예 — 요약 + 사실, 2단계 검색	아니요 — Claude가 유용하다고 판단한 것만 저장	메모리 없음
프로젝트 간 작동	예 — 모든 프로젝트 간 메모리 공유	프로젝트별 (git 저장소별)	메모리 없음
기록에 따른 확장	예 — 5개 컬렉션, 승격/강등/감쇠	CLAUDE.md 무제한, 자동 메모리 처음 200줄	메모리 없음
완전 로컬 / 비공개	예 — 사용자 기기의 ChromaDB	예	예

┌─────────────────────────────────────────────────────────┐
│  pip install roampal && roampal init                    │
│    Claude Code: hooks + MCP → ~/.claude/                │
│    OpenCode:    plugin + MCP → ~/.config/opencode/      │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  HTTP Hook Server (port 27182)                          │
│    Auto-started on first use, self-heals on failure     │
│    Manual control: roampal start / roampal stop         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  User types message                                     │
│    → Hook/plugin calls HTTP server for context          │
│    → AI sees relevant memories, responds                │
│    → Exchange stored, scored (hooks or sidecar)         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Single-Writer Backend                                  │
│    FastAPI → UnifiedMemorySystem → ChromaDB             │
│    All clients share one server, isolated by session    │
└─────────────────────────────────────────────────────────┘

전체 기술 세부 정보는 dev/docs/를 참조하세요.

요구 사항

Python 3.10+
다음 중 하나: Claude Code 또는 OpenCode
플랫폼: Windows, macOS, Linux (주로 Windows에서 개발 및 테스트됨)
RAM: 약 800MB 사용 가능 (교차 인코더 재순위 지정 + 임베딩 + ChromaDB)
디스크: 모델용 약 500MB (다국어 임베딩 + 재순위 지정, 첫 사용 시 자동 다운로드)
CPU: AVX2를 지원하는 최신 x86-64 프로세서 (Intel Haswell 2013+ / AMD Excavator 2015+)
GPU: 필요 없음 — 모든 추론은 ONNX Runtime을 통해 CPU에서 실행됨

문제 해결

Claude Code 재시작 (시작 시 후크 로드)
HTTP 서버 확인: curl http://127.0.0.1:27182/api/health

~/.claude.json에 올바른 Python 경로가 포함된 roampal-core MCP 항목이 있는지 확인
Claude Code 출력 패널에서 MCP 오류 확인

roampal init --opencode를 실행했는지 확인
서버가 자동 시작되었는지 확인: curl http://127.0.0.1:27182/api/health
그렇지 않은 경우 수동으로 시작: roampal start

정상입니다. Roampal은 자가 치유 기능을 갖추고 있어 HTTP 서버 응답이 없으면 자동으로 재시작하고 재시도합니다.

여전히 해결되지 않나요? AI에게 도움을 요청하세요. 로그를 읽고 Roampal 문제를 직접 디버깅할 수 있습니다.

지원

Roampal Core는 완전 무료 오픈 소스입니다.

개발 지원: roampal.gumroad.com
기능 아이디어 및 피드백: Discord
버그 리포트: GitHub Issues
AI 메모리 관련 도움이 필요하신가요? 문의: roampal@protonmail.com | LinkedIn

라이선스

Apache 2.0

roampal-core