개요

AI coding agent를 쓰다 보면 매번 같은 설명을 반복하게 됩니다. 어제 세션에서 인증을 왜 그렇게 구현했는지, 이 프로젝트가 어떤 스택을 쓰는지, 지난주에 어떤 라이브러리를 왜 골랐는지를 새 세션마다 다시 말해줘야 합니다. Agent가 게을러서가 아니라, 세션이 끝나는 순간 대화 컨텍스트가 통째로 사라지기 때문입니다.

agentmemory는 이 문제를 정면으로 겨냥한 오픈소스 프로젝트입니다. 저장소의 한 줄 소개는 이렇습니다.

Your coding agent remembers everything. No more re-explaining.

(당신의 coding agent가 모든 것을 기억합니다. 더 이상 다시 설명하지 않아도 됩니다.)

Claude Code, Cursor, Codex CLI, GitHub Copilot CLI, Gemini CLI 등 여러 agent 뒤에 공통으로 붙는 persistent memory 서버이고, iii engine 위에서 동작합니다. Agent가 무엇을 했는지 hook으로 조용히 기록해두었다가, 다음 세션이 시작될 때 필요한 부분만 골라 다시 컨텍스트에 넣어줍니다.

이 글에서는 agentmemory가 어떤 문제를 푸는지 먼저 보고, 이어서 무엇을 어떻게 기억하는지, 기억을 어떻게 찾아오는지, 그리고 이것을 붙이면 실제로 무엇이 달라지는지를 차례로 살펴보겠습니다. 이 글의 내용은 모두 agentmemory의 공식 저장소 문서를 근거로 하며, 수치와 동작은 글을 쓰는 시점의 README 기준입니다.

agentmemory란 무엇인가

세션이 끝나면 사라지는 컨텍스트

문제 상황은 단순합니다. 모든 coding agent는 세션이 끝나면 전부 잊고, 새 세션은 사용자가 스택을 다시 설명하는 것으로 시작합니다. agentmemory는 이 단계를 없애는 것을 목표로 백그라운드에서 동작합니다.

저장소는 그 효과를 이런 시나리오로 설명합니다.

Session 1: "Add auth to the API"
  Agent writes code, runs tests, fixes bugs
  agentmemory silently captures every tool use
  Session ends -> observations compressed into structured memory

Session 2: "Now add rate limiting"
  Agent already knows:
    - Auth uses JWT middleware in src/middleware/auth.ts
    - Tests in test/auth.test.ts cover token validation
    - You chose jose over jsonwebtoken for Edge compatibility
  Zero re-explaining. Starts working immediately.

첫 번째 세션에서 agent가 코드를 쓰고 테스트를 돌리는 동안 agentmemory는 모든 tool 사용을 조용히 캡처합니다. 세션이 끝나면 그 observation을 구조화된 memory로 압축합니다. 그래서 두 번째 세션은 "인증이 어디에 어떻게 구현되어 있는지"를 이미 아는 상태에서 시작합니다.

여기서 눈여겨볼 것은 마지막 줄입니다. jsonwebtoken 대신 jose를 골랐다는 사실은 코드만 읽어서는 알기 어렵습니다. 왜 그렇게 했는지는 대화 속에만 있었고, 세션과 함께 사라지던 정보입니다. agentmemory가 붙잡으려는 것이 바로 이런 종류의 맥락입니다.

Agent에 내장된 memory와의 차이

"이미 Claude Code에는 MEMORY.md가 있고 Cursor에는 notepad가 있는데 무엇이 다른가"라는 질문이 자연스럽게 나옵니다. 저장소는 이 둘의 관계를 sticky note와 그 뒤에 있는 검색 가능한 database로 설명합니다. 내장 memory는 포스트잇처럼 몇 줄 적어두는 용도이고, agentmemory는 그 포스트잇을 뒷받침하는 저장소라는 것입니다.

README가 정리한 비교는 다음과 같습니다.

