서론

안녕하세요 konippi 입니다.

Kiro로부터, 세션을 넘어 컨텍스트를 기억하고 스케줄이나 이벤트를 계기로 작업을 지속할 수 있는 오픈소스 개발 워크스페이스 Kiro Crew가 공개되었습니다🎉

Kiro Crew는 단순히 Kiro CLI에 Web UI를 붙인 것이 아닙니다. Kiro CLI를 에이전트 런타임 (Agent Runtime)으로 이용하며, 그 주변에 세션 관리, 영속 메모리 (Persistent Memory), 스케줄러 (Scheduler), Subagent, 보안 정책 (Security Policy), 다중 인터페이스를 더한 상주형 워크스페이스입니다. 본 기사에서는 공개 구현을 따라가며, 장기간 동작하는 AI 에이전트 기반을 설계할 때 참고가 될 Gateway, 세션, 메모리, MCP, Defense in Depth의 사고방식을 정리합니다.

Kiro CLI와 Kiro Crew의 책임 분담

Kiro Crew의 설계를 이해하려면 다음 3개의 레이어 (Layer)를 나누어 생각하면 이해하기 쉽습니다.

Kiro Crew는 LLM 추론이나 에이전트 표준 도구의 실행을 담당하는 런타임이 아니라, 그 역할을 Kiro CLI에 위임합니다. Kiro Crew는 kiro-cli acp --agent <name>

을 실행하여, **ACP (Agent Client Protocol)**를 통해 Kiro CLI를 조작합니다. 반면, Cron의 Script / Command 등 모델을 사용하지 않는 처리는 Gateway 측에서 직접 실행됩니다. ACP와 Kiro CLI를 ACP Client로부터 이용하는 방법에 대해서는 이전 기사 「Kiro CLI가 ACP 대응! 원하는 에디터에서 Kiro CLI를 사용하자」를 참조해 주세요.

현재 공개 버전 Kiro Crew가 실행하는 에이전트 런타임은 Kiro CLI뿐입니다. ACP를 사용하고 있지만, Claude Code나 Codex CLI 등 임의의 ACP Agent를 설정에서 교체하는 기능은 없습니다. 또한, Kiro Crew 자체는 Apache-2.0 라이선스의 OSS이지만, Kiro CLI를 이용하기 위해 Kiro Account로의 Sign-in과 Kiro Plan이 필요합니다.

즉, Kiro Crew는 Kiro CLI를 대체하는 것이 아니라, Kiro CLI 위에 지속 운용을 위한 기능을 추가하고 있습니다. 상위 수준에서 아키텍처를 도식화하면 다음과 같은 이미지입니다.

백엔드의 중심은 Python의 asyncio와 aiohttp로 구현된 Gateway입니다. Gateway는 단일 장수명 코디네이터 프로세스 (Coordinator Process)로서, Dashboard의 API와 WebSocket, 각 채널로부터의 입력, 세션의 라이프사이클 (Lifecycle), 컨텍스트 구성, Cron / Heartbeat / TaskRunner / Subagent, 도구 승인 및 영속화를 조정하며, Kiro CLI나 MCP Server와 같은 자식 프로세스 (Child Process)를 관리합니다. 외부 데이터베이스나 메시지 브로커를 필수적으로 요구하지 않으며, Embedding 생성이나 파일 탐색과 같은 무거운 처리는 이벤트 루프 (Event Loop)를 블록하지 않도록 전용 워커 스레드 (Worker Thread)로 오프로드 (Offload)합니다.

메시지가 처리되기까지의 흐름

다음은 Web Dashboard에서 일반적인 Chat Turn을 시작했을 경우의 흐름입니다. Slack 등의 메시징 채널 (Messaging Channel)에서는 수신된 메시지가 설정된 Auto Reply와 일치하면, Session이나 LLM을 기동하지 않고 정형 문구를 반환하는 경우가 있습니다. 또한, kirocrew chat은 Gateway를 경유하지 않고 Kiro CLI를 직접 기동합니다.

Session Manager와 ACP 런타임

