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

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

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

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

agentmemory가 해결하려는 문제

agentmemory의 README가 꼽는 문제는 반복입니다. 사용자는 매 세션마다 같은 아키텍처를 다시 설명하고, 같은 버그를 다시 발견하고, 같은 선호를 다시 가르칩니다.

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

agentmemory는 세션에서 일어난 일을 관찰해 검색 가능한 메모리로 압축합니다. 다음 세션이 시작되면 관련 컨텍스트를 주입합니다.

flowchart TD
  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. 자동 캡처

README에 따르면 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 ↗에 따르면 평가는 retrieval-only입니다. LongMemEval-S 500문항, 질문당 약 48개 세션, 약 115K 토큰 환경에서 수행했습니다.

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

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으로”라고 표현합니다. gist가 제안하는 흐름은 다음과 같습니다. 새 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