핵심 차이는 검색 행에 있습니다. 내장 memory 파일은 관련이 있든 없든 전부 컨텍스트에 올라갑니다. 기록이 쌓일수록 매 세션 비용이 선형으로 늘어납니다. 반면 agentmemory는 질의에 맞는 상위 K개만 골라 넣기 때문에, 저장된 양이 늘어도 주입되는 양은 예산 안에서 유지됩니다.

무엇을 어떻게 기억하는가

Hook이 자동으로 잡아내는 것들

agentmemory의 첫 번째 축은 자동 캡처입니다. 사용자가 "이거 기억해"라고 말해야만 저장되는 방식이 아니라, agent의 lifecycle hook에 붙어서 별도 조작 없이 기록합니다. Claude Code의 경우 native plugin이 12개의 hook을 등록합니다.

각 hook이 무엇을 잡는지는 다음과 같습니다.

PostToolUseFailure가 별도로 있다는 점이 흥미롭습니다. 성공한 작업뿐 아니라 실패한 시도와 그 에러 컨텍스트도 기록한다는 뜻입니다. 같은 함정을 다음 세션에서 다시 밟지 않으려면 오히려 이쪽이 더 중요한 기록일 수 있습니다.

PreCompact도 눈여겨볼 만합니다. 대화가 길어져 컨텍스트가 압축될 때 memory를 다시 주입해서, compaction 과정에서 중요한 정보가 통째로 날아가는 것을 막습니다.

Hook 개수는 agent마다 다릅니다. Codex CLI plugin은 6개, Cursor plugin은 7개, OpenCode plugin은 세션 lifecycle과 메시지·tool·에러를 포괄하는 22개를 등록합니다. Hook을 지원하지 않는 agent라면 MCP나 REST API만으로도 붙일 수 있습니다.

Memory Pipeline: 캡처에서 주입까지

잡아낸 기록이 그대로 쌓이지는 않습니다. 저장까지 몇 단계를 거치고, 세션 경계에서 한 번 더 가공됩니다. README가 정리한 전체 흐름은 다음과 같습니다.

PostToolUse hook fires
  -> SHA-256 dedup (5min window)
  -> Privacy filter (strip secrets, API keys)
  -> Store raw observation
  -> Synthetic compression by default
     (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
  -> Vector embedding when an embedding provider is active
  -> Index in BM25, plus vectors when enabled

Stop / SessionEnd hook fires
  -> Summarize session
  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)

SessionStart hook fires
  -> Load project profile (top concepts, files, patterns)
  -> Hybrid search (BM25 + vector + graph)
  -> Token budget (default: 2000 tokens)
  -> Inject into conversation

세 덩어리로 읽으면 이해하기 쉽습니다.

쓰기 경로는 tool이 실행될 때마다 돕니다. SHA-256 해시로 5분 창 안의 중복을 걸러내고, privacy filter로 secret과 API key를 제거한 뒤 raw observation으로 저장합니다. 압축은 기본값이 synthetic 방식이고, LLM이 직접 쓰는 압축은 provider가 설정되어 있고 AGENTMEMORY_AUTO_COMPRESS=true일 때만 켜집니다. 그다음 embedding provider가 활성화되어 있으면 vector를 만들고, BM25 인덱스에 색인합니다.

세션 종료 경로에서는 세션을 요약하고, 설정에 따라 knowledge graph를 추출하거나 slot reflection을 수행합니다.

읽기 경로는 다음 세션이 시작될 때 돕니다. 프로젝트 profile을 불러오고 hybrid search로 관련 기록을 찾은 뒤, token 예산 안에서만 잘라 대화에 주입합니다. 기본 예산은 2,000 tokens입니다. 이 예산이 있기 때문에 memory가 아무리 쌓여도 세션 시작 비용이 폭발하지 않습니다.