여기서 말하는 **논리 세션 (Logical Session)**이란, 대화 이력, Workspace, Agent 설정, 실행 컨텍스트를 다른 대화로부터 분리하는 단위입니다. Dashboard의 채팅 슬롯, Cron 실행, TaskRunner, Subagent 등은 통상 각각의 논리 세션에 할당됩니다. 대부분은 dashboard:chat-1, cron:{id}, subagent:{id}와 같이 발생원과 개체를 나타내는 session_key로 식별되지만, 연동된 Slack Thread가 기존 Dashboard Session으로 합류하는 경우나, Heartbeat가 공유 예약 키를 사용하는 경우도 있습니다.

논리 세션과 OS Process는 1 대 1 관계가 아닐 수도 있습니다. 세션 전용 ACP Process를 사용하는 구성 외에도, 공유 ACP Runtime 상에서 여러 Session Handle을 다중화하는 구성이 있습니다. 세션 기반은 Warm Pool, Idle Session 회수, 연속 실패 시의 Circuit Breaker, 자동 Compaction, Orphan Process 회수 등을 담당합니다. Turn Timeout은 Surface Runner나 ACP Transport에서도 강제되며, Gateway 전체의 Shutdown은 Cron, Heartbeat, Subagent, Session 등을 안전한 순서로 정지시킵니다.

ContextBuilder와 6개 계층의 메모리

Kiro Crew의 큰 특징은 세션을 넘나드는 기억입니다. 아래의 6개 계층은 독립된 6개의 Database가 아니라, 컨텍스트(Context)에 주입할 때의 논리적인 우선순위입니다. Lessons, Semantic Memory, Episodic Memory 등 여러 계층이 동일한 memory.db를 공유합니다.

우선순위가 높은 레이어일수록 컨텍스트 내에서 강력한 지시로 취급되며, Lessons가 과거의 Preferences와 모순될 경우 Lessons가 우선됩니다.

기억의 업데이트에는 3가지 경로가 있습니다. 사용자가 명시적으로 기억을 요청하고 Agent가 learn_add MCP Tool을 호출하면, Lesson으로서 즉시 저장됩니다. 그 외의 대화는 LLM에 의한 집약 (Consolidation)을 거쳐 각 계층으로 분배됩니다. 트리거는 30개 메시지 축적과 3시간 유휴(Idle) 상태의 두 가지이며, 둘 다 Semantic / Episodic Memory를 추출합니다. 유휴 상태의 경우 일일 요약과 대화 중의 정정 사항 (Lessons)을 추가로 작성합니다.

참고로 제4계층인 Preferences / Projects는 구조화된 메모리 이전부터 존재하던 레이어로, memory.db로 이관이 완료된 환경에서는 Consolidation의 쓰기 대상에서 제외되며, pref.* / project.* 키로서 Semantic Memory 측으로 일원화됩니다.

검색 시 Semantic Memory는 pref.* / project.* / user.*

등의 Key-Value로 취급되며, 사용자가 명시한 값은 자동으로 추출된 값보다 우선됩니다. Episodic Memory는 Vector 유사도에 더해 중요도, 시간 감쇠 (Time Decay), MMR (Maximal Marginal Relevance)을 통한 다양화를 조합하여 검색합니다. Embedding은 동봉된 llama-cpp-python Runtime과, 최초 실행 시 백그라운드에서 가져오는 Local Model로 생성합니다. Model이 준비될 때까지는 Keyword / FTS 검색으로 폴백 (Fallback)하므로, Gateway의 기동이나 채팅은 차단되지 않습니다.

ContextBuilder는 Memory, Lessons, Skills, History 등 주요 정보원별로 글자 수 상한을 설정하며, 사용 중인 Model의 컨텍스트 윈도우 (Context Window)에 따라 비례 축소하면서 프롬프트 (Prompt)를 구성합니다. 동일한 ACP Session의 연속된 턴에서는 Kiro CLI 자체가 대화 이력을 유지하므로, Thread History를 매번 중복하여 주입하지 않습니다.

자율 실행을 뒷받침하는 4가지 메커니즘

Kiro Crew가 "자리를 비운 중에도 작업을 진행"하기 위한 핵심 기능은 Cron, Heartbeat, TaskRunner, Subagent입니다. LLM 추론을 동반하는 작업은 공통의 Session / ACP 기반을 사용하며, 컨텍스트, 보안, 감사 메커니즘을 공유합니다. 이러한 추론은 대화에서 시작했을 때와 마찬가지로 Kiro Plan 사용량으로 계상됩니다. 반면, Cron의 Script / Command와 같이 Model을 호출하지 않는 처리는 ACP를 경유하지 않으며, Kiro Plan의 요청을 소비하지 않습니다.

