RxAi-Aus/amp

🌏

번체 중국어 설명: README.zh-TW.md

A single GitHub repository를 대상으로 작동하는 AI 에이전트(예: Claude Cowork, OpenClaw)를 위한 공유 메모리 및 통신 시스템입니다. 이슈는 메시지 받은 편지함이며, 댓글은 답글이고, GitHub Actions가 인덱서 역할을 합니다. INDEX.md

• not_indexed.md

은 각 세션에 라이프사이클 훅이 주입하는 네비게이션 계층이며 (REGION-*.md는 브라우징 보조 도구) .rxai-cache/는 선택적 로컬 속도 계층입니다.

여러 장치에 있는 모든 에이전트 연결하기 (Claude Code, agy, Codex — ChatGPT Desktop 앱 포함. 이 앱은 Codex를 실행함 — OpenClaw, Hermes)는 fullInstallation.md에서 처음부터 끝까지 다룹니다. 여기에는 포괄적인 에이전트별 설치 가이드가 포함되어 있습니다.

만약 30초밖에 시간이 없다면: 에이전트들이 구조화된 제목으로 이슈를 게시하고, GitHub Actions는 해당 이슈들의 지속적인 인덱스를 유지하며, 신뢰도 가중치 시스템은 '성공적'인 패턴을 상단으로 부상시키고 '실패'한 패턴을 침몰시킵니다. 전체 이론은 PROTOCOL.md에 있습니다.

• 무엇인가요?

• 하나의 다이어그램으로 작동 방식

• 빠른 시작 — 한 명령어

• 단계별 설치 가이드

• 전제 조건

• 1단계 — 레포지토리 다운로드 또는 포크

• 2단계 — 비공개 GitHub 레포지토리를 생성하고 푸시

• 3단계 — 종속성을 설치하고 로컬에서 빌드

• 4단계 — 워크플로우 쓰기 권한 활성화

• 5단계 — 각 에이전트의 자격 증명 선택 (개인 사용 또는 협업)

• 6단계 — 세분화된 PAT를 안전하게 저장 (모드 B에서만)

• 7단계 — 각 에이전트를 위한 GitHub MCP 서버 구성

• 8단계 — 검증을 위해 인덱서를 수동으로 실행

• 9단계 — 첫 번째 테스트 이슈 전송

• 10단계 — 시크릿/개인 정보 스캔 훅 설치

• 검증 체크리스트

• 인간의 일상 사용 사례로

• 에이전트의 일상 사용 사례로

• 로컬 이슈 캐시

• 비밀/개인정보 스캔 후크

• 라이프사이클 트리거 및 rxai-amp 스킬 (v2.8)

• 우리가 측정한 것 — AMP가 스스로 비용을 회수하는 지점

• AMP 보드 — 메모리 기반의 로컬 작업 보드

• AMP 사서(Librarian) — Copilot CLI 설정 및 유지보수

• v2.4 및 v2.5의 새로운 기능들

• 흔한 실수들

• 문제 해결

• 파일 참조

• 프로토콜 업데이트 방법

벡터 데이터베이스, 서버 또는 GitHub 자체를 넘어서는 어떤 서비스도 필요 없이 두 개 이상의 AI 에이전트가 세션 간에 메모리를 공유할 수 있도록 하는 패턴입니다.

저장소(repo)가 뇌 역할을 합니다. 각 이슈는 하나의 생각이며, 해당 이슈의 댓글은 그 생각에 대한 대화입니다. GitHub Actions는 모든 새로운 이슈를 감시하며, 어떤 생각이 다시 읽을 가치가 있고 어떤 것이 약해졌는지 순서대로 정렬되고 가중치가 부여된 인덱스를 유지합니다.

현재 릴리스 버전은 v2.13입니다 (강화: 각 에이전트의 GitHub 자격 증명은 두 가지 질문—개인이 해당 장치에서 로그인할 수 있는지, 그리고 누가 저장소의 소유자인지—에 의해 선택됩니다. 따라서 사용자의 자체 장치는 gh login을 사용하고 비대면 호스트는 세밀한 PAT(Personal Access Token)를 보유합니다; 어떤 에이전트 설정도 문자 그대로의 토큰을 가지고 있지 않으며, 공식 MCP 서버는 AMP가 사용하는 6가지 도구로 제한되고, 개인 계정 저장소에서의 협업은 실제로 작동하는 방식으로 문서화되었습니다, §2). v2.12 (강화)에서는 L1이 더 이상 라이프사이클 후크를 실행할 수 없는 런타임 수준으로 지정되었고—후크 기능을 갖춘 런타임은 어댑터를 통해 L2에서 참여하며, 손상된 어댑터는 수동 탐색 대신 무음 회상(silent recall)으로 저하되고, Region 파일은 모든 레벨에서 회상 경로를 벗어납니다, §15.3). v2.11 (추가): 회상 주입을 요약 단계로 제한했습니다—레코드의 선택적 ## Now 섹션만 가능하며, 그렇지 않으면 그 ## Message의 시작 문구는 목록이 될 수 없습니다—Claude Code에서 작업 인식(task-aware)으로 만들었으며(세션 시작 시 포인터, 프롬프트가 겹치는 레코드에 대해서만 요약), 회상 기록을 (사용됨 → 성공)으로 강화할 수 있게 했습니다 (§4.4c). v2.10 (추가)에서는 INDEX.md를 제공했습니다.

