agentmemory: 코딩 에이전트를 위한 영속 메모리 엔진

코딩 에이전트를 오래 쓰다 보면 같은 설명을 반복하게 됩니다. 프로젝트 구조, 인증 방식, 테스트 관례, 이전에 고친 버그, 선호하는 코드 스타일 같은 것들입니다. CLAUDE.md, .cursorrules, AGENTS.md 같은 파일로 어느 정도 줄일 수는 있지만, 세션에서 실제로 일어난 사건까지 자동으로 쌓이기는 어렵습니다.

agentmemory ↗는 이 문제를 정면으로 다루는 오픈소스 프로젝트입니다. Claude Code, Codex CLI, Cursor, Gemini CLI, OpenClaw 등 여러 코딩 에이전트가 공유할 수 있는 영속 메모리 서버 + MCP 서버를 제공합니다.

이 글은 작성 시점 2026-05-18 · @agentmemory/agentmemory v0.9.18, GitHub README와 벤치마크 문서 스냅숏 기준으로 정리했습니다. 이전에 다룬 Karpathy의 LLM-Wiki와 무엇이 비슷하고 다른지도 함께 봅니다.

agentmemory가 해결하려는 문제

agentmemory의 README는 문제를 이렇게 잡습니다. 매 세션마다 같은 아키텍처를 다시 설명하고, 같은 버그를 다시 발견하고, 같은 선호를 다시 가르치는 일이 반복된다는 것입니다.

예를 들어 첫 번째 세션에서 JWT 인증을 만들고, 두 번째 세션에서 rate limiting을 요청한다고 해보겠습니다. 일반적인 에이전트는 이전 세션의 구현 맥락을 모릅니다. 사용자가 다시 “인증은 jose 미들웨어를 쓰고, 테스트는 토큰 검증을 커버한다”고 설명해야 합니다.

agentmemory는 이 반복을 줄이기 위해 세션에서 일어난 일을 관찰하고, 검색 가능한 메모리로 압축한 뒤, 다음 세션 시작 시 관련 컨텍스트를 주입합니다.

flowchart LR
  A[에이전트 세션] --> B[hook / MCP / REST로 관찰]
  B --> C[agentmemory 서버]
  C --> D[SQLite + iii-engine]
  C --> E[BM25 + Vector + Graph 검색]
  E --> F[다음 세션에 관련 기억 주입]

  G[Claude Code] --> C
  H[Codex CLI] --> C
  I[Cursor / Gemini CLI / OpenClaw] --> C

핵심은 “에이전트별 메모리 파일”이 아니라 여러 에이전트가 하나의 메모리 서버를 공유한다는 점입니다. Claude Code에서 쌓은 기억을 Codex CLI나 OpenClaw 쪽에서도 MCP/REST를 통해 활용할 수 있는 구조입니다.

설치와 기본 흐름

README 기준 기본 실행은 단순합니다.

npm install -g @agentmemory/agentmemory
agentmemory
agentmemory demo
agentmemory connect claude-code

또는 전역 설치 없이 바로 실행할 수도 있습니다.

npx @agentmemory/agentmemory

서버는 기본적으로 로컬에서 동작합니다. REST API는 localhost:3111, 실시간 viewer는 localhost:3113을 사용합니다. MCP 클라이언트에서는 @agentmemory/mcp를 붙여 메모리 도구를 노출하는 방식입니다.

OpenClaw 같은 MCP 호스트에서는 대략 이런 형태로 연결합니다.

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

메모리 엔진으로서의 특징

agentmemory가 단순한 “메모장”과 다른 지점은 세 가지입니다.

1. 자동 캡처

Claude Code 플러그인은 12개 hook을 등록하고, Codex 플러그인은 6개 lifecycle hook을 등록한다고 설명합니다. 세션 시작, 사용자 프롬프트 제출, 도구 사용 전후, compact 전후 같은 이벤트를 관찰해 메모리 후보를 수집하는 방식입니다.

