코딩 에이전트 메모리: Claude Code, Codex, Cursor

Claude Code, Codex, Cursor 같은 코딩 에이전트의 공유 메모리는 버전 관리하는 AGENTS.md와 짧은 작업 인계 메모부터 시작하세요. 자동 수집과 인계가 필요하면 ai-memory를, 세션 기록을 검토하고 재사용할 지식을 승인하려면 Beacon을 추가하세요. 어느 쪽을 선택하든 반드시 지켜야 할 프로젝트 규칙은 저장소에 두세요.

도구를 바꿔도 남아야 할 정보를 구분하세요

오래 유지할 결정과 현재 작업의 진행 상태를 따로 보관하세요. 새 에이전트는 코드를 읽을 수 있어도 특정 접근을 포기한 이유, 어제 알려 준 수정 사항, 미완료 작업에서 다음에 해야 할 일까지 알지는 못할 수 있습니다.

세 가지 컨텍스트는 서로 다른 문제를 해결합니다. 지침은 일하는 방법을, 작업 인계 메모는 어디까지 진행했는지를 설명하고, 세션 이력은 두 가지를 뒷받침하는 근거를 제공합니다. 하나를 공유한다고 나머지 컨텍스트나 실행 중인 프로세스, 도구 사용 권한까지 자동으로 이전되지는 않습니다.

방식	이어서 사용할 수 있는 정보	선택할 상황	선택을 바꿀 조건
저장소의 지침과 작업 인계 파일	직접 관리하는 규칙, 결정, 작업 진행 상태	적은 수의 메모로 충분하며 Git과 함께 관리하고 싶을 때	사람들이 메모 갱신을 자주 잊는다면 서비스 도입을 검토하세요
ai-memory	수집된 관찰 내용, 검색 가능한 Markdown 위키, 에이전트 간 작업 인계	에이전트를 자주 바꾸며 수집과 검색을 자동화하고 싶을 때	훅, 인증 정보, 서버를 관리하는 부담이 이점보다 크다면 파일을 유지하세요
Beacon	공통 형식으로 정리된 세션 기록과 명시적으로 승인한 프로젝트 지식	발생한 일을 살펴보고 반복해서 알려 준 수정 사항을 검토된 지식으로 남기고 싶을 때	기록과 지식 검토보다 자동 인계가 중요하다면 ai-memory를 우선하세요

2026-10-21 기준으로 이 비교는 ai-memory v3.1.2와 Beacon v1.3.45를 다룹니다. 차이는 구조에 있습니다. ai-memory는 Git으로 관리하는 Markdown 위키 외에도 서버, 훅, MCP를 포함하며, Beacon에서는 세션 수집과 메모리 승인이 별도 절차입니다.

AGENTS.md와 짧은 작업 인계 메모부터 시작하세요

AGENTS.md를 프로젝트의 공통 참고 문서로 삼고 각 도구가 실제로 읽는지 확인하세요. 기본 제공되는 지침 로딩 규칙은 도구마다 다릅니다.