Privacy filter가 저장 이전 단계에 있다는 점도 짚고 넘어갈 만합니다. Secret이 일단 들어갔다가 나중에 지워지는 것이 아니라, 애초에 저장되지 않습니다. <private> 태그로 감싼 내용도 같은 지점에서 걸러집니다.

4-Tier Memory Consolidation

Working, Episodic, Semantic, Procedural

두 번째 축은 memory의 계층 구조입니다. agentmemory는 모든 기록을 같은 자리에 평평하게 두지 않고, 사람의 뇌가 기억을 처리하는 방식, 특히 수면 중 consolidation을 본떠 네 단계로 나눕니다.

아래로 갈수록 개별 사건에서 멀어지고 일반화된 지식에 가까워집니다. Working tier의 "2026년 9월 3일 14시에 src/auth.ts를 읽었다"는 그 자체로는 다음 세션에 큰 도움이 되지 않습니다. 이것이 Episodic tier에서 "인증 모듈을 리팩터링한 세션"으로 묶이고, Semantic tier에서 "이 프로젝트의 인증은 JWT middleware를 쓴다"는 사실로 정리되며, Procedural tier에서 "이 프로젝트에서 인증을 고칠 때는 어떤 순서로 접근한다"는 패턴이 됩니다.

Consolidation은 자동으로 돌지만, MCP tool memory_consolidate로 직접 실행할 수도 있고 설정에서 끌 수도 있습니다.

잊는 것도 기능이다

계층만큼 중요한 것이 감쇠입니다. agentmemory의 memory는 시간이 지나면서 Ebbinghaus 망각 곡선을 따라 약해집니다. 자주 접근되는 memory는 반대로 강화됩니다. 오래되고 쓰이지 않는 memory는 자동으로 밀려납니다.

정리하면 이런 장치들이 함께 동작합니다.

• TTL 만료: 유효 기간이 지난 항목을 정리합니다.
• 중요도 기반 eviction: 중요도가 낮은 항목부터 밀어냅니다.
• 모순 감지와 해소: 서로 어긋나는 memory가 생기면 감지해서 정리합니다.
• 버전 관리와 supersession: 갱신된 memory의 이전 버전은 검색 인덱스에서 빠지지만, 버전 체인은 KV에 그대로 남아 이력을 추적할 수 있습니다.

마지막 항목이 특히 실용적입니다. "이 프로젝트는 npm을 쓴다"는 memory가 나중에 "pnpm으로 옮겼다"로 갱신되면, 검색에는 새 버전만 걸리고 옛 버전은 이력으로만 남습니다. 낡은 사실이 검색 결과에 섞여 agent를 잘못 이끄는 상황을 구조적으로 막는 설계입니다.

Memory를 무한히 쌓기만 하는 저장소였다면 시간이 지날수록 오히려 방해가 되었을 것입니다. 잊는 장치가 함께 있어야 memory가 쓸모를 유지합니다.

세 갈래 신호를 합치는 Hybrid Search

BM25, Vector, Graph

세 번째 축은 검색입니다. 아무리 잘 저장해도 필요한 순간에 꺼내오지 못하면 의미가 없습니다. agentmemory는 성격이 다른 세 가지 신호를 동시에 사용합니다.

세 신호는 서로 다른 종류의 질문에 강합니다. BM25는 AGENTMEMORY_AUTO_COMPRESS 같은 정확한 식별자를 찾을 때 확실합니다. Vector는 "인증 관련해서 뭘 했더라"처럼 단어가 정확히 일치하지 않는 의미 기반 질의에 강합니다. Graph는 "이 파일과 엮인 결정들"처럼 관계를 따라가야 하는 질의를 담당합니다. 하나만 써서는 세 종류를 모두 커버할 수 없기 때문에 셋을 함께 씁니다.