사용자가 매번 remember()를 호출하지 않아도 세션 흐름에서 의미 있는 단서를 잡으려는 설계입니다.

2. 하이브리드 검색

검색은 BM25, 벡터 검색, 그래프 탐색을 조합하는 쪽입니다. README와 비교 문서에서는 이를 “BM25 + Vector + Graph”로 설명하고, Reciprocal Rank Fusion 계열의 결합을 언급합니다.

BM25는 정확한 키워드에 강하고, 벡터 검색은 의미 유사도에 강하며, 그래프는 엔티티 간 관계를 따라갈 수 있습니다. 코딩 세션 메모리에서는 파일명, 함수명, 결정 이유, 버그 원인처럼 검색 단서의 형태가 다양하므로 단일 검색 방식보다 이런 조합이 잘 맞습니다.

3. 메모리 lifecycle

agentmemory의 설계 문서인 LLM Wiki v2 gist ↗는 Karpathy의 LLM-Wiki를 확장하면서 “memory lifecycle”을 핵심 누락 계층으로 봅니다.

여기에는 confidence scoring, supersession, forgetting, consolidation tiers가 포함됩니다.

• confidence scoring — 근거 수, 최근 확인 시점, 모순 여부를 바탕으로 사실의 신뢰도를 추적
• supersession — 새 정보가 기존 정보를 대체할 때 이전 내용을 stale로 표시
• forgetting — 오래 쓰이지 않는 임시 사실을 낮은 우선순위로 밀어냄
• consolidation tiers — working → episodic → semantic → procedural 단계로 압축·승격

이 관점은 agentmemory를 단순 저장소가 아니라 “코딩 에이전트가 오래 일하기 위한 운영 메모리”에 가깝게 만듭니다.

벤치마크는 어떻게 봐야 하나

agentmemory README는 LongMemEval-S 기준 검색 성능을 공개합니다. benchmark/LONGMEMEVAL.md ↗에 따르면 LongMemEval-S 500문항, 질문당 약 48개 세션, 약 115K 토큰 환경에서 retrieval-only 평가를 수행했습니다.

주요 수치는 다음과 같습니다.

흥미로운 점은 BM25만으로도 R@5 86.2%가 나오고, 벡터를 더하면 95.2%까지 올라간다는 부분입니다. 코딩 메모리에서도 정확한 파일명·개념명 검색과 의미 검색이 함께 필요하다는 직관과 잘 맞습니다.

비교 문서도 주의가 필요합니다. agentmemory와 MemPalace는 LongMemEval-S 기준이고, Mem0와 Letta는 LoCoMo 기준 수치를 함께 놓습니다. 문서 스스로도 “apples vs oranges”라고 caveat를 둡니다. 따라서 “절대 순위”보다 agentmemory가 어떤 설계 선택을 했고, 어떤 벤치마크로 검증하려고 하는가를 보는 편이 안전합니다.

Karpathy의 LLM-Wiki와 무엇이 다른가

agentmemory README는 스스로를 Karpathy의 LLM-Wiki 패턴을 확장한 구현체로 설명합니다. 둘 다 “매번 다시 읽지 말고, 지식이 쌓이게 하자”는 문제의식은 같습니다. 하지만 초점은 꽤 다릅니다.

LLM-Wiki는 패턴, agentmemory는 런타임

Karpathy의 LLM-Wiki는 구현체라기보다 작업 방식입니다. raw source, wiki, schema라는 3계층을 두고, Ingest / Query / Lint라는 동사로 위키를 유지합니다. 핵심 산출물은 LLM이 직접 쓰는 마크다운 위키입니다.

agentmemory는 여기서 한 단계 더 내려와 실행 가능한 런타임을 제공합니다. 서버를 띄우고, 에이전트 hook을 연결하고, MCP 도구를 노출하고, viewer에서 세션을 replay합니다. 즉 LLM-Wiki가 “지식을 이렇게 관리하자”라면, agentmemory는 “코딩 에이전트 세션에서 그 관리를 자동화하자”에 가깝습니다.

