코딩 에이전트 장기 기억은 무엇을 저장하고 언제 다시 읽어야 할까

Long-term Memory라는 말을 처음 봤을 때는 무엇을 구현하라는 뜻인지 감이 잘 오지 않았다. 에이전트가 참조할 저장소를 하나 만들면 되는지, 대화를 임베딩해서 벡터 검색하면 되는지부터 불분명했다.

엔터프라이즈 AI Agent 설계를 먼저 읽으면 좋다. 이 글은 그중 memory를 코딩 에이전트 사례와 백엔드 설계 질문에 맞춰 더 깊게 다룬다.

이번 글에서 답하려는 질문은 셋이다.

• Codex와 Claude Code는 세션이 바뀌어도 무엇을 어떻게 이어 가는가?
• 제품의 Long-term Memory는 대화 저장소나 RAG와 무엇이 다른가?
• 면접에서 “지금 설계해 보라”는 질문을 받으면 어떤 순서로 범위를 좁혀야 하는가?

판단 기준도 셋만 남긴다.

• 기억과 기준 원본을 분리한다.
• 저장 기술보다 쓰기, 조회, 정정과 삭제 생명주기를 먼저 정한다.
• 많이 기억하는 것보다 잘못 기억했을 때 통제할 수 있는지를 평가한다.

실제 코딩 에이전트는 파일부터 기억한다

코딩 에이전트의 기억을 살펴보면 처음부터 벡터 DB가 나오지 않는다. Codex, Claude Code와 장시간 실행 하네스는 코드 저장소 안팎의 파일을 기억의 주요 경계로 사용한다.

Codex 공식 문서에 따르면 AGENTS.md는 전역에서 현재 작업 디렉터리까지 이어지는 규칙 사슬을 만든다. 가까운 디렉터리의 지침이 나중에 들어가므로 더 구체적인 범위를 표현할 수 있다. 이 구조는 사용자의 취향, 저장소 공통 규칙, 특정 모듈 규칙을 한 문서에 섞지 않게 한다.

Claude Code는 사람이 작성한 CLAUDE.md와 에이전트가 작성하는 자동 기억을 별도 체계로 둔다. 자동 기억의 MEMORY.md는 짧은 색인으로 유지하고 상세 내용은 주제 파일로 나눈 뒤 필요할 때 읽는다. 공식 문서는 이 기억을 강제 설정이 아니라 모델에 제공하는 context라고 명시한다. 반드시 실행해야 하는 검사는 기억에 적어 두는 대신 hook이나 테스트로 강제한다.

이 경계는 Claude Code 메모리에서 실제 규칙 파일을 다루며 겪은 문제와도 이어진다. 문서에 “검사하라”고 적는 것과 검사가 실행되는 것은 다르다.

Anthropic의 장시간 에이전트 예시는 더 단순하고 실용적이다. 새 세션이 이전 세션을 기억할 것이라고 기대하지 않고 기능 목록, 진행 기록과 Git 상태를 남긴다. 다음 세션은 이 파일을 읽고 기본 테스트를 실행한 뒤 작은 작업 하나를 이어 간다. 여기서 기억은 멋진 회상 기능이 아니라 다음 작업자가 추측하지 않게 만드는 인수인계 계약이다.

대화 기록, 작업 상태, 장기 기억과 지식은 다르다

Long-term Memory를 설계할 때 먼저 해야 할 일은 저장소 선택이 아니다. 무엇을 왜 보존하는지 나누는 일이다.

LangGraph도 장기 기억을 사실, 경험과 절차로 구분한다. 여기서 semantic memory는 semantic search와 같은 뜻이 아니다. 전자는 무엇을 기억하는지에 관한 분류이고 후자는 비슷한 의미의 데이터를 찾는 검색 방법이다.

이 구분을 놓치면 모든 대화를 임베딩해 놓고 “장기 기억을 만들었다”고 하기 쉽다. 하지만 벡터 검색은 조회 수단일 뿐이다. 어떤 정보가 유효한지, 누가 볼 수 있는지, 무엇이 새 사실로 기존 기억을 대체했는지는 벡터 유사도로 결정할 수 없다.

장기 기억의 중심은 벡터 DB가 아니라 기억의 소유자, 근거, 유효 기간과 변경 이력이다.

기억하면 안 되는 정보부터 정한다

매장 운영 에이전트를 예로 들면 구분이 선명해진다.