한국어로 memory를 쌓는다면 짚고 넘어가야 할 부분이 있습니다. BM25 tokenizer는 그리스 문자, 키릴 문자, 히브리 문자, 아랍 문자, 악센트가 붙은 라틴 문자를 기본으로 처리하지만, 한국어를 포함한 CJK는 별도의 segmenter가 필요합니다. 저장소는 선택적 패키지 설치를 안내합니다.

npm install @node-rs/jieba tiny-segmenter

설치하지 않으면 CJK 구간을 단어 단위로 쪼개지 못하고 통째로 하나의 토큰처럼 다루며, stderr에 힌트를 한 번 출력합니다. 오류로 멈추지는 않지만 한국어 키워드 검색의 정확도가 떨어지므로, 한국어 위주로 쓸 계획이라면 처음부터 설치해두는 편이 좋습니다.

RRF fusion과 embedding provider 선택

세 stream의 결과는 Reciprocal Rank Fusion으로 합쳐집니다. 상수 k는 60이고, 한 세션에서 최대 3개까지만 결과에 넣는 session diversification이 함께 적용됩니다.

RRF는 점수 자체가 아니라 순위를 기준으로 결합하는 방식입니다. BM25 점수와 코사인 유사도는 애초에 척도가 달라서 직접 더할 수 없는데, 각 stream에서의 등수만 쓰면 정규화 문제를 피할 수 있습니다. Session diversification은 한 세션의 기록이 상위 결과를 독식하는 것을 막는 장치입니다.

Embedding provider를 무엇으로 할지는 설치할 때 정하게 됩니다. 키 없이 설치하면 vector embedding이 꺼지고 검색은 BM25로만 동작합니다. 이때도 graph 데이터가 이미 있다면 smart-search는 구조적 매칭을 함께 사용할 수 있습니다.

무료로 semantic 검색까지 쓰고 싶다면 on-device embedding을 켜면 됩니다.

# ~/.agentmemory/.env
EMBEDDING_PROVIDER=local

이렇게 두고 재시작하면 첫 embedding 요청에서 Xenova/all-MiniLM-L6-v2 모델을 내려받고, 이후 추론은 로컬에서 돕니다. README는 이 방식이 BM25만 쓸 때보다 recall을 8퍼센트포인트 끌어올린다고 밝히고 있습니다. 비용은 0이고 API key도 필요 없으므로, 개인 개발 환경에서는 이 조합이 기본값으로 삼기 좋습니다.

품질이나 다국어가 더 중요하다면 원격 provider도 선택할 수 있습니다. OpenAI의 text-embedding-3-small은 100만 토큰당 $0.02이고, 코드에 특화된 Voyage AI의 voyage-code-3, 무료 티어가 있는 Gemini의 gemini-embedding-001 등이 지원됩니다. 원격 provider는 키가 있으면 자동으로 감지되며, EMBEDDING_PROVIDER를 명시하면 그 설정이 우선합니다.

agentmemory로 할 수 있게 되는 것들

하나의 memory를 여러 agent가 공유한다

지금까지가 구조라면, 여기서부터는 그 구조가 실제로 무엇을 가능하게 하는지입니다.

가장 큰 변화는 memory가 특정 agent에 묶이지 않는다는 점입니다. agentmemory는 hook, MCP, REST API 중 하나만 지원하면 어떤 agent와도 연동되고, 연결된 모든 agent가 같은 memory 서버를 공유합니다. agentmemory connect <agent> 명령으로 붙일 수 있는 adapter가 20개 준비되어 있습니다.

agentmemory connect cursor
agentmemory connect codex
agentmemory connect warp

MCP를 쓰는 host라면 설정 블록도 동일합니다.

"agentmemory": {
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  "env": {
    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
  }
}

Host마다 설정 파일 위치와 key 이름은 다릅니다. Zed는 mcpServers가 아니라 context_servers를 쓰고, OpenCode는 최상위 mcp key에 command를 배열로 넣으며, Codex CLI는 TOML 형식입니다. 이런 차이를 connect 명령이 대신 처리해줍니다.