Webhook은 외부 Event로부터 이러한 처리를 시작하는 트리거 (Trigger)이며, Apps는 Agent, Skills, Schedule, Integration을 특정 용도의 UI / Workflow로 묶는 확장 레이어입니다.

TaskRunner는 태스크 (Task) 사양을 단계 (Step)로 분해하고, 실행, 검증, 재시도, 재계획을 반복하면서 상태를 체크포인트 (Checkpoint)로 저장합니다. 태스크가 분해되어 실행 중이었던 Run은 Gateway 재기동 시 Paused 상태로 복원되며, 실행 중이었던 Step을 재실행하는 방식으로 수동 재개할 수 있습니다.

Subagent는 부모 세션으로부터 독립된 subagent:<id> 세션에서 실행되며, 완료 후 결과를 부모에게 반환합니다. 필요에 따라 continue나 steer로 추가 지시를 보낼 수도 있습니다. Research Lab과 같은 Apps도 병렬 조사의 Worker로서 이 메커니즘을 이용할 수 있습니다.

MCP로 Gateway의 기능을 에이전트에게 공개하기

Kiro Crew의 기능은 가능한 한 구조화된 MCP Tool로서 Kiro CLI에 공개됩니다. 설계에서는 "LLM이 이용하는 신기능은 CLI 커맨드뿐만 아니라, 반드시 MCP Tool로서 제공한다"라는 MCP-first 원칙이 정의되어 있습니다. 즉, MCP는 외부 Tool의 추가뿐만 아니라 Cron, Subagent, Learning, TaskRunner 등 Gateway 자신의 기능을 에이전트에게 공개하는 제어 측면이기도 합니다.

MCP Server 프로세스는 여러 세션이나 Subagent로부터 공유될 수 있으므로, Tool은 Stateless (무상태) 방식으로 구현됩니다. 호출 시마다 Gateway가 추가한 Caller Context 등의 정보를 통해 Session을 해결하며, 세션 고유의 상태는 MCP 프로세스 내부가 아닌 Gateway 측에서 유지합니다. 프로세스 내에 '마지막으로 호출한 세션'과 같은 상태를 가지게 되면, 다른 대화에 결과를 반환하거나 부모 세션을 오작동시킬 위험이 있기 때문입니다.

설정 측면에서 Kiro Crew는 자신의 Tool을 사용자 소유의 ~/.kiro/settings/mcp.json에 기록하지 않고, 관리할 설정을 전용 Agent Config인 ~/.kiro/agents/kirocrew.json으로 집약합니다. 이러한 분리를 통해 Kiro Crew 전용 Tool이 일반적인 Kiro CLI나 Kiro IDE의 세션으로 유출되는 것을 방지합니다.

PreToolUse Gate를 포함한 다층 방어 (Defense in Depth)

LLM은 Repository, Web, Slack 등 신뢰할 수 없는 정보를 읽기 때문에, Kiro Crew의 Threat Model (위협 모델)은 Model을 신뢰할 수 있는 호출자가 아닌, 공격자의 영향을 받을 수 있는 입력으로 취급합니다. 주요 위협은 Prompt Injection (프롬프트 인젝션)을 통한 인증 정보의 읽기 및 외부 전송, 그리고 위험한 Local Operation (로컬 작업)입니다.

Kiro CLI가 session/request_permission을 보낸 Tool Call은 Gateway의 HookManager.on_tool_call에서 평가됩니다. 명령어를 검증할 수 없는 Shell 호출은 우선 거부되며, 이어서 Sensitive Path (민감 경로) / Sensitive Bash (민감 Bash) / Exfiltration Pattern (데이터 유출 패턴) → Write-Protected Path (쓰기 보호 경로) → Denied Command (거부된 명령어) → Governance (거버넌스) 순으로 판정한 후, Auto Approve (자동 승인) 또는 Session Trust (세션 신뢰)를 적용합니다.