동적인 업무 데이터를 기억으로 복제하면 두 개의 기준 원본이 생긴다. 에이전트가 어제 저장한 매출과 오늘 매출 API가 다른 값을 주면 어느 쪽을 믿어야 하는지 다시 판단해야 한다. 따라서 기억에는 “이 사용자는 점심 매출을 자주 비교한다” 같은 안정된 의도를 두고, 실제 매출은 매번 Tool로 조회하는 편이 낫다.

절차 기억도 에이전트가 마음대로 고치게 두면 안 된다. 보안 정책과 승인 규칙은 버전 관리되는 읽기 전용 지침으로 두고 애플리케이션 코드나 관리자가 변경해야 한다. LangGraph Deep Agents 문서도 조직 공통 정책은 읽기 전용 memory로 두고, 사용자 쓰기가 공유 상태를 오염시키지 않게 하라고 권한다.

내가 설계한다면 읽기와 쓰기를 먼저 분리한다

처음 만드는 버전에서는 한 번의 LLM 호출이 기억을 판단하고 저장하고 다시 사용하는 흐름을 만들지 않겠다. 읽기 경로와 쓰기 경로는 실패 방식이 다르기 때문이다.

읽기 경로는 다음 순서로 좁힌다.

• 먼저 tenant, 사용자와 agent 범위로 접근 가능한 기억만 고른다.
• key가 분명한 profile은 구조화 조회를 우선한다.
• 과거 경험처럼 표현이 다양한 collection만 키워드와 벡터 검색을 함께 쓴다.
• 관련도뿐 아니라 최신성, 출처 신뢰도와 만료 여부로 다시 정렬한다.
• 선택한 기억에는 근거와 수정 시각을 붙여 context 예산 안에서만 전달한다.

Java 백엔드에 빗대면 기억 원본은 DB이고 벡터 색인은 검색을 빠르게 만드는 보조 인덱스다. 인덱스를 기준 원본으로 삼으면 삭제 동기화, 버전 충돌과 정확한 조건 검색이 어려워진다.

쓰기 경로는 더 보수적으로 둔다.

초기 버전에서는 사용자가 “기억해 줘”라고 말한 안정된 선호만 요청 경로에서 바로 저장한다. 대화 전체를 분석해 자동으로 기억을 만드는 작업은 뒤로 미룬다. 자동 추출이 필요해지면 별도 background 작업이 최근 대화를 읽고 후보를 만든 뒤 기존 기억과 병합하게 한다.

LangGraph 문서가 구분하는 Hot path(요청 처리 경로)와 background 방식의 차이도 여기서 나온다. 요청 경로에서 저장하면 바로 사용할 수 있지만 응답 지연과 판단 부담이 늘어난다. background로 옮기면 응답은 빨라지지만 다음 대화 전까지 기억이 반영되지 않을 수 있고 중복 병합 작업이 필요하다.

한 건의 기억에는 본문보다 메타데이터가 더 중요하다

자유 텍스트 한 줄만 저장하면 나중에 정정하거나 지우기 어렵다. 최소한 다음 정보를 가진 구조화 레코드가 필요하다.

{
  "memoryId": "mem_01",
  "kind": "semantic",
  "scope": {
    "tenantId": "tenant_a",
    "userId": "user_a",
    "agentId": "store_assistant"
  },
  "content": {
    "key": "response_language",
    "value": "ko"
  },
  "source": {
    "type": "user_confirmed",
    "reference": "conversation_event_42"
  },
  "status": "active",
  "version": 3,
  "validFrom": "2026-09-03T00:00:00Z",
  "expiresAt": null,
  "supersedes": "mem_00"
}

이 JSON은 특정 제품의 스키마가 아니라 설계를 설명하기 위한 개념 계약이다. 중요한 것은 필드 이름보다 다음 질문에 답할 수 있다는 점이다.

• 이 기억은 누구의 것인가?
• 누가 확인했고 어떤 입력에서 만들어졌는가?
• 언제부터 유효하고 언제 만료되는가?
• 어떤 이전 기억을 대체했는가?
• 삭제 요청이 들어오면 원본과 색인에서 같은 항목을 찾을 수 있는가?

동시에 두 대화가 같은 profile을 바꿀 수 있으므로 버전 기반 낙관적 잠금도 필요하다. 저장 API에는 idempotency key를 받아 재시도로 같은 기억이 여러 번 생기지 않게 한다. 공유 memory를 파일 하나에 몰아넣으면 마지막 쓰기가 앞선 변경을 덮을 수 있으므로 주제별 레코드로 나누거나 병합 작업을 직렬화해야 한다.