실무에서 이 구조가 갖는 의미는 분명합니다. 터미널에서는 Claude Code를 쓰고 IDE에서는 Cursor를 쓰더라도, 한쪽에서 쌓은 맥락을 다른 쪽이 그대로 이어받습니다. Agent를 갈아타도 프로젝트 지식이 리셋되지 않습니다.

여러 역할의 agent가 한 서버를 공유하는 경우를 위한 장치도 있습니다. AGENT_ID를 설정하면 모든 쓰기에 그 역할이 태그로 붙고, AGENTMEMORY_AGENT_SCOPE가 recall 시 그 태그로 필터링할지를 결정합니다.

AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated  # 생략 시 기본값은 shared

기본값인 shared 모드에서는 태그만 남기고 필터링은 하지 않습니다. Architect가 developer의 기록을 볼 수 있되, 모든 행이 누가 남긴 것인지를 기록합니다. isolated 모드에서는 각 역할이 자기 기록만 보게 됩니다. 감사 추적이 필요하면 앞쪽을, 엄격한 분리가 필요하면 뒤쪽을 고르면 됩니다.

Token 비용과 recall 정확도

두 번째 변화는 비용입니다. 저장소가 제시하는 연간 token 비교는 다음과 같습니다.

첫 행이 눈에 띕니다. 모든 맥락을 매번 붙여넣는 방식은 비싼 것이 아니라 아예 불가능합니다. 컨텍스트 창을 넘기 때문입니다. 결국 선택지는 "요약해서 넣기"와 "검색해서 필요한 것만 넣기"이고, agentmemory는 후자입니다.

정확도는 어떨까요? ICLR 2025의 LongMemEval-S 벤치마크 500문항에서의 결과는 다음과 같습니다.

두 행의 차이가 곧 hybrid search의 기여분입니다. R@5 기준으로 9퍼센트포인트, MRR 기준으로는 16.7퍼센트포인트 차이가 납니다. MRR 격차가 더 크다는 것은, hybrid가 정답을 단순히 찾아내는 데 그치지 않고 더 위쪽 순위로 올려놓는다는 뜻입니다. Token 예산 안에서 상위 몇 개만 주입되는 구조에서는 이 차이가 그대로 체감으로 이어집니다.

다만 수치를 읽을 때 저장소가 스스로 붙인 단서도 함께 볼 필요가 있습니다. 저장소는 자체 코퍼스인 coding-agent-life-v1에 대해 규모가 작고 gold가 희소하다는 점, 그리고 그 벤치마크에서의 이득이 집계 precision이 아니라 recall과 시간 축 질의에서 나온다는 점을 명시하고 있습니다. 위의 LongMemEval-S 쪽이 더 변별력 있는 지표라는 설명도 저장소 자신의 표현입니다. 벤치마크 하네스는 eval/에 공개되어 있어 직접 재현해볼 수 있습니다.

MCP tool과 viewer로 memory를 직접 다루기

세 번째 변화는 memory가 조작 가능한 대상이 된다는 점입니다. 자동으로 쌓이기만 하는 것이 아니라, agent가 MCP tool로 직접 저장하고 검색하고 정리할 수 있습니다.

Tool 표면은 세 단계로 나뉩니다. AGENTMEMORY_TOOLS=core는 memory_save, memory_recall, memory_consolidate, memory_smart_search, memory_sessions, memory_diagnose, memory_lesson_save, memory_reflect 8개만 노출합니다. 기본 tool 집합은 14개이고, 기본값인 AGENTMEMORY_TOOLS=all은 54개를 전부 엽니다.

Tool 목록을 보면 agentmemory가 단순 저장소를 넘어서려 한다는 것이 드러납니다. memory_recall이나 memory_timeline처럼 memory를 다루는 tool 옆에, memory_action_create나 memory_next처럼 작업 항목과 의존성을 관리하는 tool, memory_lease나 memory_signal_send처럼 여러 agent 사이의 조율을 담당하는 tool이 함께 있습니다. memory_verify로 특정 memory가 어떤 observation에서 나왔는지 출처를 역추적할 수도 있습니다.

