agentic-stack: 코딩 에이전트 도구를 바꿔도 메모리와 스킬을 유지하는 이식형 브레인

9bow · 6월 24, 2026, 12:30오후

agentic-stack 소개

코딩 에이전트를 쓰다 보면 도구를 갈아탈 일이 자주 생깁니다. Claude Code로 작업하다가 Cursor로 옮기고, 다시 터미널 기반 도구로 넘어가는 식입니다. 문제는 도구를 바꾸는 순간 그동안 쌓인 컨텍스트가 초기화된다는 점입니다. 프로젝트의 관례, 과거에 내린 결정, 에이전트가 학습한 교훈이 특정 도구의 설정 파일에 묶여 있어 함께 따라오지 못합니다. agentic-stack은 이 문제를 정면으로 다루는 프로젝트입니다.

agentic-stack의 핵심은 하나의 이식형 .agent/ 폴더입니다. 이 폴더는 메모리(memory), 스킬(skills), 프로토콜(protocols)을 담고 있으며, 여러 코딩 에이전트 하네스(harness)에 동일하게 연결됩니다. 현재 Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, GitHub Copilot CLI, Google Gemini CLI, Hermes, Pi Coding Agent, Codex, Antigravity, 그리고 직접 만든 Python 루프까지 12종의 하네스를 지원합니다. 도구를 바꿔도 .agent/ 폴더의 지식은 그대로 유지되므로, 에이전트가 일하는 방식이 도구에 따라 리셋되지 않습니다.

이 프로젝트는 폴더 구조만 제시하는 가이드와는 다릅니다. 9개의 시드 스킬(seed skill), 4개의 메모리 계층, 강제되는 권한 규칙, 야간 스테이징 사이클, 호스트 에이전트용 리뷰 도구, 그리고 여러 하네스용 어댑터가 실제 파일로 함께 들어 있습니다. 본 게시물에서는 agentic-stack의 구조와 메모리·리뷰 동작 방식, 스킬과 프로토콜, 그리고 설치·사용법을 정리합니다.

agentic-stack의 전체 구조: 이식형 .agent 폴더

agentic-stack은 여러 하네스가 위쪽에서 동일한 .agent/ 폴더를 공유하는 구조입니다. 아래 다이어그램은 상단의 코딩 에이전트들이 가운데의 이식형 브레인에 연결되고, 그 브레인이 메모리·스킬·프로토콜 세 축으로 구성된다는 점을 보여줍니다.

각 하네스는 자신의 설정 방식(예: Claude Code의 훅, Cursor의 룰 파일)으로 같은 .agent/ 폴더를 읽습니다. 하나의 저장소에 여러 어댑터를 동시에 설치할 수도 있어서, 같은 프로젝트에서 Claude Code와 Cursor를 함께 쓰면서 메모리와 스킬을 공유하는 구성이 가능합니다.

v0.9.0부터는 어댑터 관리가 매니페스트(manifest) 기반으로 바뀌었습니다. 모든 하네스는 adapter.json으로 선언되고, 공용 Python 백엔드가 이를 적용하며, 동사형 서브커맨드나 대화형 TUI로 관리합니다. POSIX와 Windows를 모두 지원하고, 동시 쓰기 보호와 공유 파일 소유권 추적을 갖추고 있어 한 어댑터를 제거해도 다른 어댑터가 끊기지 않습니다.

agentic-stack의 4계층 메모리와 리뷰 프로토콜

agentic-stack의 메모리는 네 개의 계층으로 나뉩니다. 작업 메모리(working/), 일화 메모리(episodic/), 의미 메모리(semantic/), 개인 설정 메모리(personal/)이며, 각 계층은 자체 보존 정책을 가집니다. 검색은 현저성(salience)과 관련성(relevance)을 곱한 질의 인식형(query-aware) 방식으로 이뤄지고, 야간에 메모리를 압축해 리뷰 가능한 후보(candidate)로 정리합니다.

여기서 중요한 설계 결정은 자동 추론을 무인으로 두지 않는다는 점입니다. 야간 사이클인 auto_dream.py 는 후보 교훈(candidate lesson)을 기계적으로 스테이징만 합니다. 무언가를 수락하거나 의미 메모리를 직접 수정하지 않습니다. 실제 채택 여부는 세션 안에서 호스트 에이전트가 CLI 도구로 결정합니다.

# 우선순위순으로 정렬된 대기 후보 목록 조회
python3 .agent/tools/list_candidates.py

# 근거를 달아 수락 (rationale 필수)
python3 .agent/tools/graduate.py <id> --rationale "evidence holds, matches PREFERENCES"