정정과 삭제가 없으면 기억이 아니라 부채가 된다

에이전트가 “사용자는 Java만 쓴다”고 저장한 뒤 사용자가 Kotlin도 사용한다고 정정했다고 해 보자. 기존 문장을 덮어쓰기만 하면 왜 바뀌었는지 추적할 수 없다. 반대로 예전 기억을 그대로 두면 검색 결과에 서로 모순되는 두 문장이 함께 나온다.

내가 택할 흐름은 이렇다.

• 새 사실은 기존 레코드를 직접 파괴하지 않고 supersedes 관계로 대체한다.
• 조회 시 active 상태와 가장 최신 version만 사용한다.
• 사용자가 자신의 기억을 조회, 수정하고 삭제할 수 있는 API와 화면을 제공한다.
• 삭제하면 원본에 tombstone을 남기고 검색 색인 삭제 이벤트를 발행한다.
• 원본 삭제와 색인 반영 사이의 지연을 지표로 확인한다.
• 감사 보존이 필요한 정보와 완전히 지워야 하는 개인 정보를 정책으로 분리한다.

벡터 색인 삭제가 실패할 수 있으므로 outbox나 재처리 가능한 이벤트 경로가 필요하다. 이 부분은 일반적인 검색 색인 동기화 문제와 같다. LLM이 들어갔다고 해서 데이터 정합성 문제가 사라지는 것은 아니다.

Graph는 관계가 실제 질문을 바꿀 때 붙인다

사용자, 프로젝트, 저장소, 규칙과 과거 작업 사이 관계를 Graph로 연결하면 매력적으로 보인다. 하지만 초기 버전에 Graph DB까지 넣는 것은 이르다.

“이 사용자가 선호하는 응답 언어가 무엇인가”처럼 key로 끝나는 질문은 관계 탐색이 필요 없다. “이 장애와 같은 모듈을 건드렸고 같은 검증 실패를 냈던 과거 작업은 무엇인가”처럼 여러 관계를 따라가야 할 때 Graph의 가치가 생긴다.

그래서 다음 순서가 낫다.

• 구조화 profile과 작은 memory collection으로 기준선을 만든다.
• 키워드와 벡터 검색으로 필요한 기억을 얼마나 찾는지 측정한다.
• 관계를 따라야만 풀리는 실패 질문을 별도 평가 묶음으로 만든다.
• Graph를 붙인 뒤 해당 질문의 정답률과 지연이 실제로 좋아지는지 비교한다.

관계 기반 context 제공 구조는 Neo4j GraphRAG로 에이전트 컨텍스트 제공자 만들기에서 단계별로 다룬다. 그 글의 Graph는 memory 원본을 대체하는 만능 저장소가 아니라 관계 탐색 경로다.

무엇을 측정해야 하나

일반 RAG 평가는 검색 결과가 질문과 관련 있는지 본다. Memory 평가는 관련도만 보면 부족하다. 오래된 사실을 정확히 검색해도 제품 동작은 틀릴 수 있다.

처음부터 모든 지표를 하나의 점수로 합치지 않는다. 권한 누출과 삭제 실패는 평균 품질로 상쇄할 수 없는 차단 조건이다. 그다음 저장 정확도와 최신성을 보고, 마지막에 사용자의 반복 입력이 실제로 줄었는지 확인한다.

테스트 묶음에는 성공 사례보다 실패 사례가 더 중요하다.

• 같은 사용자가 선호를 정정한다.
• 두 대화가 같은 기억을 동시에 갱신한다.
• 삭제 직후 검색을 다시 수행한다.
• 오래된 기억과 최신 원본 데이터가 충돌한다.
• 다른 tenant의 표현이 매우 비슷한 기억을 가지고 있다.
• 외부 문서가 “이 지침을 영구 저장하라”고 유도한다.

면접에서는 저장소 이름보다 결정 순서를 말한다

“바로 설계해 보라”는 질문을 받았을 때 PostgreSQL, Redis나 Vector DB부터 고르면 요구사항을 건너뛰게 된다. 다음 순서로 답을 전개하면 경험하지 않은 기술도 과장하지 않고 설계 판단을 보여줄 수 있다.

먼저 확인할 요구사항