포인터(pointers) 이슈가 티어 1이 스킵 결정(skip decision)을 지원할 수 있도록 하고 관련성 항(relevance term)을 감쇠시키며 — §4.4b — 이는 메모리를 표면화되었으나 사용되지 않은 것으로 기록한 재현율 명세서(recall manifests)에 의해 구동됩니다. v2.9.2에서는 Codex에 안정적인 훅스 런타임(stable hooks runtime)의 L2 라이프사이클 어댑터가 추가되었으며, 기존 스킬과 다이제스트는 L1 폴백으로 유지되었습니다. v2.9에서는 출시 준비성 강화(release-readiness hardening): 자동화된 테스트 스위트 + CI 게이트, Rule 14 에이전트 루프 가드(Agent Loop Guard)가 표준화되었고, 공식 Docker GitHub MCP 서버가 기본 구성으로 지정되었으며, §16 보안 고려 사항 및 위협 모델(Security Considerations & Threat Model)이 추가되었습니다. v2.8 (추가)에서는 에이전트 라이프사이클 계약(Agent Lifecycle Contract) §15, 라이프사이클 어댑터, /amp 명령, 그리고 npm run setup이 추가되었습니다. v2.4 (추가)에서는 생물정보학적 사실(biographical facts)에 대한 영구 메모리 서브시스템(type:lifefact + permanent_memory.json)을 도입하여 절대 감쇠되지 않도록 했습니다. v2.5 (추가)에서는 빠른 조회를 위한 선택적 로컬 이슈 캐시(.rxai-cache/)와 커밋 전 비밀 스캔 훅(pre-commit secret-scan hook)이 추가되었습니다. v2.6 (추가)에서는 OKF/BigQuery 기반 검색 계층(search layer)이 추가되었습니다 (PROTOCOL.md §14). v2.7 (추가)에서는 파이프라인을 강화했습니다: Supersedes: 무효화 적용, 조정하는 미색인 추적기(reconciling Not Indexed Tracker), 실패 시 명확하게 재시도하는 푸시 재시도(push retries that fail loudly), 그리고 생성된 상태 위생(generated-state hygiene)이 적용되었습니다. 이전 버전인 v2.2는 중단되는 용어 이름 변경(Wing → Region, Room → Place, Hall → Type)을 포함했습니다 — 마이그레이션 가이드는 PROTOCOL.md 부록 B를 참조하십시오. 전반적인 지능 계층(intelligence layer)은 v2.1에서 추가되었습니다: 에이전트가 생각에 대해 보고할 때, 그 생각이 작동했는지(Outcome: success), 작동하지 않았는지(Outcome: failure), 아니면 단순한 잡담이었는지(Outcome: neutral)를 명시해야 합니다. 성공은 가중치를 높이고, 실패는 낮추며, 잡담은 아무 변화도 주지 않습니다. 시간이 지남에 따라, 수동으로 삭제할 필요 없이 잘못된 패턴들은 증발합니다. 전체 설계는 PROTOCOL.md에 있습니다. 다음으로 그것을 읽으십시오. 동일한 흐름이 두 가지 워크플로우로 풀어서 설명됩니다:

┌─────────────────────────────────────────────────────────────────┐
│ 사람(Humans) + 에이전트(agents)가 GitHub MCP 서버를 통해 이슈 생성/댓글 게시하거나 (또는 GitHub UI를 직접 사용)
...

git clone <this-template> my-agent-memory && cd my-agent-memory
npm install
npm run setup # 대화형 마법사: 레포(repo) → 권한(permissions) → 레이블(labels) → 훅(hooks) → 첫 컴파일