LLM-Wiki는 문서 중심, agentmemory는 세션 중심

LLM-Wiki의 입력은 논문, 기사, 노트, 메시지 같은 raw source입니다. agentmemory의 주요 입력은 에이전트 세션입니다. 프롬프트, 도구 호출, 결과, 코드 변경 맥락, 사용자 선호가 모두 기억 후보가 됩니다.

그래서 LLM-Wiki는 개인 지식 베이스나 리서치 위키에 잘 맞고, agentmemory는 장기 코딩 작업의 세션 연속성에 더 잘 맞습니다.

LLM-Wiki는 수동 운영을 전제로 하고, agentmemory는 이벤트 기반 자동화를 지향한다

Karpathy의 원문은 사용자가 LLM에게 Ingest, Query, Lint를 요청하는 흐름에 가깝습니다. 반면 agentmemory는 hook, MCP, REST를 통해 세션 이벤트를 자동으로 받아들이고, 다음 세션에 필요한 기억을 주입하려고 합니다.

LLM Wiki v2 gist는 이 차이를 “manual에서 event-driven으로”라는 표현으로 설명합니다. 새 source가 오면 자동 ingest, 세션 시작 시 관련 context load, 세션 종료 시 observation 압축, 스케줄 기반 lint와 consolidation 같은 흐름을 제안합니다.

LLM-Wiki는 파일 위키, agentmemory는 검색·그래프·거버넌스 계층을 붙인다

Karpathy의 LLM-Wiki는 마크다운 페이지와 wikilink만으로도 꽤 멀리 갈 수 있다는 아이디어입니다. agentmemory는 여기에서 confidence, graph, hybrid search, audit trail, privacy filtering, delete governance 같은 운영 계층을 더합니다.

요약하면 이렇게 볼 수 있습니다.

어디에 잘 맞을까

agentmemory가 특히 잘 맞아 보이는 경우는 다음과 같습니다.

• Claude Code, Codex CLI, Cursor, OpenClaw를 번갈아 쓰는 경우
• 같은 코드베이스를 여러 세션에 걸쳐 계속 고치는 경우
• 프로젝트별 의사결정, 파일 위치, 테스트 관례를 자주 다시 설명하는 경우
• 장기 작업에서 “지난번에 왜 이렇게 했지?”를 자주 묻는 경우
• MCP 기반 도구 체인을 이미 운영하고 있는 경우

반대로 단순한 개인 지식 정리에는 조금 무거울 수 있습니다. 논문·기사·노트를 위키로 정리하는 목적이라면, 먼저 Karpathy식 LLM-Wiki처럼 Obsidian 볼트와 schema 문서 한 장으로 시작하는 편이 더 가볍습니다.

마무리

agentmemory는 코딩 에이전트의 메모리 문제를 파일 하나로 해결하려 하지 않습니다. 세션 이벤트를 관찰하고, hybrid search로 필요한 기억을 찾고, MCP/REST로 여러 에이전트에 공유하는 쪽을 택합니다.

Karpathy의 LLM-Wiki가 “LLM이 직접 관리하는 개인 지식 지도”라면, agentmemory는 그 아이디어를 코딩 에이전트 런타임으로 끌어내린 구현체에 가깝습니다. 특히 Claude Code, Codex CLI, OpenClaw처럼 세션 기반 에이전트를 많이 쓰는 환경에서는 꽤 흥미로운 방향입니다.

다만 벤치마크는 retrieval-only라는 점, iii-engine 런타임 의존성이 있다는 점, 자동 캡처가 많아질수록 privacy/governance 설계가 중요해진다는 점은 함께 봐야 합니다. “기억하는 에이전트”는 편리하지만, 무엇을 기억하고 무엇을 잊을지 정하는 일이 결국 운영 품질을 가릅니다.

참고 자료

• rohitg00/agentmemory ↗
• agentmemory LongMemEval benchmark ↗
• agentmemory benchmark comparison ↗
• LLM Wiki v2 gist ↗
• Karpathy의 LLM-Wiki