Codex: 프로젝트 루트에서 작업 디렉터리까지 이어지는 지침 파일을 읽습니다. 같은 디렉터리에서는 AGENTS.override.md가 AGENTS.md보다 우선합니다. Codex의 지침 탐색 규칙을 참고하세요.
Cursor: 루트와 하위 디렉터리의 AGENTS.md를 지원합니다. 적용 범위를 지정한 Cursor 전용 규칙이 필요하면 .cursor/rules/*.mdc에 두세요. 자세한 내용은 Cursor 규칙 문서에 나와 있습니다.
Claude Code: v2.1.277부터 AGENTS.md를 직접 읽을 수 있습니다. 다만 기본 동작은 작업 디렉터리나 상위 디렉터리에 있는 파일 중 로딩 조건을 충족하는 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md를 우선합니다. 기존 Claude 지침이 있거나 직접 읽기를 지원하지 않는 세션이라면, 루트의 AGENTS.md 옆에 있는 CLAUDE.md에 @AGENTS.md 한 줄을 추가하세요. Claude Code 메모리 가이드에서 두 방법을 확인할 수 있습니다.

간단히 시험하려면 루트의 AGENTS.md에 다음 규칙을 넣으세요. 파일이 이미 있다면 기존 지침과 합쳐서 사용하세요. 아래 예시는 의존성을 바꾸기 전에 공식 릴리스 노트와 관련 테스트를 확인하고, 작업 재개 시 인계 파일을 읽으며, 과거 기록을 현재 코드와 대조하라는 지침입니다.

## Working context

- Before changing a dependency version, read its official release notes
  and run the tests for the affected component.
- When resuming work, read docs/agent-handoff.md if it exists.
- Treat handoffs as historical evidence. Check old commands, paths and
  conclusions against the current checkout before acting.

실제 작업을 마친 뒤에는 에이전트에게 다음과 같이 인계 메모를 작성하도록 요청하세요. 목표와 현재 브랜치·커밋, 확정된 결정, 실제 실행한 명령과 결과, 남은 불확실성, 다음 행동을 기록하라는 프롬프트입니다. 실패한 접근과 성공한 접근을 구분하고 인증 정보나 전체 대화는 넣지 않도록 합니다.

Write docs/agent-handoff.md with the goal, current branch and commit,
confirmed decisions, commands actually run and their results,
remaining uncertainty, and the next concrete action.
Distinguish failed approaches from successful ones.
Do not include credentials or copy the full conversation.

코드 변경 사항과 함께 이 파일을 검토하세요. 계속 적용할 규칙은 AGENTS.md에 두고, 작업이 진행되면 인계 메모를 갱신하세요.

각 도구에서 새 세션을 열고 의존성 업데이트에 어떤 확인 절차가 적용되는지, 그 절차를 어느 파일에서 읽었는지 물어보세요. Claude Code에서는 /context로 로딩된 메모리 파일을 살펴볼 수도 있습니다. Codex가 규칙을 놓쳤다면 같은 내용을 여러 곳에 복사하기 전에 작업 디렉터리와 지침을 덮어쓰는 파일부터 확인하세요.

도구 자체의 자동 메모리도 해당 도구 안에서는 유용합니다. Claude Code는 프로젝트 메모를 ~/.claude/projects/<project>/memory/에 저장합니다. Codex 로컬 메모리는 직접 활성화해야 하며, ~/.codex/memories/에 저장되고 /memories로 관리합니다. 이처럼 분리된 저장소는 여러 도구가 함께 쓰는 작업 인계 형식이 아닙니다.

ai-memory로 수집과 작업 인계를 자동화하세요

에이전트가 서비스를 통해 프로젝트 컨텍스트를 기록하고 다시 읽게 하려면 ai-memory를 선택하세요. 원본 지식은 Git으로 관리하는 Markdown 위키에 있고, SQLite는 그로부터 만든 검색 인덱스 역할을 합니다. MCP는 에이전트에 메모리 도구를 제공하고, 세션 이벤트에 반응하는 훅은 수집과 세션 시작·종료 시의 처리를 담당합니다.

설치하고 에이전트를 연결하세요

다음 예제는 macOS에서 Bash를 사용하는 사용자 범위의 신규 설치를 대상으로 합니다. Git과 코딩 에이전트가 이미 설치되어 있고 에이전트 인증도 끝났다고 가정합니다. 다른 플랫폼은 해당 릴리스의 설치 가이드를 참고하세요.

curl -fsSLo /tmp/ai-memory-install-v3.1.2.sh \
  https://github.com/akitaonrails/ai-memory/releases/download/v3.1.2/install.sh
less /tmp/ai-memory-install-v3.1.2.sh
AI_MEMORY_VERSION=3.1.2 sh /tmp/ai-memory-install-v3.1.2.sh
export PATH="$HOME/.local/bin:$PATH"
ai-memory --version
ai-memory setup --plan --agent claude-code --agent codex --agent cursor
ai-memory setup --agent claude-code --agent codex --agent cursor
ai-memory status

표시되어야 할 버전은 3.1.2입니다. 설정을 적용하기 전에 계획을 검토하세요. 이 설정은 백그라운드 서비스를 만들고 사용자 범위에서 MCP, 훅, 스킬 구성을 바꿉니다. 따라서 선택한 에이전트로 작업하는 다른 프로젝트도 수집 대상에 포함될 수 있습니다.

또한 이 릴리스의 Codex 설정 생성 코드는 ai-memory 도구에 default_tools_approval_mode = "approve"를 설정합니다. 메모리 변경에 확인 절차를 요구하고 싶다면 이 권한을 검토하세요.

이 릴리스의 Codex 기본 등록 방식에서는 생성된 bearer 토큰을 실행 환경에 불러와야 합니다. macOS의 기본 데이터 디렉터리를 쓴다면 다음 Bash 명령은 토큰을 화면에 출력하지 않고 불러옵니다.

AI_MEMORY_AUTH_TOKEN="$(cat "$HOME/Library/Application Support/ai-memory/auth-tokens/default")"
export AI_MEMORY_AUTH_TOKEN
codex

등록 설정은 AI_MEMORY_AUTH_TOKEN을 참조합니다. MCP 설치 가이드에 이 Codex 전용 요구 사항이 설명되어 있습니다. 데이터 디렉터리를 바꿨다면 ai-memory status가 표시하는 실제 경로를 사용하세요.

Codex 안에서 /hooks를 실행하고 설치된 ai-memory 훅을 신뢰하도록 설정하세요. 설정 후 Claude Code와 Cursor를 다시 시작하세요. 설치 프로그램의 종료 코드만으로는 Codex가 아직 신뢰하지 않는 훅을 실행할 것이라고 판단할 수 없습니다.

저장된 지식과 작업 인계를 따로 확인하세요

첫 확인에서는 같은 저장소 작업 사본을 사용하고 프로젝트 범위를 명시하세요. 루트에서 ai-memory project init을 실행한 뒤 워크스페이스와 프로젝트 이름을 확인하거나 선택하세요. 이 명령은 .ai-memory.toml을 작성합니다. 모든 에이전트에서 두 이름을 동일하게 사용하세요.

Claude Code에 다음 프롬프트를 입력하세요. 프로젝트 범위를 읽고 연결 상태를 확인한 뒤, 의존성 업데이트 규칙을 시험 페이지에 저장하고 다시 읽어 저장 경로를 확인하게 합니다.

Read .ai-memory.toml and use its workspace and project for ai-memory calls.
Call memory_status.
Use memory_write_page to save decisions/shared-memory-demo.md with:
"Memory trial: before a dependency upgrade, check the official release
notes and run the affected component's tests."
Read the page back with memory_read_page and report its stored path.

같은 작업 사본에서 Codex나 Cursor를 여세요. Memory trial을 대상으로 memory_query를 호출하고, 일치하는 결과에 대해 memory_read_page를 호출하도록 요청하세요. 실제 도구 결과에 저장한 경로와 결정 내용이 나와야 성공입니다. 검색하지 않고 그럴듯한 답을 하는 것만으로는 충분하지 않습니다. 이 작업들은 프로그래밍 방식의 메모리 접근 문서에 설명되어 있습니다.

다음으로 작은 실제 작업에서 자동 인계를 확인하세요. 아직 하지 않은 행동 하나를 명확히 남기고 세션을 정상 종료한 다음, 같은 디렉터리에서 다른 에이전트를 여세요. 새 에이전트의 시작 컨텍스트에 그 미완료 행동이 나타나야 합니다. 지속적으로 보관하는 페이지는 계속 검색할 수 있지만, 인계 정보는 다음 세션에 넘기는 용도이며 한 번만 가져갈 수 있습니다.

검색이 실패하면 ai-memory doctor를 실행하고 MCP 연결 상태와 워크스페이스·프로젝트 조합을 확인하세요. Codex 인증이 실패했다면 실행 환경을, 인계 정보가 없다면 훅 신뢰 설정과 세션 수집을 확인해야 합니다. 서로 다른 원인을 같은 장애로 취급하지 마세요.

Beacon으로 기록을 검토하고 지식을 승인하세요

재사용할 지식의 근거를 직접 확인하려면 Beacon을 선택하세요. Beacon은 OpenTelemetry, 훅, 로컬 세션 파일 복구 등의 수집 방법을 함께 쓰며, 수집 가능한 범위는 도구에 따라 다릅니다. 세션을 수집했다고 해서 그 내용이 자동으로 승인된 메모리가 되지는 않습니다.

로컬 수집기를 설치하세요

macOS에서 Bash와 Homebrew를 사용하는 신규 설치에서는 여기서 다루는 세 에이전트만 설정하세요.

brew update
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon
beacon version
BEACON_ONBOARDING=0 beacon endpoint install \
  --harness claude,codex,cursor --no-backfill
beacon endpoint status

확인 날짜 기준으로 Homebrew 포뮬러가 제공하는 버전은 1.3.45입니다. 이 예제는 과거 세션 가져오기와 대화형 초기 설정 마법사를 건너뜁니다. 선택한 에이전트의 수집 기능을 사용자 범위에 설치하므로, 다른 저장소에서 수행한 작업도 로그에 들어갈 수 있습니다.

일반 초기 설정 마법사에서는 Beacon Cloud가 미리 선택되어 있습니다. 신규 설치에서 마법사를 건너뛰고 --connect를 생략하면 Cloud 등록을 피할 수 있습니다. 이미 연결된 설치를 해제하는 동작은 아니므로, 기존 연결을 끊으려면 beacon endpoint disconnect를 사용하세요. 데이터 목적지 선택은 초기 설정 문서에 설명되어 있습니다.

설정 후 에이전트를 다시 시작하고 Codex의 /hooks에서 Beacon 훅을 검토한 뒤 신뢰하도록 설정하세요. 시험할 저장소에서 짧은 세션을 진행하며 앞서 제시한 의존성 검토 규칙을 명시적으로 알려 주세요.

지식 하나를 만들고 승인한 뒤 조회하세요

재사용할 지식을 만들기 전에 기록된 세션부터 살펴보세요. 저장소 루트에서 다음 명령을 실행하세요.

beacon endpoint traces list --limit 10
read -r -p "Trace ID from the trial session: " BEACON_TRACE_ID
beacon endpoint traces show "$BEACON_TRACE_ID" --limit 150

목록에 반환된 실제 ID를 선택하고, 그 이벤트에 알려 준 규칙이 포함되어 있는지 확인하세요. 그런 다음 메모리 후보를 만드세요. 여기서는 해당 저장소에서 의존성 버전을 바꾸기 전에 공식 릴리스 노트를 읽고 관련 컴포넌트의 테스트를 실행하라는 규칙을 제안합니다.

beacon memory candidates create \
  --trace "$BEACON_TRACE_ID" \
  --kind convention \
  --title "Dependency upgrades require release-note review" \
  --applicability "Before changing a dependency version in this repository" \
  --body "Check the dependency's official release notes and run the affected component's tests before proposing the upgrade."
read -r -p "Candidate ID returned above: " BEACON_CANDIDATE_ID
beacon memory candidates show "$BEACON_CANDIDATE_ID"

후보 내용과 원본 근거를 검토하세요. 해당 지식을 받아들이기로 결정한 다음에만 승인하세요.

beacon memory candidates approve "$BEACON_CANDIDATE_ID" \
  --reason "Reviewed against the source trace"

이처럼 후보 텍스트를 직접 작성하는 방식은 평가기를 호출하지 않습니다. Beacon의 선택적 평가기는 세션 기록에 점수를 매길 뿐, 완성된 지식 문장을 작성하지 않습니다. 두 방식 모두 메모리 명령 참조 문서에 나와 있습니다.

이제 같은 저장소에서 작업하는 다른 에이전트에게 다음 명령을 실행하도록 요청하세요.

beacon memory list -q "dependency upgrades" --json

반환된 메모리 ID를 beacon memory show에 전달하고, 이 규칙이 언제 적용되는지 설명하도록 하세요. 기대하는 결과는 현재 프로젝트에 연결된 승인된 지식입니다. 결과가 비어 있다면 승인 상태, 프로젝트 범위, 검색어를 확인하세요. Beacon의 로컬 검색에서는 검색어의 모든 단어가 일치해야 합니다.

이 CLI 경로에는 MCP가 필요하지 않습니다. 에이전트 도구로 조회하려면 Beacon의 별도 로컬 MCP 서버가 제공하는 search_memory, get_memory, get_memory_context를 사용할 수 있습니다. 이 서버는 승인된 로컬 메모리를 읽습니다. Beacon Cloud는 별도 저장소를 쓰며, 기기를 연결해도 두 메모리 저장소가 동기화되지는 않습니다.

잘못된 지식, 비공개 데이터, 비용을 관리하세요

적용 범위가 분명한 결론을 근거와 함께 저장하고, 조회한 텍스트는 과거의 정보로 취급하세요. 실패한 시도는 프로젝트의 영구적인 규칙 때문이 아니라 일시적인 장애나 잘못된 브랜치에서의 작업 때문일 수 있습니다. 적용 상황, 원본 작업이나 커밋, 검증 결과, 검토 날짜를 기록하고, 실제 동작이 바뀌면 메모를 수정하거나 더 이상 쓰지 않도록 정리하세요.

승인은 절차일 뿐 사람이 내용을 검토했다는 증거는 아닙니다. Beacon 후보를 제안하는 에이전트와 검토하는 사람을 구분하고, 저장된 지침이 현재 요구 사항이나 권한보다 우선하지 않도록 하세요.

수집을 켜면 비공개 정보가 남는 위치도 달라집니다. .ai-memory.toml의 ai-memory [capture] ignore_paths 규칙은 지원되는 경로 기반 이벤트를 제외할 수 있지만, 사용 문서는 이것이 프롬프트와 출력 전반의 데이터 유출을 막는 필터는 아니라고 명시합니다. 재사용할 메모에 인증 정보나 고객 데이터를 넣지 마세요. 현재 Markdown 페이지를 지워도 Git에는 이전 버전이 남을 수 있습니다.

작업 세션을 Beacon Cloud로 보내기 전에는 현재 개인정보 처리방침을 확인하세요. 2026-10-21 기준으로 연구와 모델 학습 목적의 사용은 기본 활성화되어 있으며 거부할 수 있습니다. 메타데이터만 보내는 모드에도 경로와 명령줄 같은 정보가 포함됩니다. 클라우드 코딩 모델을 쓴다면 로컬 메모리에서 조회해 그 모델의 컨텍스트에 넣은 내용도 모델 입력이 됩니다.

전체 작업에 드는 비용을 계산하세요. ai-memory의 기본 메모리 경로에는 생성형 모델 API 키가 필요하지 않지만, 검색용 벡터를 만드는 기본 로컬 임베딩 모델이 처음 시작할 때 다운로드될 수 있습니다. Beacon에서 지식의 문장을 직접 작성하는 방식은 평가기 호출을 피합니다.

그래도 코딩 에이전트의 일반 사용량, 조회한 내용으로 늘어난 입력, 선택적인 클라우드 처리, 저장 공간, 검토 시간은 비용에 영향을 줍니다. 어느 구조도 그 자체만으로 총비용이 더 낮다고 입증하지는 않습니다.

모든 프로젝트에 메모리 계층을 도입하기 전에 실제 작업에서 도구를 한 번 바꿔 보세요. 올바른 결정을 조회하고, 미완료 행동을 파악하고, 근거를 확인한 뒤 현재 작업 사본에 맞춰 이어서 진행하세요. 이 과정이 실패한다면 메모리를 더 쌓기 전에 로딩, 범위, 수집 문제부터 해결하세요.