코덱스(Codex)에 "두 번째 뇌"를 추가해서 대화가 끊겨도 컨텍스트가 유지되는 메커니즘, 알고 계신가요? 그 이름은 바로 Agentmemory입니다. 설치 절차부터 설정, 자주 겪는 함정까지 모두 정리했습니다. 매번 같은 내용을 설명하는 게 귀찮거나 토큰을 낭비하고 싶지 않은 분들에게 반드시 필요한 글입니다.
매일 아침 Claude Code를 켜서 "어제부터 이어서 해줘"라고 입력하면, 돌아오는 대답은 "이전 세션의 내용을 알려주세요." 거의 매일 겪는 현상입니다.
세션이 끊기는 순간, 프로젝트 컨텍스트가 리셋됩니다. CLAUDE.md에 작성된 내용은 읽히지만, "3일 전에 논의한 버그"나 "지난주에 결정한 설계 정책의 배경" 같은 '컨텍스트의 무게'는 완전히 사라져 버립니다.
한 개발자가 이렇게 말했습니다.
기본적으로 Claude Code 세션 기록은 컴퓨터에 30일간만 저장됩니다. 모든 세션에 걸쳐 메모리를 유지하려면 더 길게 설정해야 합니다.
세션 기록의 기본 보존 기간은 30일입니다. 게다가 저장되는 것은 "문자열로서의 기록"일 뿐, 컨텍스트로 호출할 수 있는 메커니즘이 아닙니다.
코덱스(Codex) 쪽도 기본적으로 마찬가지입니다. GPT-5.5의 컨텍스트는 API 기준 100만 토큰, Codex CLI에서는 40만 토큰입니다. 물리적 크기는 충분해 보이지만, 실제로는 약 20만 토큰부터 정확도가 떨어지기 시작합니다.
그때 등장한 것이 바로 4,000 Stars를 돌파하며 화제가 된 Agentmemory입니다. 저는 일주일 동안 본격적으로 사용해 봤습니다. 결론부터 말씀드리면,
"Codex/Claude Code에 무한 메모리를 추가한다"는 표현은 절반은 과장이고, 절반은 사실입니다.
이 글에서는 "사실"인 부분을 극대화하는 방법과 "과장"인 부분을 만났을 때 피하는 방법을 설명하겠습니다.
1. Codex/Claude Code가 왜 "건망증"에 걸리는가?
Agentmemory를 논하기 전에, 기존 도구만으로는 왜 부족한지부터 명확히 하겠습니다. 이 부분을 건너뛰면 "편리한 메모리 도구를 추가했다"는 얘기로 끝나고 본질을 놓치게 됩니다.
컨텍스트 윈도우가 아무리 커도 실제로는 완전히 활용할 수 없습니다.
2026년 5월 기준, 주요 모델의 컨텍스트 윈도우는 다음과 같습니다.
● Claude Opus 4.7: 100만 토큰 (200K에서 확장)
● GPT-5.5: 100만 토큰 (API) / Codex CLI에서는 40만 토큰 제한
● Gemini 3.1 Pro: 100만 토큰
한국어로 환산하면 약 141만 자에 해당합니다. 한 권의 책뿐만 아니라 시리즈 전체를 넣을 수 있는 용량입니다. 숫자만 보면 "다 들어간다"고 생각할 수 있습니다.
하지만 Anthropic은 공식 엔지니어링 블로그에서 이렇게 밝혔습니다.
컨텍스트 윈도우의 토큰 수가 증가할수록, 모델이 해당 컨텍스트에서 정보를 정확하게 기억해내는 능력은 감소합니다.
물리적 용량이 정확성 유지 능력을 의미하지는 않습니다. 경험상 약 20만~40만 토큰 정도에서 Claude는 "방금 전에 말한 것"을 잊어버리기 시작합니다. 이를 일반적으로 컨텍스트 부패(context rot)라고 합니다.
공식 Claude Code에서도 발생한 "사고의 붕괴"
실제 사례를 하나 들어보겠습니다. 2026년 4월 23일, Anthropic이 공식 포스트모템을 발표했습니다.
3월 26일에 배포된 버그로 인해 "1시간 유휴 시간 이후 오래된 생각을 지우는 기능"이 세션 재개 후 매 턴마다 발동되었습니다.
그 결과, 표시되는 생각 길이의 중앙값이 다음과 같이 변했습니다.
● 1월: 2,200자
● 3월: 600자
73%나 붕괴된 것입니다. 약 한 달 동안 공식 Claude Code가 임의로 자신의 컨텍스트를 잘라내고 있었습니다.
이 사례가 중요한 이유는 컨텍스트 부패가 단순한 "사용자 실수"가 아니라 서비스 측 환경에 의해서도 발생할 수 있음을 보여주기 때문입니다. 아무리 CLAUDE.md를 깔끔하게 작성해도, 도구 쪽의 단 한 번의 튜닝 조정으로 "지난주 컨텍스트"가 휴지 조각이 되어 버릴 수 있습니다.
기존 솔루션의 한계 (CLAUDE.md / 자동 메모리)
Anthropic도 대책을 마련하고 있습니다. Claude Code의 자동 메모리 기능은 세션 간에 학습한 내용을 기억했다가 재시작 시 불러오는 메커니즘입니다. Claude Code 팀이 5월에 발표했습니다.
하지만 이 기능은 컴팩션(compaction)과 연동하여 작동하도록 설계되어 있습니다. "컨텍스트 압축 → 중요한 정보를 메모리로 이동"이라는 내부 흐름을 수행하며, AI가 각 압축 시 "무엇을 유지할지"를 결정합니다. 사용자는 이 결정 로직을 건드릴 수 없습니다.
게다가 자동 메모리는 Claude Code 전용입니다. Codex, Cursor, Cline, Hermes 같은 다른 에이전트에서 이를 읽을 수 있는 API는 없습니다. 여러 에이전트를 사용하는 경우, "같은 전제를 세 번 설명해야 하는" 상황이 일상화됩니다.
2. Agentmemory가 다른 점
이제 본론으로 들어갑니다. Agentmemory(공식 레포지토리: rohitg00/agentmemory)는 2026년 5월 15일 기준 8.8k Stars를 달성한 오픈소스 메모리 엔진입니다. 초기 "4,000+ Stars" 보고 이후 두 배 이상 증가했습니다. Apache 2.0 라이선스, TypeScript 기반이며 최신 릴리스는 v0.9.12(5월 13일)입니다. 완전히 자체 호스팅되며 외부 SaaS로 데이터가 전송되지 않습니다.
개발자의 철학
리드 개발자 Rohit Ghumare(@ghumare64)는 Agentmemory의 핵심을 한 문장으로 요약했습니다.
6개월 전에 agentmemory로 이걸 만들었습니다: AI 코딩 에이전트를 위한 영구 메모리. 같은 핵심 아이디어입니다. 매번 다시 유도하지 말고, 컴파일하세요.
"매번 다시 유도하지 말고, 컴파일하세요." 이것이 기존 도구와의 철학적 차이입니다.
CLAUDE.md는 "매번 다시 유도하기 위한 입력"이었습니다. 프로젝트 구조, 규칙, 과거 결정 사항. AI는 매 세션마다 이를 다시 읽고, 재해석하고, 그 후에 잊어버렸습니다. Agentmemory는 이 "재유도 루프"를 "컴파일된 메모리 계층"으로 대체합니다.
3계층 아키텍처 (README 요약)
공식 README에 따르면 내부 구조는 세 단계로 나뉩니다.
첫 번째는 캡처(Capture)입니다. 12개의 Claude Code 라이프사이클 훅을 사용하여 데이터를 자동으로 캡처하므로 memory_save를 수동으로 실행할 필요가 없습니다.
두 번째는 파이프라인(Pipeline)입니다. 중복 제거 → 개인정보 보호 필터(API 키/PII 자동 제거) → AI 기반 압축의 흐름을 통해 관찰 내용을 정리합니다.
세 번째는 검색(Retrieval)입니다. RRF k=60을 사용하여 세 가지 유형의 하이브리드 검색(BM25 / 벡터 / 그래프)을 융합합니다. BM25는 형태소 기반 키워드와 동의어 확장을 처리하고, 벡터는 밀집 임베딩의 코사인 유사도를 처리하며, 그래프는 지식 그래프 탐색을 처리합니다. 이를 Reciprocal Rank Fusion으로 융합하면 한 방법이 놓친 것을 다른 방법이 찾아냅니다. 결과는 세션 분산(세션당 최대 3개)으로 반환되어, 같은 세션의 결과만 나오는 문제를 해결합니다.
4계층 메모리 (에빙하우스에서 영감)
또 다른 흥미로운 점은 시간이 지나면서 "성장하는" 4계층 메모리로 설계되었다는 점입니다.
가장 아래 계층은 작업(Working) 메모리로, 원시 도구 실행 관찰 결과, 오류 로그, 명령어 기록 같은 단기 기억입니다. 일화(Episodic) 메모리로 올라가면 "무슨 일이 일어났는지"에 대한 세션 요약이 됩니다. 의미(Semantic) 수준에서는 "내가 아는 것", 추출된 지식, 패턴으로 변환됩니다. 가장 위 계층은 절차(Procedural) 메모리로, "진행 방법"에 대한 워크플로우와 절차로 구성됩니다.
자주 접근되는 기억은 강화되고, 참조되지 않는 기억은 에빙하우스 망각 곡선에 따라 쇠퇴합니다. 인간의 기억 구조를 모델로 한 메커니즘입니다. 이것이 "매번 다시 유도하지 말고 컴파일하라"는 말의 진정한 의미입니다.
경쟁사 대비 포지셔닝
솔직히 GitHub Stars만 보면 Agentmemory는 경쟁사에 비해 여전히 작습니다.
● Mem0: 55.7k Stars, 범용 메모리 계층, API/Cloud 우선
● Letta(구 MemGPT): 22.7k Stars, 에이전트 OS, 가상 컨텍스트 관리
● Agentmemory: 8.8k Stars, 코딩 에이전트 특화, 로컬 SQLite
숫자 싸움에서는 밀립니다. 하지만 Agentmemory가 빛을 발하는 부분은 코딩 에이전트 특화와 분리형 설계입니다. Rohit 자신이 이렇게 썼습니다.
실제 확장된 메모리 아키텍처, 에이전트 간 이식성, 특정 에이전트에 종속되지 않는 것을 원한다면 agentmemory를 확인해 보세요. 여러 하네스에서 작동하는 분리된 메모리 계층으로 설계되었습니다.
Cursor, Cline, Claude Code, Codex, Hermes에 동일한 메모리로 연결할 수 있습니다. 이것이 Mem0, Letta와의 차별점입니다. Mem0은 너무 범용적이어서 코딩 컨텍스트에 대한 자동 캡처가 약하고, Letta는 에이전트 OS이기 때문에 메모리 계층만 추출하기 어렵습니다.
Agentmemory는 "여러 코딩 에이전트를 동시에 사용하는 개발자"라는 틈새를 정확히 노렸습니다.
3. 3분 만에 시작하기 — 설치 및 초기 설정
실습을 해보겠습니다. 기본적인 흐름은 Node.js 환경만 갖춰져 있으면 Mac, Linux, Windows 모두 동일합니다.
1단계: 메모리 서버 시작
터미널을 열고 다음을 실행합니다.
메모리 서버 시작 (계속 실행)
npx @agentmemory/agentmemory
첫 번째 실행 시 의존성 다운로드에 1-2분 소요됩니다. 성공하면 http://localhost:3111에서 REST API가 시작됩니다. 상태는 다음으로 확인할 수 있습니다.
curl http://localhost:3111/agentmemory/health
→ {"status":"ok","version":"0.9.12"}
뷰어도 함께 시작되므로, 브라우저에서 http://localhost:3113을 열면 메모리 내용을 시각화할 수 있습니다.
2단계: 데모 데이터 삽입
빈 내용으로는 시각화하기 어려우니 샘플 데이터를 추가해 보겠습니다.
별도 터미널에서 실행
npx @agentmemory/agentmemory demo
이 명령어는 더미 세션 기록을 SQLite에 기록하여 뷰어에서 관찰할 수 있게 합니다.
3단계: Claude Code에 통합
Claude Code 쪽에서 가장 빠른 방법은 플러그인 마켓플레이스를 이용하는 것입니다.
Claude Code 내에서 실행
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory
이렇게 하면 다음이 자동으로 등록됩니다.
● 12개 훅 (SessionStart / PostToolUse / Stop 등 모든 라이프사이클)
● 4개 스킬 (recall / consolidate / export / governance)
● 51개 MCP 도구 (AGENTMEMORY_TOOLS=all이면 전체, 기본값은 15개 핵심 도구)
4단계: Codex CLI에 통합
Codex도 비슷한 스타일입니다.
codex plugin marketplace add rohitg00/agentmemory
codex plugin install agentmemory
Codex의 경우 AGENTMEMORY_URL=http://localhost:3111이 환경 변수로 자동 설정됩니다. 참고로 Codex는 Claude Code보다 MCP 동기성에 더 엄격하므로 서버가 다운되어 있으면 즉시 오류가 발생합니다. 서버를 계속 실행해 두는 것을 잊지 마세요.
5단계: Cursor / Cline 등에 연결
Cursor에서 사용하려면 ~/.cursor/mcp.json에 추가합니다.
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": { "AGENTMEMORY_URL": "http://localhost:3111" }
}
}
}
Cline, Hermes 및 기타 MCP 호환 편집기도 동일한 패턴으로 연결됩니다. Cursor의 MCP 설정은 단순히 껐다 켜는 것으로 반영되지 않는 함정이 있습니다. 이에 대해서는 "5가지 함정" 섹션에서 자세히 다루겠습니다.
6단계: 헬스 체크 루틴
설치 후 다음 체크리스트를 필수로 수행하세요.
1. 메모리 서버 연결 확인
curl http://localhost:3111/agentmemory/health
2. iii-engine 버전 확인 (v0.11.2 필요)
iii --version
3. 뷰어에서 메모리 확인
뷰어에 관찰 내용이 기록되어 있으면 설정이 완료된 것입니다. Node.js가 이미 설치되어 있다면 3분 이내에 완료됩니다.
4. 3가지 기본 동작 — 저장, 검색, 자동 압축
Agentmemory 사용법은 크게 세 가지 동작으로 정리할 수 있습니다.
동작 1: 저장 (자동 캡처가 기본)
Mem0이나 Letta에서는 memory_add(...) 같은 수동 명령어로 저장하는 것이 일반적입니다. Agentmemory는 철학이 다릅니다: 12개의 훅을 사용하여 모든 것을 자동으로 캡처합니다.
예를 들어, 다음 관찰 내용들은 아무것도 하지 않아도 기록됩니다.
● Bash 도구 실행 중 명령어와 출력 (PostToolUse 훅)
● 파일 편집 전후의 diff (PreToolUse / PostToolUse 훅)
● 세션 시작 시 관련 메모리 자동 주입 (SessionStart 훅)
● 세션 종료 시 요약 압축 (Stop 훅)
가장 큰 장점은 "사용자가 무엇을 저장할지 결정해야 하는 부담"이 사라진다는 점입니다. 이전에는 CLAUDE.md에서 "이건 중요하니 기록하자" 또는 "이건 지우자"고 생각했지만, 여기서는 그 결정 로직을 AI에 맡깁니다.
물론 수동 저장도 가능합니다. MCP 도구를 통해 memory_save를 호출하면 "이것은 중요하다"고 명시적으로 표시할 수 있습니다. 중요한 설계 결정은 자동 캡처에만 의존하지 않고 수동으로 저장하는 것이 더 안전합니다.
동작 2: 검색 (3중 하이브리드 + RRF)
검색은 MCP 도구를 사용하거나 REST API를 직접 호출하여 수행합니다. 대표적인 MCP 도구는 다음과 같습니다.
● memory_recall — 자연어로 관련 메모리 검색
● memory_smart_search — 하이브리드 검색의 전체 기능 버전
● memory_sessions — 세션별 목록
● memory_timeline — 시간순 정렬
● memory_relations — 관련 엔터티 그래프 탐색
REST API를 직접 호출하는 경우:
"Supabase 인증 관련 이전 수정 사항" 검색
curl -X POST http://localhost:3111/agentmemory/search \
-H "Content-Type: application/json" \
-d '{"query": "supabase auth fix", "limit": 5}'
반환되는 결과는 RRF k=60을 사용한 BM25 / 벡터 / 그래프의 융합입니다. 지연 시간은 P50 기준 20ms 미만(로컬 SQLite이므로 빠름).
공식 벤치마크(LongMemEval-S, 500개 질문, ICLR 2025)의 정확도는 다음과 같습니다.
● R@5: 95.2% (상위 5개 후보 내에 정답이 있을 확률)
● R@10: 98.6%
● MRR: 88.2%
참고로 이것은 "검색 정확도"이지 "엔드투엔드 QA 정확도"가 아닙니다. 정답이 후보군 어딘가에 있을 확률이며, Claude가 이를 사용하여 올바르게 답변할지는 별개의 문제입니다. 이 둘을 혼동하여 과신하지 마세요.
동작 3: 자동 압축 (시간이 지나면서 성장하는 4계층)
Stop 훅이 실행될 때마다 세 단계의 압축이 순차적으로 발생합니다.
먼저 작업(Working) → 일화(Episodic)가 원시 도구 로그를 세션 요약으로 압축합니다. 다음으로 일화(Episodic) → 의미(Semantic)가 여러 세션 이벤트에서 "패턴"과 "지식"을 추출합니다. 마지막으로 의미(Semantic) → 절차(Procedural)가 자주 반복되는 단계를 "워크플로우"로 고정합니다.
이를 통해 "모든 것을 저장하여 검색 노이즈를 만드는" 문제가 자동으로 해결됩니다. 세션 시작 시 주입되는 토큰 예산은 기본적으로 2,000 토큰입니다. 이는 "이전 컨텍스트"를 필요 충분한 형태로 복원하도록 설계되었습니다.
5. Codex / Claude Code 듀얼 사용 워크플로우
이제 실제 응용입니다. Codex와 Claude Code를 모두 진지하게 사용하는 분들을 위해 세 가지 워크플로우 패턴을 소개합니다.
패턴 1: 개인 개발을 위한 일일 워크플로우
agentmemory 서버를 계속 실행해 두면 Claude Code 시작 시 SessionStart 훅이 실행되어 전날의 일화(Episodic) 메모리가 자동으로 주입됩니다. "어제부터 이어서 해줘"라고 입력하지 않아도 Claude가 "Supabase RLS에서 막혔던 논의를 계속하자"는 내용을 이미 이해한 상태로 대화를 시작합니다.
코딩 중에는 PostToolUse 훅이 명령어, 출력, diff를 계속 SQLite에 기록합니다. 세션을 종료하면 Stop 훅이 작업(Working) 메모리를 일화(Episodic) 메모리로 압축합니다. 다음 날 아침, 이것이 자동으로 읽혀지면서 루프가 완성됩니다.
패턴 2: 여러 프로젝트 관리
Agentmemory는 메모리를 세 가지 범위로 나눌 수 있습니다. 사용자(user) 범위는 개인에 연결되어 코딩 규칙 선호도 같은 "개인 습관"을 담습니다. 프로젝트(project) 범위는 각 프로젝트별로 별도 관리되며, 별도의 SQLite 파일을 사용합니다. 로컬(local) 범위는 해당 머신에만 존재하며 팀 공유 모드에서도 외부로 나가지 않습니다.
프로젝트를 전환할 때 환경 변수를 AGENTMEMORY_PROJECT=foo-app으로 변경하면 다른 SQLite 파일을 참조합니다. 여러 프로젝트를 병렬로 운영하는 사람들에게 매우 효과적입니다. CLAUDE.md를 사용할 때는 프로젝트 A의 설계 결정이 프로젝트 B 논의에 새어 나오는 현상이 자주 발생했습니다. Agentmemory에서는 물리적으로 분리되어 있어 간섭이 없습니다.
패턴 3: 팀 공유 및 상장 기업과의 공동 개발
저희는 현재 상장 기업과 AI 에이전트를 공동 개발 중인데, MCP 서버 공유 모드가 여기서 미묘하게 효과적입니다. collab=true 플래그를 설정하면 여러 Codex / Claude Code 인스턴스가 동일한 메모리 서버를 참조할 수 있습니다.
서버 측
AGENTMEMORY_COLLAB=true npx @agentmemory/agentmemory --bind 0.0.0.0
팀 VPN을 통해 참조하면 여러 사람이 "동일한 프로젝트의 메모리"를 공유하면서 작업할 수 있습니다. 단, 개인정보 보호 필터를 강력하게 설정해야 합니다. API 키나 개인 정보가 섞이면 팀 전체에 공유되므로 .agentmemoryignore에서 제외 설정이 필수입니다. 이 부분은 "함정" 섹션에서 다루겠습니다.
듀얼 사용 시 고유한 함정
동일한 프로젝트에서 Codex와 Claude Code를 전환할 때 메모리는 공유되지만, 프롬프트 문법이 다릅니다. Claude Code의 /plugin 명령어는 Codex에서 작동하지 않으며, Codex의 codex plugin install은 Claude Code에서 작동하지 않습니다. "양쪽 모두에서 작동하는 도구"라도 각각 설정이 필요합니다. 첫 주에 많은 분들이 여기서 막힙니다.
6. 벤치마크 읽는 법 — 숫자를 "경험"으로 변환하기
공식 수치를 실제 감각으로 변환해 보겠습니다.
"92% 토큰 감소"의 진실
뉴스 속보나 Medium 기사에서 강조하는 "92% 감소"는 세션 기준입니다.
● 기존 CLAUDE.md 수동 운영: 세션당 약 22,000 토큰
● Agentmemory 사용 시: 세션당 약 1,900 토큰
● 감소율: 약 91-92%
세션 시작 시 컨텍스트 주입 토큰이 대폭 줄어듭니다. 연간 기준으로는 수치가 달라지며, README의 Token Savings 표에 따르면:
● LLM 요약 운영: 연간 약 65만 토큰 (약 $500)
● Agentmemory: 연간 약 17만 토큰 (약 $10)
토큰 기준으로는 약 74% 감소이지만, 비용 기준으로는 98% 감소입니다. $500가 $10이 됩니다. 차이가 나는 이유는 Agentmemory가 로컬 SQLite + 로컬 임베딩에서 실행되기 때문입니다. Mem0이나 Letta는 매번 LLM 기반 압축을 실행하는 반면, 운영 비용이 최소화됩니다.
"LongMemEval-S R@5 95.2%"의 의미
LongMemEval-S는 ICLR 2025에서 공개된 장기 메모리 벤치마크(500개 질문, 질문당 약 48개 세션, 약 115K 토큰 컨텍스트)입니다. 주요 도구를 비교하면 다음과 같습니다.
도구 | R@5 |
|---|---|
Agentmemory | 95.2% |
Mem0 (신규 알고리즘, 2026년 4월) | 94.8% |
Letta | 83.2% |
Cognee | 72.5% |
Zep | 71.0% |
Mem0 (기존 알고리즘) | 68.5% |
Mem0이 신규 알고리즘으로 추격하고 있으므로 숫자만으로 "압승"이라고 말하기는 어렵습니다. 하지만 Agentmemory가 코딩 에이전트에 특화된 자동 캡처 메커니즘과 결합하여 95.2%를 달성했기 때문에, 현재 평가는 "정확성 대 운영 부담" 트레이드오프에서 좋은 위치에 있다는 것입니다.
다시 말씀드리지만, R@5는 검색 정확도이며 Claude나 Codex가 최종적으로 올바른 답변을 제공할 확률이 아닙니다. 이 둘을 혼동하면 과대평가로 이어집니다.
Codex 400K vs Opus 4.7 1M: "물리적 vs 실용적"
벤치마크 수치를 보면서 또 하나 중요한 점을 발견했습니다.
Claude Opus 4.7은 컨텍스트를 100만 토큰으로 확장했습니다. GPT-5.5도 API 기준 100만 토큰입니다. 이것만 보면 "더 이상 메모리 도구가 필요 없다"고 생각할 수 있습니다.
하지만 Codex CLI는 실제로 40만 토큰으로 제한됩니다. 물리적 한계와 실용적 한계가 일치하지 않습니다. 게다가 Anthropic이 직접 밝혔듯이, 컨텍스트가 증가함에 따라 20만~40만 토큰에서 컨텍스트 부패가 시작됩니다.
즉, 물리적 크기가 커져도 메모리 엔진의 필요성은 줄어들지 않습니다. 오히려 "넓은 컨텍스트 윈도우를 효율적으로 사용하는 방법"이 새로운 기술 과제가 되었습니다.
7. 5가지 함정 — 제가 실제로 밟은 지뢰들
솔직히 말씀드리겠습니다. 실제로 실행하면서 밟은 지뢰 5가지를 골랐습니다. 공식 README나 인플루언서 트윗에는 나오지 않는 내용이며, GitHub Issue에서 재현 가능한 것만 엄선했습니다.
함정 1: iii-engine v0.11.2 버전 불일치
설치 직후 어떤 분들은 이런 오류를 만납니다.
iii: command not found
또는
Version mismatch: expected v0.11.2, got v0.11.0
Agentmemory는 내부적으로 iii-engine이라는 바이너리에 의존하며, 버전이 v0.11.2로 고정되어 있습니다. 다른 버전이 이미 설치되어 있으면 시작 단계에서 실패합니다. 해결 방법은 각 OS별 릴리스에서 고정 버전을 가져오는 것입니다.
macOS arm64
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz \
chmod +x ~/.local/bin/iii
Linux x64
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-x86_64-unknown-linux-gnu.tar.gz \
확인
iii --version # v0.11.2가 표시되어야 함
이 단계를 건너뛰면 이후 모든 것이 실패하므로 반드시 먼저 해결하세요.
함정 2: Issue #181 — 무한 루프를 통한 고스트 세션 대량 생성
이것은 심각하게 위험합니다. v0.9.1에서 보고된 치명적인 버그로, API 키가 설정되지 않은 상태에서 Stop 훅이 /summarize를 호출하면 무한히 자식 세션이 생성됩니다.
Stop 훅 → /summarize → 자식 세션 생성
↓
자식 세션의 Stop 훅도 실행 → /summarize → 더 많은 자식 세션
↓
(무한 루프)
GitHub Issue #181에 몇 분 만에 약 579개의 고스트 세션이 생성되었다는 보고가 있습니다. 세 가지 해결 방법이 있습니다.
옵션 1: agent-sdk 모드 비활성화 (권장)
export AGENTMEMORY_ALLOW_AGENT_SDK=false
옵션 2: 가짜 API 키로 강제 오류 발생
export AGENTMEMORY_ANTHROPIC_API_KEY="fake-key"
옵션 3: 실제 API 키 설정
export AGENTMEMORY_ANTHROPIC_API_KEY="sk-ant-..."
프로덕션 사용 시에는 옵션 1 또는 3이 안전합니다. 옵션 2는 "일단 움직이게만 하자"는 첫날에만 사용하세요.
함정 3: Issue #159 — MCP와 REST API가 별도 KV에서 실행됨
이것도 모르면 머리를 긁적이게 되는 현상입니다. MCP 도구(예: memory_search)를 호출하면 매번 빈 결과가 반환되는데, REST API(POST /agentmemory/search)로는 동일한 데이터에서 검색 결과가 나옵니다.
REST API: GET /agentmemory/sessions → 69개 관찰
MCP 도구: memory_sessions → [] (빈 값)
원인은 @agentmemory/mcp 패키지와 Agentmemory 서버가 완전히 별도의 KV 저장소를 사용하도록 설계되었기 때문입니다(Issue #159). MCP는 "로컬 KV"이고 서버는 "다른 KV"이며, 둘 사이에 통신 코드 경로가 없습니다. 2026년 5월 현재 이슈는 열려 있습니다. 해결 방법은:
● 옵션 1: REST API를 직접 사용 (MCP 도구 대신 curl 또는 fetch 사용)
● 옵션 2: /mcp 훅을 일시적으로 비활성화하고 서버만 실행
향후 수정 계획이 있지만, 현재로서는 이 사양을 감안하고 사용해야 합니다.
함정 4: Cursor / VSCode에서 MCP가 반영되지 않음
~/.cursor/mcp.json을 편집하고 Cursor를 재시작했는데, /mcp list에 Agentmemory가 나타나지 않습니다. 이 현상은 Cursor뿐만 아니라 일반적으로 Windows Store 앱에서 발생합니다.
GUI "X" 버튼으로 종료하면 WindowsApps 백그라운드 프로세스가 기본적으로 계속 실행됩니다. 이전 프로세스가 이전 설정을 메모리에 보유한 채 계속 실행됩니다. 완전 종료를 위한 의식이 필요합니다.
macOS
pkill -9 Cursor
Windows (PowerShell 관리자)
그런 후 다시 열기
open /Applications/Cursor.app
Windows (PowerShell)
→ 재시작
설정 파일을 의심하기 전에 '잔여 프로세스 확인'을 기본으로 하면 시간을 절약할 수 있습니다.
함정 5: 개인정보 필터에 의해 관찰이 조용히 삭제됨
"서버는 실행 중인데 뷰어에 관찰이 나타나지 않는" 현상도 첫 주에 자주 발생합니다. 로그를 보면 다음과 같은 경고가 표시됩니다:
[경고] private_tag 감지로 관찰 삭제됨
[경고] private_email 감지로 관찰 삭제됨
이는 의도된 동작이지 버그가 아닙니다. Agentmemory 의 개인정보 필터는 API 키, 비밀번호, 이메일 주소 및 PII를 자동으로 감지하고 해당 관찰을 기록하지 않고 삭제합니다. 보안에 좋은 기능이지만, 이 사실을 모르면 "작동하지 않는다"고 생각할 수 있습니다. 공존 전략은 다음과 같습니다:
.agentmemoryignore 파일로 제외
echo ".env" >> .agentmemoryignore
echo ".env.local" >> .agentmemoryignore
echo "*/.key" >> .agentmemoryignore
echo "*/password*" >> .agentmemoryignore
특히 실험 코드를 실행할 때 관찰에 API 키가 포함되는 경우가 많으므로, 사전에 이 파일을 배치하는 것이 안전합니다.
8. 요약 — '무한 메모리'는 단지 컨텍스트 창 확장이 아니다
Agentmemory 를 일주일 동안 집중적으로 사용한 후 가장 와닿은 느낌은 다음과 같습니다: '무한 메모리'라는 표현은 컨텍스트 창의 물리적 확장을 의미하는 것이 아닙니다.
1M 토큰으로 늘어나도 200K에서 정확도가 떨어진다면 결국 의미가 없습니다. 물리적 크기 경쟁은 이미 끝났다고 생각합니다. 대신 Agentmemory 가 제공하는 것은 의미론적 외부 뇌입니다.
구조화된 메모리를 세션 내부가 아닌 외부에 유지하세요. 필요할 때만 필요한 것을 불러오고, 사용이 끝나면 닫으세요. 기억할 가치가 있는 것은 시간이 지남에 따라 성장하고, 잊어도 되는 것은 조용히 사라집니다. 인간의 기억 구조와 동일합니다.
개발자의 마음에 일어나는 변화는 한 문장으로 설명할 수 있습니다: "세션이 끝나면 끝나는 것"에서 "세션 간에 기억이 성장하는 것"으로의 전환입니다.
업계 전체가 이 방향으로 움직이고 있습니다. DeepLearning.AI 의 에이전트 메모리 코스, Mem0 의 "상태 비저장 에이전트를 상태 저장으로 만든다"는 메시지, MemGPT 논문 "LLMs as Operating Systems" — 궁극적으로 이들은 모두 외부 메모리에 관한 것이며, Agentmemory 는 코딩 에이전트 맥락에서 하나의 솔루션입니다.
Mem0, Letta, 또는 자체 구현이든, Codex / Claude Code 를 진지하게 사용하는 사람들에게 현재 '무한 메모리' 감각을 시험해볼 수 있는 가장 빠른 도구입니다. 솔직히 설치할 가치가 있습니다.
9. 이 계정에 대하여
여기까지 읽어주신 분들께: 이 계정 @Codestudiopjbk는 세 명의 하드코어 Codex 사용자가 운영합니다.
● 대학원생 및 박사후 연구원을 위한 개발 프로그램 참여
● 300,000엔 상금 획득
● 현재 상장 기업과 AI 에이전트 공동 개발 중
저희의 일반적인 콘텐츠는 다음과 같습니다:
● GPT-5.5 / OpenAI Codex 를 사용한 구현 예제
● Codex 활용, CLI 자동화 및 개발 트렌드
● 최신 해외 GPT-5.5 / Codex 정보 번역 및 검증
● Claude Code 와의 실용적 비교 (수백 시간 사용 기반)
● 상장 기업과의 공동 개발에서 얻은 교훈
저희는 작동하는 제품을 세상에 내놓는 전체 과정(개발 철학부터 디자인, 구현 및 개선)에 대해 매일 게시합니다. 관심이 있으시면 팔로우하고 확인해보세요. 그만한 가치가 있습니다.
개발 관련 상담은 DM으로 보내주세요. Codex 도입, 자동화 설계 또는 AI 에이전트 구현에 대해 편하게 연락주세요.
참고문헌 및 인용
● [Rohit Ghumare (rohitg00/agentmemory)] (2026-05-13) Agentmemory v0.9.12 — 코딩 에이전트를 위한 메모리 엔진 — 공식 저장소, Apache-2.0, 8.8k 스타, TypeScript
● [Rohit Ghumare] (2026-04) "6개월 전에 agentmemory로 구축했습니다: AI 코딩 에이전트를 위한 지속적 메모리" — 개발자 철학
● [GitHub Issue #181] 중단 후크 → /summarize → agent-sdk 무한 재귀 — 함정 2의 주요 출처
● [GitHub Issue #159] 독립형 MCP 도구가 실행 중인 agentmemory 서버로 프록시되지 않음 — 함정 3의 주요 출처
● [Anthropic Engineering] AI 에이전트를 위한 효과적인 컨텍스트 엔지니어링 — 컨텍스트 엔지니어링에 대한 공식 가이드
● [Anthropic] (2026-04-23) 4월 23일 사후 분석 — Claude Code 사고 길이 붕괴 사건의 사회적 증거
● [Mem0] Mem0 소개 — Mem0 철학 및 Taranjeet Singh 인용
● [Letta] AI 에이전트 메모리 벤치마킹 — Letta 벤치마크 수치 출처
● [Charles Packer et al.] (2023-10) MemGPT: LLM을 운영 체제로 향하여 — 가상 컨텍스트 관리 논문, Agentmemory 의 이론적 전신
● [DeepLearning.AI] 에이전트 메모리: 메모리 인식 에이전트 구축 — Andrew Ng / Oracle 코스