반면, Kiro CLI가 allowedTools나 mcpServers.autoApprove를 통해 로컬에서 승인한 호출은 Permission Request (권한 요청)를 발행하지 않으므로 이 Gate를 통과하지 않습니다. Kiro Crew는 위험한 Blanket Grant (포괄적 허용)를 최종 Agent Config에서 제외하며, 주요 MCP Tool의 Schema Validation (스키마 검증), Sandbox (샌드박스), 출력의 Redaction (비식별화), HMAC Chain이 포함된 SEL을 조합하여 Defense in Depth (다층 방어)를 구성합니다.

PreToolUse Gate는 Agent Config의 Prompt와는 독립적으로 평가되며, Permission Request 경로에서는 Hard Deny가 Session Trust보다 우선됩니다. 다만, 어느 한 층도 단독으로 완전한 방어를 제공하지는 않습니다. 기본적으로 임의의 목적지로 향하는 Network Egress를 완전히 차단하지 않으며, Command Gate 또한 완전한 Bash AST Parser가 아니기 때문에, 최소 권한의 Credential과 고영향 작업(High-impact operation)에 대한 리뷰가 전제되어야 합니다.

Enterprise를 위한 Governance는 effective permission = POLICY ∩ PROFILE로 표현됩니다. POLICY는 기동 시에 로드되는 전체 상한선이며, PROFILE은 채널마다 더욱 좁게 설정하는 구성으로, 항상 더 엄격한 쪽이 적용됩니다. Policy나 서명 키와 같은 Trust Root는 에이전트가 Read / Write 할 수 없는 기밀 경로(Secret path)로서 보호됩니다.

데이터는 어디에 저장되는가

Kiro Crew의 상태는 기본적으로 ~/.kiro/crew/에 저장됩니다 (KIROCREW_HOME으로 변경 가능합니다).

~/.kiro/crew/
├── config.json # 설정
├── security_policy.json # Governance POLICY
...

대화 이력, Memory, Schedule, Audit Log는 Local / Remote를 불문하고 Gateway와 동일한 Host에 저장됩니다. 반면, 사용자의 Prompt와 ContextBuilder가 구성한 컨텍스트는 LLM 추론을 위해 Kiro CLI를 경유하여 Provider로 전송됩니다.

요약

Kiro Crew의 아키텍처를 요약하면 다음과 같습니다.

• Kiro CLI를 에이전트 런타임(Agent Runtime)으로 분리: LLM 추론, 도구, MCP는 Kiro CLI가 담당하며, Kiro Crew는 인터페이스, 세션, 메모리, 스케줄, 보안을 조정합니다.
• 논리 세션으로 실행 컨텍스트를 분리: Dashboard, Channel, Cron, Task, Subagent를 공통의 세션 기반으로 관리합니다.
• 6개 층의 메모리를 선택적으로 주입: Lesson부터 Recent History까지, 우선순위와 검색 방법을 나누어 컨텍스트 윈도우(Context Window)를 사용합니다.
• MCP로 Gateway의 기능을 공개: Cron, Subagent, Learning, TaskRunner 등을 구조화된 도구로서 에이전트가 이용할 수 있게 합니다.
• 다중 보안 레이어를 조합: Permission Request 경로의 PreToolUse Gate에 더해, Sandbox, Input Validation, Output Redaction, SEL로 보완합니다.
• Gateway 호스트에 상태를 영속화: 대화, 메모리, 스케줄, 감사 로그는 Gateway와 동일한 호스트에 저장하며, LLM 추론은 Kiro CLI를 통해 Provider로 전송합니다.

Kiro Crew의 아키텍처에서 배울 수 있는 점은, 에이전트의 능력을 단 한 번의 Chat Turn에 가두지 않고, 세션, 메모리, 스케줄, 보안을 갖춘 워크스페이스(Workspace)로 구축하는 방법입니다. ACP를 통해 에이전트 런타임과 워크스페이스를 분리하고, MCP로 Orchestration 기능을 공개하며, 상태를 Gateway 호스트에 영속화하는 설계는 독자적인 AI 에이전트 기반을 고민할 때도 응용할 수 있습니다.

오픈 소스이므로, 본 기사에서 소개한 설계는 모두 코드로 확인할 수 있습니다. Desktop App, 원라이너(One-liner) 설치, Docker 등의 도입 방법은 공식 README의 Quick start에 정리되어 있으니 꼭 시도해 보세요!

참고 링크

Discussion