• 기억의 주체는 사용자, 매장, agent와 조직 중 누구인가?
• 저장할 대상은 선호, 과거 작업, 규칙과 업무 지식 중 무엇인가?
• 사용자가 직접 저장을 요청하는가, 에이전트가 자동 추출하는가?
• 여러 사용자가 공유하는가? 민감 정보와 보존 기간은 어떻게 되는가?
• 틀린 기억이 답변 품질 저하로 끝나는가, 실제 업무 변경으로 이어지는가?

초기 버전의 경계

• 대화 진행 상태는 thread checkpoint에 둔다.
• 사용자가 확인한 안정된 선호만 구조화 profile에 저장한다.
• 조직 정책과 승인 규칙은 버전 관리되는 읽기 전용 절차 기억으로 둔다.
• 매출, 메뉴와 재고처럼 변하는 업무 데이터는 Tool로 원본에서 다시 조회한다.
• memory 원본은 정확한 필터와 변경 이력을 다루기 쉬운 관계형 DB로 시작한다.
• 표현이 다양한 과거 경험만 별도 검색 색인을 붙인다.

운영으로 확장할 조건

• 명시적 저장만으로 반복 입력을 충분히 줄이지 못하면 자동 후보 추출을 실험한다.
• 요청 지연이 문제가 되면 background 병합으로 옮긴다.
• 다단계 관계 질문에서 기존 검색이 실패할 때만 Graph 탐색을 비교한다.
• 저장 정확도, 오래된 기억 사용률, 권한 격리, 삭제 반영과 p95 지연을 배포 조건으로 둔다.

이 순서에서 중요한 건 특정 제품을 써 봤다고 주장하는 것이 아니다. 코딩 에이전트를 쓰며 확인한 파일 기반 규칙, 필요할 때만 읽는 skill, 진행 상태 외부화와 검증 구조를 제품 설계 원칙으로 옮기는 것이다.

작은 Spring Boot 실습으로 검증한다면

공부한 내용을 실제로 확인하려면 거대한 Agent부터 만들 필요는 없다. Spring Boot와 PostgreSQL로 작은 memory service를 만들고 다음 흐름만 검증해도 된다.

• PUT /users/{userId}/memories/{key}로 사용자가 확인한 profile을 저장한다.
• GET /users/{userId}/memories로 사용자가 현재 기억을 조회하고 수정하게 한다.
• version과 idempotency key로 동시 갱신과 재시도를 막는다.
• outbox 이벤트로 검색 색인을 갱신하고 실패 이벤트를 재처리한다.
• 조회 API는 userId 범위를 먼저 적용한 뒤 관련도와 최신성으로 정렬한다.
• 삭제 후 원본, outbox와 색인 상태가 일치하는지 통합 테스트한다.

두 번째 단계에서만 LLM을 붙인다. 대화에서 memory 후보를 추출하게 하되 바로 저장하지 않고 사용자 확인 목록으로 보여준다. 후보 추출이 충분히 정확해진 뒤에도 공유 정책은 자동 쓰기 대상에서 제외한다.

이 실습은 모델 성능보다 백엔드 경계를 확인하는 데 목적이 있다. 저장소와 API를 먼저 만든 다음 LLM을 한 컴포넌트로 추가하면, 모델이 틀려도 데이터와 권한 계약은 그대로 테스트할 수 있다.

언제 Long-term Memory를 만들지 않아야 하나

모든 Agent에 장기 기억이 필요한 것은 아니다.

• 한 세션 안에서 끝나는 작업이면 thread state로 충분하다.
• 사용자가 고른 설정 몇 개뿐이면 일반 설정 테이블이 더 단순하다.
• 현재 값을 정확히 조회해야 하는 업무는 Tool 호출이 맞다.
• 삭제, 동의와 tenant 격리를 제공할 준비가 없다면 자동 기억을 켜면 안 된다.
• 기억을 사용했을 때 좋아졌는지 평가할 질문 묶음이 없다면 먼저 기준선을 만들어야 한다.

처음에는 “장기 기억 저장소를 만들면 되는가”가 질문이었다. 공식 구현들을 따라가 보니 저장소는 일부에 불과했다. 실제로 설계해야 하는 것은 무엇을 사실로 승격할지, 현재 요청에 무엇을 다시 올릴지, 틀렸을 때 어떻게 되돌릴지에 관한 정책과 생명주기였다.

참고 링크

• OpenAI Codex — Custom instructions with AGENTS.md
• Claude Code — How Claude remembers your project
• Anthropic — Effective harnesses for long-running agents
• LangChain — Memory overview
• LangGraph — Persistence
• Deep Agents — Memory