Tool 개수가 부담스럽다면 core로 줄이는 선택지가 있다는 점도 실용적입니다. Tool 정의 자체가 컨텍스트를 차지하므로, 필요한 만큼만 여는 편이 나을 때가 있습니다.

Observability도 갖춰져 있습니다. 실시간 viewer가 3113 포트에서 자동으로 뜹니다.

open http://localhost:3113

Observation 스트림, 세션 탐색기, memory와 lesson의 원본 레코드, knowledge graph, 세션 replay, health 대시보드를 볼 수 있습니다. Viewer 서버는 기본적으로 127.0.0.1에만 바인딩됩니다. Agent가 무엇을 기억하고 있는지 눈으로 확인할 수 있다는 것은, memory가 잘못 쌓였을 때 원인을 찾을 수 있다는 뜻이기도 합니다.

마지막으로 확장성입니다. agentmemory는 그 자체가 이미 실행 중인 iii 인스턴스이고, 별도의 plugin 시스템 없이 iii의 worker를 추가하는 것으로 기능을 늘립니다.

iii worker add iii-cron     # 야간 consolidation, 주기적 snapshot, 정해진 시각의 decay
iii worker add iii-queue    # embedding·압축 작업 실패 시 재시도, 재시작해도 유실 없음
iii worker add iii-pubsub   # 여러 인스턴스로 memory 쓰기를 전파

Postgres도 Redis도 Express도 pm2도 따로 설치하지 않는 이유가 여기에 있습니다. 그 역할을 iii의 KV state, stream, trigger, worker 관리가 대신합니다. 로컬 런타임은 기본적으로 네 개의 포트를 사용합니다. REST와 MCP HTTP에 3111, iii stream에 3112, viewer에 3113, iii worker WebSocket에 49134입니다.

마무리

agentmemory는 "agent가 세션마다 잊는다"는 문제를 세 가지 축으로 풀어냅니다.

첫째, 자동 캡처입니다. Lifecycle hook에 붙어 tool 사용, 프롬프트, 실패한 시도까지 사용자 개입 없이 기록합니다. 저장 전에 중복을 제거하고 secret을 걸러냅니다.

둘째, 계층화와 감쇠입니다. Working에서 Episodic, Semantic, Procedural로 이어지는 4단계 consolidation으로 개별 사건을 일반화된 지식으로 끌어올리고, 망각 곡선과 TTL, 중요도 eviction, supersession으로 낡은 memory가 검색을 오염시키지 않게 합니다.

셋째, hybrid search입니다. BM25와 vector와 graph를 RRF로 결합해 필요한 것만 찾아내고, token 예산 안에서 잘라 주입합니다. LongMemEval-S 기준 R@5 95.2%라는 수치와 연간 약 170K tokens라는 비용은 같은 설계에서 나온 두 얼굴입니다.

그 결과 얻는 것은 결국 하나입니다. Agent를 갈아타도, 세션이 끊겨도, 프로젝트에 대해 쌓아둔 맥락이 리셋되지 않는 것입니다.

시작하는 데 큰 준비가 필요하지도 않습니다. Node.js 20 이상이면 아래 한 줄로 대화형 설치가 시작되고, 연동할 agent와 provider를 고르면 설정 파일 생성부터 서버 기동까지 알아서 진행됩니다.

npx -y @agentmemory/agentmemory@latest

키 없이도 BM25 검색은 그대로 동작하므로, 일단 붙여두고 며칠 써보면서 viewer로 무엇이 쌓이는지 확인해보는 것이 가장 빠른 판단 방법일 것입니다. 한국어로 기록을 남길 계획이라면 CJK segmenter를 함께 설치하는 것을 잊지 마시기 바랍니다.

References

• agentmemory - GitHub