<p>
<img src="https://raw.githubusercontent.com/aerovato/operator-memory/HEAD/docs/assets/banner.jpeg" alt="Operator Memory, the self-improving context engine for coding agents">
</p>
<p align="center">
<a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a>
</p>
Operator Memory: 코딩 에이전트를 위한 자체 개선 컨텍스트 엔진.
Operator Memory는 에이전트가 수행하는 모든 작업을 문서화할 수 있는 두뇌를 제공합니다. 에이전트가 작업함에 따라, 이 '두뇌' 안에 사양(specs), 결정 사항(decisions), 표준(standards), 연구 내용(research), 교훈(lessons) 등이 자동으로 문서화됩니다. 매번 새로운 세션은 이전 세션에서 학습한 모든 것을 알고 시작합니다.
주요 기능 (Features)
- 완벽한 컨텍스트 엔진 (Complete Context Engine) — 통합된 단일 시스템 내에서 문서화, 메모리, 인덱스, 스킬을 제공합니다.
- 자동 문서화 (Automatic Documentation) — 사양, 결정 사항, 연구 내용 등이 에이전트에 의해 자동으로 문서화됩니다.
- 투명한 메모리 (Transparent Memory) — 메모리는 읽고, 업데이트하고, 삭제할 수 있는 Markdown 문서 형태로 저장됩니다.
- 공유 가능한 지식 (Sharable Knowledge) — Git으로 문서를 추적하고 팀과 지식을 공유할 수 있습니다.
- 제로 인프라 (Zero Infrastructure) — 백그라운드 에이전트, 임베딩(embeddings), 벡터 데이터베이스(vector database), 모델 설정(model configuration)이 필요 없습니다.
설치 (Installation)
Operator는 Operator Helper를 통해 관리되며, 이 도구는 설정 및 에이전트 지침도 제공합니다. npm을 사용하여 Helper를 설치하세요:
npm install --global @aerovato/operator-helper
또는 Bun을 사용하세요:
bun add --global --minimum-release-age 0 @aerovato/operator-helper@latest
그런 다음, 사용 중인 하네스(harness)에 맞는 Operator 어댑터를 설치합니다. 각 링크를 클릭하여 해당 하네스별 정보를 확인하세요.
| Harness | Status | Install |
|---|
| Claude Code (CLI + Desktop) | 🟢 Fully Supported | operator-helper install claude-code |
| ... | | |
| Setup은 에이전트와의 대화입니다. 각 명령을 새로운 대화에서 실행하세요. | | |
- 처음 한 번만:
/operator:user-init — 전역 사용자 파티션을 설정합니다.
- 새로운 프로젝트마다:
/operator:project-init — Operator를 구성하고, 기존 문서를 마이그레이션하며, 레포지토리를 인덱싱합니다.
- 새 대화를 시작하고 일반적인 작업을 수행합니다.
기존 프로젝트에서 처음부터 시작할 때는 초기에는 정보가 부족한 상태(sparse brain)일 것으로 예상해야 합니다. 작업하는 모듈에 대한 첫 번째 사양을 에이전트에게 작성하도록 요청하세요. 이러한 문서들이 존재하게 되면, 이후 세션에서는 이를 일반적인 작업의 일부로 유지합니다.
<p align="center"><big><strong>Operator를 처음 사용하시나요? <a href="docs/getting-started.md">시작 가이드(Getting Started guide)</a>를 읽어보세요.</strong></big></p>
Operator 작동 방식
에이전트는 단일 세션에서는 탁월하지만, 세션이 끝나면 모든 것을 잊어버립니다. 다음 세션은 불완전한 컨텍스트를 다시 수집하는 데 토큰을 낭비합니다: 코드베이스 재탐색, 아키텍처 재학습, 결정 및 수정 사항 재교육.
Operator는 Markdown으로 구성된 지속 가능한 작업 공간(durable workspace)을 에이전트에게 제공하며, 이 공간은 세 곳에 보관됩니다:
.operator/ — 개인 프로젝트 지식으로, 사용자의 장치에 저장됩니다..operator-shared/ — 레포지토리와 함께 게시되는 프로젝트 지식입니다.~/.operator/user/ — 프로젝트 전반에서 사용되는 사용자 개인 규칙 및 지식입니다.
모든 세션은 동일한 루프를 실행합니다:
- 참고(Consult) — 에이전트는 브레인(Brain): 명령어, 코드베이스 인덱스, 사양, 가이드로부터 시작합니다.
- 구축(Build) — 에이전트는 해당 지식에 기반하여 일반적인 개발 작업을 수행합니다.
- 업데이트(Update) — 에이전트는 변경된 내용을 기록합니다: 새로운 사양, 결정 사항, 표준, 교훈.
프로젝트의 진실(project truth)이 변경될 때, 에이전트는 RAG 데이터베이스 레코드를 추가하는 대신 정식 파일(canonical file)을 업데이트합니다. 더 자세한 내용은 아키텍처를 참조하세요.
<p>
<img src="https://raw.githubusercontent.com/aerovato/operator-memory/HEAD/docs/assets/change-the-loop.png" alt="기억을 갖춘 에이전트 루프: 브레인 참고, 구축, 브레인 업데이트">
</p>
일상적인 작업 흐름
- 에이전트에게 일반적인 개발 작업을 부여합니다.
- 에이전트는 기존 지식을 자동으로 참조합니다: 코드 탐색을 위한 인덱스, 모듈 계약을 위한 사양(specs), 타사 통합 세부 정보를 위한 가이드 등을 활용합니다.
- 에이전트는 기존 지식을 자동으로 업데이트합니다: 프로젝트 진실(project truth)이 변경되면 관련 문서가 자동으로 업데이트됩니다.
- 다음 세션은 업데이트된 지식으로부터 계속 진행됩니다.
때로는 에이전트가 문서를 생성하거나, 통합하거나, 분할하는 것을 주저하기도 합니다. 이 경우, 에이전트를 더 큰 아키텍처 결정으로 유도합니다:
- "구현하기 전에 이 기능에 대한 사양을 작성해 주세요."
- "이 조사를 반복하지 않도록 연구 내용을 기록해 주세요."
- "이 두 문서는 중복됩니다. 통합해 주세요."
- "이 문서는 너무 큽니다. 분할해 주세요."
- "팀원들이 받을 수 있도록 이 사양을 Shared로 승격시켜 주세요."
로드맵
Operator Memory는 활발하게 개발 중입니다. 더 많은 기능들이 곧 추가될 예정이며, 각 기능은 기본 Operator 경험을 선호하는 경우를 대비하여 명시적인 온/오프 스위치와 함께 제공될 것입니다.
브레인 개선(Brain Improvements)
- 관찰 엔진 (Observation Engine) — 시간이 지남에 따라 지속 가능한 사용자 관찰 내용을 학습하며, 이는 명시적인 사용자 지침(User Instructions)과는 별도로 유지됩니다.
- 신뢰할 수 있는 브레인 업데이트 (Reliable Brain Updates) — 장시간 대화 중에도 사양 및 기타 브레인 문서를 최신 상태로 유지하여, 에이전트의 기억에만 의존하지 않습니다.
컨텍스트 관리(Context Management)
- 캐시 인식 프롬프트 렌더링 (Cache-Aware Preamble Rendering) — 캐시가 만료될 때 프롬프트를 자동으로 새로 고칩니다.
- 컨텍스트 관리 (Context Management) — 압축, 가지치기(pruning), 컨텍스트 관리를 위한 맞춤형 전략을 제공합니다.
- 손실 없는 컨텍스트 압축 (Lossless Context Compression) — 손실 없는 컨텍스트 압축을 통해 컨텍스트를 확장할 수 있습니다.
다른 메모리 플러그인과의 비교(VS Other Memory Plugins)
스니펫 캡처, RAG 검색, 컨텍스트 압축 모두 같은 방식으로 실패합니다.
더 알아보기
- Getting Started - 온보딩 및 사용 가이드: Operator가 작동하는 방식, 설정 방법, 일상적인 사용법, 에이전트 지시 방법, 그리고 Brain 검토 방법을 다룹니다. 명령어 레퍼런스도 포함합니다.
- Architecture - 파티션(partitions), 카탈로그(catalogs), 인덱스(indexes), 그리고 결정론적 컨텍스트 로딩(deterministic context loading)이 어떻게 작동하는지 설명합니다.
- Harness docs - 각 하네스별 설치, 검증, 명령어, 업데이트 및 문제 해결 방법을 안내합니다.
- Troubleshooting - 유효성 검사(validation), 복구(repair), 그리고 업데이트 복구에 대한 내용을 다룹니다.
라이선스
BSD 3-Clause. LICENSE를 참조하세요.