# 사유를 달아 반려 (reason 필수, 결정 이력 보존)
python3 .agent/tools/reject.py <id> --reason "too specific to generalize"

수락된 교훈은 진실 공급원인 semantic/lessons.jsonl 에 들어가고 semantic/LESSONS.md 로 렌더링됩니다. 반려된 후보는 결정 이력을 그대로 보존해, 반복되는 잡음이 새것처럼 보이지 않고 누적된 기록으로 남습니다. 한 번 수락한 교훈도 retract_lesson.py 로 회수하면 이력에는 status=retracted 로 남되 이후 능동 회상에서는 제외됩니다.

agentic-stack의 스킬과 프로토콜

스킬은 점진적 공개(progressive disclosure) 방식으로 동작합니다. 가벼운 매니페스트는 항상 로드되지만, 전체 SKILL.md 파일은 작업의 트리거가 맞을 때만 로드됩니다. 모든 스킬에는 자기 재작성(self-rewrite) 훅이 포함됩니다. 기본 제공되는 design-md 스킬은 에이전트가 루트의 DESIGN.md 를 UI와 Google Stitch 워크플로우의 시각적 진실 공급원으로 사용하도록 안내합니다.

프로토콜 계층은 타입이 지정된 도구 스키마, 사전 도구 호출(pre-tool-call) 훅이 강제하는 permissions.md, 그리고 서브 에이전트를 위한 위임 계약(delegation contract)으로 구성됩니다. 권한 규칙이 훅으로 강제되기 때문에, 에이전트가 허용되지 않은 도구를 호출하는 일을 사전에 차단할 수 있습니다.

agentic-stack의 데이터 레이어와 데이터 플라이휠

같은 .agent/ 브레인을 여러 하네스가 함께 쓰는 팀을 위해, agentic-stack은 두 가지 로컬 우선(local-first) 기능을 제공합니다.

데이터 레이어(data-layer 시드 스킬)는 Claude Code, Hermes, OpenClaw, Codex, Cursor, OpenCode 등 여러 하네스에 걸친 로컬 대시보드 내보내기를 만듭니다. 하네스 이벤트, cron 타임라인, KPI 요약, 토큰·비용 추정치, 카테고리, dashboard.html, daily-report.md 가 여기에 포함됩니다. 아래는 데이터 레이어가 모으는 정보의 흐름입니다.

데이터 플라이휠(data-flywheel 시드 스킬)은 승인되고 비식별화된(redacted) 실행을 추적 기록(trace records), 컨텍스트 카드(context cards), 평가 케이스(eval cases), 학습용 JSONL, 준비도(readiness) 지표로 내보냅니다. 이 기능은 로컬 전용이며 모델에 비종속적입니다. 즉 아티팩트를 준비할 뿐 모델을 학습시키거나 외부 API를 호출하지 않습니다.

agentic-stack 설치 및 사용법

macOS와 Linux에서는 Homebrew로 설치합니다. tap 등록과 설치 두 줄이 모두 필요합니다.

# tap 등록 + 설치 (최초 1회, 두 줄 모두 필요)
brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack
brew install agentic-stack

# 원하는 프로젝트에서 브레인을 설치하면 온보딩 마법사가 자동 실행됨
cd your-project
agentic-stack claude-code
# 또는: cursor | windsurf | opencode | openclaw | copilot-cli | gemini | hermes | pi | codex | standalone-python | antigravity

저장소를 클론해 ./install.sh <adapter> 로 설치할 수도 있고, Windows에서는 install.ps1 을 사용합니다. 인자 없이 ./install.sh 를 실행하면 다중 선택 마법사가 열려 사용 중인 하네스를 한 번에 설치합니다. 설치 이후에는 동사형 서브커맨드로 프로젝트를 관리합니다.

./install.sh dashboard           # TUI 대시보드: 상태, 검증, 메모리, 팀, 스킬, 인스턴스
./install.sh add cursor          # 두 번째 어댑터 추가 (같은 저장소에 Claude Code + Cursor)
./install.sh doctor              # 읽기 전용 점검: 어댑터별 green/yellow/red
./install.sh remove cursor       # 확인 후 삭제 (격리 없음, 되돌리기 없음)

선택 기능으로, v0.18.0부터는 외부 장기 메모리 도구인 codejunkie99/brain 과의 브리지를 제공합니다. Brain은 git 기반의 장기 메모리 바이너리이자 MCP 서버이며, agentic-stack은 이를 Rust 워크스페이스를 통째로 끌어오지 않고 선택적 외부 메모리 계층으로 연결합니다.

agentic-stack의 라이선스

agentic-stack은 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

agentic-stack 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~