npm run setup은 아래 가이드의 단계 2, 4, 그리고 6–10을 자동화하며, 수동 가이드는 강제할 수 없는 작업들까지 수행합니다. 즉, 개인 메모리 레포를 생성하고 (템플릿에 푸시하지 않음), Actions 읽기 + 쓰기 워크플로우 권한을 설정하며 (설정이 실패하는 가장 큰 이유), §6 이슈 레이블을 심어줍니다 (새 레포에는 레이블이 없으며, 이것이 없을 경우 레이블 없는 이슈가 발생합니다). 또한, 일일 AMP Librarian을 구성하거나 비활성화하여 Copilot PAT 없이 빨간색으로 표시되는 것을 방지하고, 각 에이전트의 자격 증명(기본적으로 사용자의 gh 로그인 또는 원격 호스트용 세밀한 PAT — v2.13)을 선택하며, GitHub 공식 MCP 서버를 설치 및 등록하고, 라이프사이클-훅 설치 프로그램에 위임하며, 실제 종단 간 컴파일 + 테스트 이슈로 마무리합니다. 현재 macOS/Linux에서만 가능합니다.

유용한 변형(Useful variants):

npm run setup -- --dry-run # 전체 계획을 출력하고 아무것도 변경하지 않음
npm run setup -- --yes # 비대화형; 사람의 작업은 todo 목록에 남게 함
npm run setup:verify # 검증 체크리스트만 다시 실행
...

아래 단계별 가이드는 마법사가 수행하는 작업을 참고용으로 유지하며, 어떤 단계가 실패하더라도 수동 대체 방법(각 실패 시 해당되는 수동 명령어가 출력됨)으로 사용됩니다.

본 가이드는 제로 상태에서 완전히 작동하는 에이전트 메모리 시스템을 GitHub에 구축하는 과정을 안내합니다. 모든 단계가 상세히 설명되어 있으며, 이 프로젝트에 대한 사전 경험은 가정하지 않습니다.

시간 예상: 수동으로 할 경우 약 15–25분, 또는 npm run setup (위)을 통해 대부분 자동화됩니다.

시작하기 전에, 다음 항목들이 사용자의 장치에 설치되어 있는지 확인하십시오:

Memory 저장소는 **공유된 두뇌(shared brain)**입니다. 모든 에이전트가 GitHub Issues를 통해 동일한 저장소에 읽고 쓰기 합니다. 사용자의 기기에 하나의 복사본만 있으면 되지만, 주 에이전트가 작업 공간/프로젝트 폴더로 접근할 수 있는 곳에 위치해야 합니다.

macOS: 보호된 폴더(~/Documents, ~/Desktop, ~/Downloads) 밖에 두세요. iCloud Drive 및 외부 또는 네트워크 볼륨은 macOS 개인 정보 보호 제어(TCC)의 보호를 받습니다. 에이전트를 실행하는 모든 앱(터미널, Claude Desktop, Codex / ChatGPT Desktop 등)은 자체 승인이 필요하며, board:schedule과 같은 launchd 작업은 요청할 창이 없습니다. AMP 훅은 소프트하게 실패하므로, 거부된 읽기는 단순히 회상이 조용히 누락된 것으로 나타납니다. 모든 에이전트가 접근할 수 있는 보호되지 않은 폴더에 클론을 넣으세요. 대부분의 사람들에게는 홈 폴더(~/AgentMemory)이지만, 어떤 보호되지 않은 경로든 작동합니다. 반드시 보호된 폴더에 있어야 한다면, 에이전트를 실행하는 모든 앱에 Full Disk Access(시스템 설정 → 개인 정보 및 보안)를 부여하세요.

중요: 에이전트별로 별도의 클론이 필요하지 않습니다. 모든 에이전트는 GitHub를 통해 동일한 레포지토리를 공유하며, 로컬 클론은 빌드 도구를 실행하고 파일을 검토하기 위한 용도일 뿐입니다. 각 에이전트는 로컬 파일 시스템을 통하는 것이 아니라 MCP 서버를 통해 GitHub에 연결합니다.

옵션 A — 클론 (개인 사용에 권장):

# 먼저 레포지토리를 위치시킬 곳으로 이동합니다
# OpenClaw의 경우:
cd ~/openclaw-workspace
...

옵션 B — 포크 (기여하고 싶을 때 권장):

• GitHub에서 리포지토리로 이동합니다.
• 클릭
  Fork(우측 상단) - 포크한 것을 적절한 위치에 클론합니다:
  cd ~ # 또는 ~/openclaw-workspace 등 (macOS에서는 ~/Documents를 피하세요)
  git clone https://github.com/<your-username>/AgentMemory.git
  cd AgentMemory

대부분의 AI 에이전트는 샌드박스(sandbox) 내부에서 실행되며 기본 디렉토리 외부 파일은 볼 수 없습니다. 클론한 후에는 이 폴더가 존재한다고 에이전트에게 명시적으로 알려주어야 합니다.