MACCHA: 로컬 CLI 에이전트에 공유 가능한 영구 메모리·작업 파이프라인·보안 템플릿 공개

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

로컬 CLI 에이전트들은 기본적으로 세션 간 문맥을 유지하지 못해 동일한 실수를 반복하고 도구 전환 시 상태가 초기화되는 문제가 있다. MACCHA는 OS-중립 파일 아키텍처를 중심으로 세 계층 메모리(동적 벡터 기반 Working Memory, AGENTS.md 기반 Meso Memory, learned-lessons/ 기반 Long-Term Memory)와 파일 기반 작업 파이프라인(todo → in-progress → done)을 제공하여 에이전트 간 컨텍스트 공유와 진행률 추적을 가능하게 한다. 작동 과정에서는 Memanto라는 벡터 검색 계층이 유사도와 confidence-decay로 관련 컨텍스트를 반환하고, 세션 종료 시 반성 훅이 핵심 교훈을 추출하여 장기 메모리에 보관한다. 또한 minimum-release-age=7d 같은 공급망 보호 규칙과 HITL·비밀 비기록 규칙을 기계적으로 강제하여 자동화의 편의성과 운영 안전성 사이의 균형을 유지한다.

실용적 조언

리포지토리를 클론하여 로컬 환경에 설치하면 AGENTS.md, todo.md, in-progress.md, done.md, learned-lessons/ 같은 파일 구조를 즉시 사용할 수 있다. 이 파일들을 단일 소스 오브 트루스로 지정하면 에이전트가 작업을 생성하고 상태를 이동시키며 자동 아카이빙을 수행하므로 작업 이력과 진행률 추적이 가능해진다. 보안 측면에서는 minimum-release-age=7d 규칙과 HITL 제약을 기본값으로 적용하여 자동 패키지 설치와 고위험 명령의 무분별한 실행을 예방할 것을 권장한다.

섹션별 상세

원문은 CLI 기반 에이전트들이 기본적으로 상태를 유지하지 못해 문맥을 잃고 같은 실수를 반복한다는 문제를 제기했다. 이 문제를 해결하기 위해 MACCHA는 에이전트에 플러그인 가능한 중앙 'BRAIN' 파일 아키텍처를 제안했고, 이 아키텍처는 에이전트가 교체되더라도 동일한 작업 메모리와 상태를 즉시 재사용할 수 있게 설계되었다. 근거로는 GitHub 리포지토리와 3계층 메모리 구조(Working, Meso, Long-Term)가 제시되어 있다. 따라서 다중 도구를 오가며 작업하던 워크플로에서 컨텍스트 손실 문제를 줄일 수 있다는 점이 실무적 의미로 도출된다.

작업 메모리 계층은 동적 벡터 검색 계층(Memanto)과 신뢰도 감소 메커니즘으로 구성되어 현재 세션에 관련된 항목을 우선 검색하고 시간이 지남에 따라 우선순위를 낮추는 방식으로 동작한다. 입력은 임베딩된 컨텍스트 조각이며 처리 과정에서 유사도 기반 검색과 신뢰도 조정이 수행되고 출력으로는 관련 컨텍스트 조각이 반환된다. 원문은 'confidence-decay'라는 용어와 Memanto라는 구성요소를 명시하여 기술적 근거를 제공했다. 이런 설계는 짧은 시점의 관련성 유지와 오래된 정보의 자연스러운 소실을 동시에 달성하여 검색 소음 감소에 기여한다.

에이전트-네이티브 작업 관리 시스템(TMS)은 파일 기반 파이프라인(todo.md → in-progress.md → done.md)을 단일 진실 원천으로 설정하여 에이전트가 태스크를 이동시키고 자동으로 보관하도록 규정한다. 입력으로는 새 태스크 파일이 생성되고 처리 과정에서는 에이전트가 해당 파일을 읽고 상태를 갱신하며 출력으로 갱신된 파일과 아카이브 항목이 생성된다. 원문은 구체적 파일명과 파이프라인 단계를 직접 명시하여 재현 가능성을 제공했다. 이 방식은 에이전트 간 작업 이관과 진행률 추적을 단순화하여 협업성 및 추적 가능성을 높인다.

