모든 메모리가 APC에 들어갈 필요는 없습니다

많은 에이전트 설정이 동일한 이유로 실패합니다. 바로 모든 메모리를 하나의 바구니로 취급하기 때문입니다.

그것은 APC와 APX가 시도하려는 방식이 아닙니다.

APC는 휴대 가능한 컨텍스트 레이어 (portable context layer)입니다. 공유, 검토 및 커밋(commit)하기에 안전한 내구성이 있는 프로젝트 사실(durable project facts)만을 유지해야 합니다.
APX는 일상적인 런타임 레이어 (daily runtime layer)입니다. 로컬 에이전트 메모리, 교차 채널 회상 (cross-channel recall), 세션 (sessions) 및 기타 런타임 상태를 레포지토리 (repo) 외부에 유지해야 합니다.

이러한 분리는 서로 다른 종류의 메모리가 서로 다른 문제를 해결하기 때문에 중요합니다.

모든 것을 APC에 넣으면, 레포지토리는 개인적인 노트, 일시적인 결론, 그리고 오래된 대화 잔해로 가득 차게 됩니다.
모든 것을 APX에 유지하면, 머신, 런타임 또는 세션이 변경될 때마다 프로젝트가 내구성이 있는 지식을 잃게 됩니다.

더 나은 모델은 간단합니다: APC는 프로젝트가 기억해야 할 것을 저장하고, APX는 런타임이 작동하기 위해 필요한 것을 저장합니다.

APC 메모리: 휴대 가능하고, 큐레이션되었으며, 팀에게 안전함

APC에서 큐레이션된 메모리는 다음 경로 아래 프로젝트와 함께 존재합니다:

.apc/agents/<slug>/memory.md

이 파일은 에이전트의 프로젝트 역할과 연결된 내구성이 있는 사실들을 위한 것입니다. 좋은 예시는 다음과 같습니다:

• 장기적인 제약 조건 (long-lived constraints)
• 팀 컨벤션 (team conventions)
• 아키텍처 결정 (architectural decisions)
• 반복되는 책임 (recurring responsibilities)
• 안정적인 도메인 사실 (stable domain facts)

이러한 종류의 메모리는 가장 좋은 의미에서 지루합니다. 일반 Markdown 형식이며, diff를 확인하기 쉽고, 검토하기 쉬우며, 다른 도구로 마이그레이션하기 쉽습니다.

리뷰어 에이전트 (reviewer agent)는 다음과 같은 것을 유지할 수 있습니다:

# Memory - reviewer

## Project facts
...

이것은 APC에 속해야 합니다. 왜냐하면 다른 기여자, 다른 IDE, 또는 다른 런타임이 나중에 동일한 프로젝트 규칙을 읽을 수 있어야 하기 때문입니다.

APX 메모리: 로컬, 운영적, 런타임 소유

APX는 다른 역할을 수행합니다. APX는 런타임 및 툴링 레이어 (tooling layer)이므로, 레포지토리에 있어서는 안 될 머신 로컬 메모리 (machine-local memory)를 유지합니다.

에이전트별 런타임 메모리는 다음 경로 아래에 존재합니다:

~/.apx/projects/<project-id>/agents/<slug>/memory.md

해당 파일은 매 호출 시 에이전트 프롬프트 (agent prompt)에 주입됩니다. 이는 로컬 운영 컨텍스트 (local operational context), 소유자 선호도 (owner preferences), 그리고 런타임 (runtime)을 돕는 영구적인 노트 (durable notes)를 위해 유용하지만, 저장소 (repository)와 함께 자동으로 이동해서는 안 됩니다.

APX는 또한 별도의 교차 채널 메모리 시스템 (cross-channel memory system)을 가지고 있습니다:

~/.apx/memory.md
~/.apx/memory.db

이 레이어는 채널 간의 자동 회상 (automatic recall)을 지원합니다. 이는 최근의 사실을 기억하고, 의미론적으로 관련 있는 과거 메시지를 검색하며, 저장소를 세션 덤프 (session dump)로 만들지 않고도 긴 히스토리를 압축할 수 있습니다.

따라서 APX는 이미 우리에게 중요한 사실을 알려주고 있습니다: 모든 메모리가 커밋 (commit)되어야 하는 것은 아니며, 모든 메모리가 전역적 (global)이어야 하는 것도 아니라는 점입니다.

실무 규칙: 형식이 아닌 가시성(visibility)으로 결정하라

팀들이 저지르는 실수는 메모리를 가시성이 아닌 파일 유형으로 판단하는 것입니다.
내용이 비공개적이거나, 일시적이거나, 검토되지 않았다면 memory.md 파일이라 할지라도 여전히 잘못된 장소일 수 있습니다.

더 나은 규칙은 다음과 같습니다:

• 프로젝트 전체가 나중에 필요로 할 수 있고 커밋해도 안전하다면 APC에 넣으세요.
• 런타임 로컬 (runtime-local)이거나, 개인적이고, 일시적이거나, 진행 중인 세션에서 파생된 것이라면 APX에 유지하세요.
• 가공되지 않은 노이즈 (raw noise)라면 둘 다 제외하세요.

예를 들어:

• "pnpm을 사용하고, npm은 절대 사용하지 말 것"은 APC에 속해야 합니다.
• "소유자는 짧은 PR 요약을 선호함"은 APX 런타임 메모리에 속할 수 있습니다.
• "이 세션에서는 안전한 경로를 찾기 전 세 번의 잘못된 리팩토링 (refactor)을 탐색함"은 어느 메모리 파일도 아닌 세션 히스토리 (session history)에 속합니다.

마지막 예시가 진짜 함정입니다. 가공되지 않은 전사 데이터 (raw transcripts)는 유익해 보이지만, 시간이 지나면 가치가 떨어집니다. 미래의 기여자들에게 모든 생각이 필요한 것은 아닙니다. 그들에게 필요한 것은 최종적인 영구적 사실, 제약 조건, 또는 결정 사항입니다.

APC와 APX가 여기서 조화를 이루는 이유

이 지점이 바로 APC/APX의 분리가 추상적인 개념을 넘어 유용해지는 부분입니다.

APC는 프로젝트에 큐레이션된 의미 (curated meaning)를 담을 수 있는 하나의 휴대 가능한 장소를 제공합니다.
APX는 일상적인 업무에 대해, 저장소로 유출하지 않으면서도 더 풍부한 상태 (state)를 유지할 수 있는 로컬 런타임을 제공합니다.

이는 프로젝트 계약 (project contract)을 잃지 않으면서도 런타임 (runtime)이 필요한 지저분한 메모리 (messy memory)를 계속 유지할 수 있도록 하면서, 도구, 머신, 또는 런타임을 전환할 수 있음을 의미합니다.

깔끔한 워크플로우 (workflow)는 다음과 같습니다:

1. APX에서 작업합니다.
2. 세션 (sessions), 회상 (recall), 그리고 런타임 메모리 (runtime memory)를 로컬 (local)에 유지합니다.
3. 내구성이 있고 정제된 사실 (durable, sanitized facts)만을 APC로 추출합니다.

모든 메모리가 버전 관리 (version control)를 받을 가치가 있는 것은 아닙니다.
하지만 모든 내구성 있는 프로젝트 사실 (durable project fact)은 휴대 가능한 보금자리를 가져야 합니다.