보안 가드레일은 공급망 보호, 인간 개입(HITL), 비밀 무기재 규칙 등 기계적으로 강제되는 규칙 세트로 구현되어 있다. 공급망 보호의 구체적 정책으로 minimum-release-age=7d가 제시되어 자동으로 최신 패키지를 즉시 설치하는 위험을 줄이고, HITL 규칙은 자금 변조·이메일 전송·고위험 실행을 명시적으로 차단하여 인간 승인 절차를 요구한다. 원문에 이러한 정책들이 명시되어 있어 실제 운영 환경에 즉시 적용 가능한 제약 조건을 확인할 수 있다. 그 결과 에이전트의 자동화 이점을 유지하면서도 운영 리스크를 낮추는 트레이드오프가 형성된다.

프로젝트는 OS 독립적인 파일 아키텍처를 강조하여 Claude Code나 OpenCode 같은 서로 다른 로컬 에이전트를 교체해도 동일한 장기 메모리와 작업 상태를 유지할 수 있다고 기술했다. 구조적으로 AGENTS.md와 learned-lessons/ 디렉토리 등의 파일을 통해 환경별 규칙과 축적된 교훈을 보관하고, 세션 종료 시 반성 훅을 통해 핵심 교훈을 추출하여 장기 메모리에 추가하는 방식으로 지속적 개선을 구현한다. 원문은 리포지토리 링크와 파일 구조 예시를 근거로 제시하여 구현의 재현 가능성을 확보했다. 따라서 에이전트 전환에 따른 지식 단절을 줄이고 점진적 학습 효과를 기대할 수 있다.

용어 해설

벡터 검색(Vector Search): — 문서나 상태를 임베딩 벡터로 변환하여 코사인 유사도 등으로 검색하는 방법이다. 최근 작업 메모리 구현에서 유사 항목을 빠르게 조회하고 관련 컨텍스트를 복원하는 데 사용된다. 이 글에서는 'Memanto'라는 동적 벡터 레이어가 작업 메모리 역할을 하며 신뢰도 감소(confidence-decay)를 통해 오래된 정보의 우선순위를 낮춘다고 기술되어 있다.
작업 메모리(Working Memory): — 실행 중인 세션의 단기적 컨텍스트와 상태를 보관하는 계층화된 저장소를 의미한다. 이 시스템에서는 벡터 검색 계층을 통해 현재 작업에 즉시 필요한 정보를 찾고, 시간이 지나면 신뢰도 감소로 자연스럽게 잊게 만든다. 작업 중 빠른 검색과 낮은 지연을 제공하여 에이전트의 즉시성 있는 의사결정을 지원한다.
사람 개입(HITL)(Human-in-the-loop): — 자동화된 처리 중 핵심 의사결정이나 위험한 조작에서 인간의 명시적 승인을 요구하는 운영 원칙이다. 이 프로젝트는 자산 변조, 이메일 전송, 고위험 명령 실행 등 특정 작업을 자동으로 차단하고 인간 승인을 필수로 하여 안전을 확보한다. HITL은 자동화의 편의성과 운영 안전성 사이의 균형을 맞추는 수단으로 사용된다.
장기 메모리(Long-Term Memory): — 에이전트가 세션 간에 누적해야 하는 지식·교훈·프로젝트 별 기록을 영구 보관하는 계층이다. 글에서는 별도 디렉토리(learned-lessons/)에 정제된 교훈을 저장하고 세션 종료 시 반성 훅을 통해 핵심 교훈을 추출한다고 기술되어 있다. 장기 메모리는 반복되는 실수를 줄이고 지속적으로 성능을 개선하는 근거가 된다.
공급망 보호(Supply Chain Protection): — 패키지·의존성 취약점을 통해 악성 코드가 유입되는 것을 방지하기 위한 정책·검증 절차를 말한다. 해당 글에서는 최소 릴리스 연령을 강제(minimum-release-age=7d)하여 zero-day 악성 패키지 설치 위험을 낮추는 규칙을 적용한다고 명시되어 있다. 이 접근법은 자동 설치 과정에서의 리스크를 제어하는 실무적 안전장치로 활용된다.

언급된 도구

MACCHA추천링크

로컬 CLI 에이전트에 공유 가능한 영구 메모리와 작업 파이프라인 및 보안 규칙을 제공하는 파일 기반 'BRAIN' 아키텍처

Memanto중립

작업 메모리 계층에서 동적 벡터 검색과 신뢰도 감소(confidence-decay)를 책임지는 구성요소

Claude Code중립

로컬 코딩 에이전트 예시로서 MACCHA에 연결되어 컨텍스트를 재사용할 수 있는 대상

OpenCode중립