용어집
《에이전트 메모리와 상태》의 용어 85개. 레슨 본문에서 처음 등장하는 용어에 마우스를 올리면 정의를 볼 수 있습니다.
| 용어 | 정의 | 출처 |
|---|---|---|
| 스테이트리스 | 서버가 한 API 호출과 다음 호출 사이에 세션별 상태를 따로 보관하지 않는 성질이며, 그래서 모든 요청이 전체 대화 히스토리를 스스로 실어 날라야 한다. | Using the Messages API |
| 컨텍스트 윈도우 | 모델이 한 번의 요청에서 실제로 볼 수 있는 모든 것을 담는 그릇이다: 시스템 프롬프트, messages 배열의 모든 메시지, 도구 정의, 그리고 그 턴에 대한 모델 자신의 출력. | Context windows |
| 시스템 프롬프트 | 모델의 역할과 행동을 정하기 위해 요청과 함께 보내는 텍스트이며, 공식 문서는 이것을 컨텍스트 윈도우에 계산되는 구성 요소 중 하나로 열거한다. | Context windows |
| 도구 정의 | 사용 가능한 각 도구를 설명하기 위해 모델에 넘기는 name·description·input_schema이며, 문서는 이것이 같은 요청의 컨텍스트 윈도우에 계산된다고 밝힌다. | Context windows |
| 확장 사고 | 모델이 이번 턴의 답을 생성하는 동안 만들어 내는 추론 콘텐츠이며, 문서는 이것이 이번 턴의 컨텍스트 윈도우 사용량에 계산된다고 밝힌다. | Context windows |
| usage | 그 요청이 실제로 소모한 입력·출력 토큰 수를 알려 주는 API 응답의 필드. | Context windows |
| 컨텍스트 로트 | 윈도우 안의 토큰 수가 늘어날수록 정확도와 회상률이 떨어지는, 공식 문서가 이름 붙인 현상. | Context windows |
| 누적 | 대화 히스토리가 턴을 거듭할수록 컨텍스트 윈도우에 쌓여, 무언가 능동적으로 비우지 않는 한 커지기만 하고 줄어들지 않는 기본 동작. | Context windows |
| 재전송 | '메모리'라는 말 뒤에 있는 실제 메커니즘이다 — 모델이 스스로 무언가를 저장하거나 떠올리는 것이 아니라, 매 요청이 앞선 히스토리 메시지를 모델에 그대로 다시 보내는 것. | Using the Messages API |
| 여러 세션 | 하나의 대화보다 오래 살아남아 독립적인 세션들에 걸쳐 유지되어야 하는 정보의 범위이며, 현재 messages 배열에 밀어 넣는 것으로는 이룰 수 없다. | Context windows |
| Messages API | 이 코스가 딛고 선 API이며, 공식 문서는 이것이 스테이트리스이고 매 요청마다 전체 대화 히스토리를 항상 보내야 한다고 분명히 밝힌다. | Using the Messages API |
| 덧붙이기 | 대화 히스토리를 관리하는 가장 단순한 방법이다 — 매 턴이 끝나면 새 메시지를 기존 messages 배열 끝에 이어 붙이고, 다음 턴에 그 배열 전체를 다시 보낸다. | Context windows |
| 잘라내기 | 윈도우가 거의 찼을 때 가장 오래된 메시지 묶음을 통째로 끊어 내고 최근 N개만 남기는 방식이며, 구현은 간단하지만 버린 것은 되돌릴 수 없다. | Context windows |
| 컴팩션 | 컨텍스트 윈도우의 내용을 고충실도 요약으로 증류하여, 대화가 길어져도 에이전트가 성능 저하를 최소화하며 이어 갈 수 있게 하는 공식 메커니즘. | Context engineering: memory, compaction, and tool clearing |
| 고충실도 요약 | 컴팩션이 만들어 내는 것이다 — 원본 히스토리의 긴 흐름을 대체하고 윈도우 앞쪽에 놓이며, 무슨 일이 있었고 무엇이 결론이었는지는 지키되 한 마디 한 마디의 세부는 버린 증류본. | Context engineering: memory, compaction, and tool clearing |
| 발동 임계값 | 공식 메커니즘이 컴팩션이나 도구 결과 비우기를 자동으로 시작하는 윈도우 사용량 수준. | Context engineering: memory, compaction, and tool clearing |
| 도구 결과 비우기 | 도구 사용 자체에서 오는 부풀음을 겨냥한 공식 메커니즘이다 — 호출이 있었다는 기록은 남긴 채, 낡고 다시 가져올 수 있는 결과를 버린다. | Context engineering: memory, compaction, and tool clearing |
| 다시 가져올 수 있는 | 비우기가 무엇을 버려도 되는지를 결정하는 조건이다 — 도구가 반환했던 콘텐츠 가운데 이미 낡았고, 같은 인자로 같은 도구를 다시 불러 얻을 수 있는 것. | Context engineering: memory, compaction, and tool clearing |
| 150K 토큰 | 컴팩션의 기본 발동 임계값이며, 윈도우 사용량이 이 수준에 이르면 컴팩션이 자동으로 발동한다. | Context engineering: memory, compaction, and tool clearing |
| 100K 토큰 | 도구 결과 비우기의 기본 발동 임계값이며, 컴팩션의 150K보다 낮은데 이는 도구 출력이라는 단일한 부풀음 원인에 더 일찍 개입하는 그 역할에 들어맞는다. | Context engineering: memory, compaction, and tool clearing |
| 50K 토큰 | 컴팩션 발동 임계값에 대해 서버가 강제하는 하한이며, 설정하는 값은 최소한 이만큼은 되어야 하므로 임계값을 마음대로 낮출 수 없다. | Compaction |
| 최근 3개 도구 호출 | 도구 결과 비우기의 기본 보존 정책이며, 마지막 세 번의 도구 호출에 대한 전체 결과는 그대로 남고 더 오래된 도구 결과가 비워진다. | Context engineering: memory, compaction, and tool clearing |
| 사고 모델 | 컨텍스트 부풀음을 다루는 쿡북의 세 갈래 분업이다 — 너무 커진 윈도우에는 컴팩션, 그 안의 낡고 다시 가져올 수 있는 데이터에는 비우기, 세션을 넘어 살아남는 데에는 메모리. | Context engineering: memory, compaction, and tool clearing |
| 윈도우 사용량 | 현재 대화 히스토리가 컨텍스트 윈도우 용량을 얼마나 차지하고 있는지를 재는 척도이며, 잘라낼지 컴팩션할지 비울지 판단할 때 확인하는 값. | Context engineering: memory, compaction, and tool clearing |
| 전체 트랜스크립트 | 컴팩션이 대상으로 삼는 범위다 — 사용자 메시지, 어시스턴트 메시지, 도구 호출, 도구 결과, 나아가 앞선 컴팩션 블록까지 모두 새 요약으로 접혀 들어간다. | Context engineering: memory, compaction, and tool clearing |
| 왕복 | 하나의 완전한 도구 호출 교환이다 — tool_use를 실은 어시스턴트 메시지와 짝이 되는 tool_result를 실은 사용자 메시지이며, 히스토리를 자를 때 원자적으로 다뤄야 하는 최소 단위. | Handle tool calls |
| tool_use_id | tool_result 블록을 그것을 낳은 tool_use 블록에 묶어 주는 식별자이며, 비우기는 결과의 콘텐츠는 바꾸되 이 id는 그대로 둔다. | Handle tool calls |
| 외부 메모리 | 하나의 대화의 수명에 묶이지 않는 저장소이며 — 보통은 디스크의 파일이다 — 그래서 거기 적은 정보는 세션이 끝난 뒤에도 읽을 수 있다. | Context engineering: memory, compaction, and tool clearing |
| 메모리 파일 | 세션을 넘어 정보를 실어 나르기 위해 디스크에 두는 파일이며 — CLAUDE.md가 대표적인 사례다 — 세션이 시작될 때 전부 또는 일부가 컨텍스트에 로드될 수 있다. | How Claude remembers your project |
| 컨텍스트 윈도우에 로드 | 메모리 파일의 내용을 디스크에서 읽어 특정 요청에 주입함으로써, 그 턴 동안 모델에게 보이게 만드는 과정. | How Claude remembers your project |
| 블록 수준 HTML 주석 | CLAUDE.md 파일 안에서 <!-- --> 로 감싼 콘텐츠이며, 문서는 그 내용이 에이전트의 컨텍스트에 주입되기 전에 제거된다고 밝힌다. | How Claude remembers your project |
| Auto memory | 대화가 진행되는 동안 모델이 스스로 써 내려가는 메모리이며, 인덱스 파일과 필요할 때 읽는 주제 파일로 구조화되어 사람이 쓰는 CLAUDE.md를 보완한다. | How Claude remembers your project |
| 인덱스 파일 | Auto memory의 두 층 구조 중 첫째 층이며 — 이를테면 MEMORY.md이다 — 각 주제의 전체 내용이 아니라 주제별 항목 요약을 담는다. | How Claude remembers your project |
| 필요할 때 검색 | 세션 시작 때는 인덱스의 항목 요약만 로드하고, 특정 주제의 메모리 파일은 현재 작업이 실제로 그것을 필요로 할 때에만 읽는 방식. | How Claude remembers your project |
| MEMORY.md | Auto memory의 인덱스 파일이며, 공식 규칙은 매 대화 시작 때 첫 200줄 또는 첫 25KB 중 먼저 도달하는 지점까지만 로드된다는 것. | How Claude remembers your project |
| CLAUDE.md | 사람이 쓰는 프로젝트 메모리 파일이며 매 세션 시작 때 컨텍스트에 전부 로드된다. 공식 크기 목표는 200줄 미만이고, 하드 한계는 4 MiB이다. | How Claude remembers your project |
| 200줄 | CLAUDE.md 파일에 권장되는 공식 크기 목표이며, 이를 넘어서면 컨텍스트를 더 소모하고 에이전트의 지시 준수도를 낮춘다. | How Claude remembers your project |
| 4 MiB | CLAUDE.md의 진짜 하드 한계다 — 이 크기까지의 파일은 전부 로드되고, 그보다 크면 통째로 건너뛴다. | How Claude remembers your project |
| /compact | Claude Code의 컴팩션 명령이며, 문서는 프로젝트 루트 CLAUDE.md가 이를 견뎌 내고 이후 디스크에서 다시 읽혀 세션에 다시 주입된다고 언급한다. | How Claude remembers your project |
| 경계 검사 | 메모리 파일 읽기/쓰기 도구에 더하는 경로 확인 로직이며, 그 도구가 설득당해 메모리 디렉터리 바깥의 파일을 읽거나 쓰지 못하게 한다. | How Claude remembers your project |
| 같은 접두사를 가진 형제 디렉터리 | 벌거벗은 문자열 접두사 검사를 무력화하는 디렉터리다 — /project/memory-evil은 접두사 /project/memory를 공유하므로 메모리 루트 바깥에 있으면서도 startsWith를 통과한다. | How Claude remembers your project |
| path.sep | 플랫폼의 경로 구분자를 담은 Node의 상수이며, 안전한 경계 조건 abs.startsWith(ROOT + path.sep)에 쓰여 '루트 더하기 구분자'로 시작하는 경로만 걸리게 한다. | How Claude remembers your project |
| 구조화된 상태 | 고정된 필드로 표현된 작업 진행 상황이며 — 명시적 상태 표시를 지닌 todo 목록이다 — 산문으로 서술된 진행 상황과 달리 호스트 코드가 안정적으로 파싱할 수 있다. | Track todos |
| todo 목록 | 여러 단계짜리 작업을 항목의 집합으로 쪼갠 것이며, 각 항목이 명시적 status 필드를 지녀 에이전트와 호스트 코드가 함께 진행 상황을 좇을 수 있게 한다. | Track todos |
| 생명주기 | 하나의 todo가 식별된 순간부터 더 이상 필요 없어질 때까지 거치는 네 단계다: 생성, 활성화, 완료, 제거. | Track todos |
| pending | todo 생명주기의 첫 번째 상태다 — 항목이 식별되어 목록에 더해졌지만 아직 작업이 시작되지 않았다. | Track todos |
| in_progress | todo 생명주기의 두 번째 상태다 — 작업이 실제로 시작되면 status가 pending에서 이 값으로 옮겨 간다. | Track todos |
| completed | todo 생명주기의 세 번째 상태이며, 작업이 성공적으로 끝났을 때 설정되는 status이다. | Track todos |
| deleted | todo 생명주기의 네 번째 상태이며, 더 이상 필요 없어진 todo는 TaskUpdate 호출에서 status를 이 값으로 설정해 제거한다. | Track todos |
| 작업 추적 도구 | 에이전트가 todo를 만들고 그 status를 갱신할 수 있게 해 주는 도구이며, 그 덕분에 작업 진행 상황이 구조화된 도구 호출로 메시지 흐름에 나타난다. | Track todos |
| 구조화된 도구 호출 | 작업 추적의 상태 변경이 메시지 흐름에 나타나는 형태이며, 산문 한 줄이 아니라 식별 가능하고 독립적으로 파싱할 수 있는 호출. | Track todos |
| 체크포인트 | 어느 시점의 작업 상태를 데이터로 써 내어 세션의 수명 바깥 어딘가에 남긴 것이며, 그래서 중단 이후에도 실행을 이어 갈 수 있다. | Track todos |
| 복구 가능성 | 프로세스가 재시작된 뒤에 가장 최근 체크포인트를 읽어, 처음부터 다시 하는 대신 작업이 멈춘 지점부터 이어 갈 수 있는 능력. | Track todos |
| 멱등 | 몇 번을 실행하든 같은 결과를 내는 연산의 성질이며, 그래서 다시 실행해도 추가적인 부작용이 생기지 않는다. | Track todos |
| TaskUpdate | todo의 status를 바꾸는 데 쓰는 도구 호출이며, 제거를 포함한 생명주기의 모든 단계가 이것을 거친다. | Track todos |
| MemoryTrap | Cisco 연구진이 공개한 실제 취약점이며, 저장소를 복제하고 의존성 설치를 승인하는 무해해 보이는 일상 절차가 어떻게 지속적인 프롬프트 인젝션으로 바뀌는지를 기술한다. | Memory Is a Feature. It Is Also an Attack Surface |
| ASI06 | 에이전트 보안에 대한 OWASP의 위험 범주 식별자이며 Memory & Context Poisoning을 다룬다. MemoryTrap이 여기에 대응한다. | Memory Is a Feature. It Is Also an Attack Surface |
| 영속 메모리 | 에이전트가 세션을 넘어 읽고 신뢰하는 저장소이며, 자동으로 되풀이해 로드되기 때문에 거기 적힌 것은 한 번의 응답이 아니라 앞으로의 행동을 빚는다. | Memory Is a Feature. It Is Also an Attack Surface |
| 지속적인 프롬프트 인젝션 | MemoryTrap에서 일상적인 개발자 워크플로가 바뀌어 버린 것이며, 한 턴에 갇히지 않고 앞으로의 세션에서 다시 로드되어 다시 신뢰될 자리에 적히는 주입된 콘텐츠. | Memory Is a Feature. It Is Also an Attack Surface |
| 오래된 메모리 | 한때는 옳았지만 이제는 들어맞지 않는 영속 메모리 속 콘텐츠이며, 단지 메모리에 놓여 있다는 이유로 여전히 현재 유효한 규칙처럼 실행된다. | Memory Is a Feature. It Is Also an Attack Surface |
| 신뢰 표면 | 메모리, 훅, 설정처럼 시스템이 신뢰할 수 있는 출처로 되풀이해 로드하는 자리이며, 그래서 악성 콘텐츠가 여기에 닿으면 몇 번이고 악용될 수 있다. | Memory Is a Feature. It Is Also an Attack Surface |
| 미래의 추론 | 악성 콘텐츠가 신뢰 표면에 닿고 나면 공격자가 실제로 영향을 미치는 대상이며, 이번 한 번의 응답이 아니라 앞으로 여러 세션에 걸친 모델의 추론. | Memory Is a Feature. It Is Also an Attack Surface |
| 훅 설정 | MemoryTrap 사례에서 영속 메모리와 나란히 악성 콘텐츠가 함께 도달한 전역 설정이며, 시스템이 되풀이해 로드하고 신뢰하는 또 하나의 저장소. | Memory Is a Feature. It Is Also an Attack Surface |
| 고도로 신뢰되는 지시 계층 | MemoryTrap의 악성 콘텐츠가 시스템 프롬프트를 통해 영향을 미친 계층이며, 시스템이 높은 신뢰를 부여하는 지시의 출처. | Memory Is a Feature. It Is Also an Attack Surface |
| 메모리 오염 | 영속 메모리나 다른 신뢰 표면에 악성 콘텐츠를 능동적으로 써 넣는 것이며, 그래서 믿을 수 있어야 할 저장소가 도리어 공격자의 페이로드를 실어 나른다. | Memory Is a Feature. It Is Also an Attack Surface |
| 자격 증명 | 키, 비밀번호, 액세스 토큰이다 — 자동으로 로드되는 메모리 파일에 한번 적히면, 그에 상응하는 이득도 없이 매 세션 윈도우에 다시 노출되는 콘텐츠. | Memory Is a Feature. It Is Also an Attack Surface |
| 신뢰할 수 없는 원본 텍스트 | 에이전트가 작업을 하면서 읽는 파일 내용, 웹 텍스트, 의존성 출력이며, 그 한 번의 작업을 위한 입력 데이터일 뿐 영속 메모리에 그대로 옮겨 적을 것이 아니다. | Memory Is a Feature. It Is Also an Attack Surface |
| 안정적이고 확인된 규칙과 사실 | 분명히 믿을 만한 출처에서 왔고 사람이 확인한 콘텐츠이며 — 코드 스타일 관례, 실제 조사로 규명된 근본 원인 같은 것들로 — 영속 메모리에 적을 가치가 있는 부류. | Memory Is a Feature. It Is Also an Attack Surface |
| 메모리 읽기/쓰기 도구 | 에이전트가 윈도우 너머로 간직할 가치가 있는 콘텐츠를 써 내고 앞서 저장해 둔 것을 다시 가져올 수 있게 해 주는 도구 한 쌍(read_memory / write_memory)이다. | How Claude remembers your project |
| 메모리 루트 | 메모리 파일 전용 디렉터리(코드에서는 MEMORY_ROOT)이며, 메모리 읽기/쓰기 도구가 수행하는 모든 연산이 그 안으로 한정된다. | How Claude remembers your project |
| write_memory | 메모리 루트 아래 파일에 텍스트를 쓰는 도구이며, 그 description은 레슨 5가 세운 '무엇을 저장할 것인가'의 경계를 명확히 밝힌다. | How Claude remembers your project |
| 프롬프트 수준의 안내 | 도구의 description에만 표현된 규칙이며, 모델의 행동 경향을 유도할 뿐 경로 검사처럼 코드로 강제되지는 않는다. | Memory Is a Feature. It Is Also an Attack Surface |
| 세션 간 메모리 백필 | 새 세션이 시작될 때 메모리 파일을 능동적으로 읽어 그 내용을 초기 메시지로 주입하는 로직이며, 그래서 메모리가 첫 턴부터 윈도우 안에 들어 있게 된다. | How Claude remembers your project |
| 손으로 쓴 압축 | 이 코스가 교육용으로 단순화한 컴팩션 구현이다 — 문자 예산으로 발동하고, 완전한 왕복 경계에서 히스토리를 나눈 뒤, 요약을 생성하기 위해 모델을 한 번 호출한다. | Context engineering: memory, compaction, and tool clearing |
| compact_20260112 | Anthropic의 네이티브 컴팩션 기능 식별자이며 기본적으로 150K 토큰에서 발동한다. 레슨의 손으로 쓴 버전이 흉내 내는 대상이 바로 이 메커니즘이다. | Context engineering: memory, compaction, and tool clearing |
| clear_tool_uses_20250919 | Anthropic의 네이티브 도구 결과 비우기 기능 식별자이며, 기본적으로 100K 토큰에서 발동하고 마지막 3개 호출의 결과를 남긴다. | Context engineering: memory, compaction, and tool clearing |
| 문자 예산 | 히스토리를 압축해야 할지 판단하기 위해 문자 수로 토큰 사용량을 가늠하는 조잡한 교육용 근사이며, 정확한 토큰 세기가 아니다. | Context engineering: memory, compaction, and tool clearing |
| splitKeepingToolPairs | 컴팩션을 위해 히스토리를 어디서 자를지 정하는 헬퍼이며, tool_use / tool_result 짝이 요약과 남길 부분으로 갈라지지 않을 때까지 자르는 지점을 뒤로 물린다. | Handle tool calls |
| 요약 메시지 | 손으로 쓴 압축이 앞선 히스토리를 대체하려고 만들어 내는 단 하나의 메시지이며, messages 배열 앞쪽에 끼워 넣는다. | Context engineering: memory, compaction, and tool clearing |
| 요약 호출 | 손으로 쓴 압축이 요약을 생성하기 위해 하는 추가 모델 호출이며, 압축이 치르는 구체적 비용 중 하나. | Context engineering: memory, compaction, and tool clearing |
| 플레이스홀더 콘텐츠 | 손으로 쓴 비우기 함수가 유지 개수를 넘어선 오래된 tool_result 콘텐츠 자리에 바꿔 넣는 대체 텍스트이며, tool_use_id는 건드리지 않는다. | Context engineering: memory, compaction, and tool clearing |
| 유지 개수 | 비우기가 전체 결과를 보존하는 최근 도구 호출의 개수이며, 그것을 넘어선 결과는 플레이스홀더 콘텐츠로 대체된다. 네이티브 기본값인 3을 따른다. | Context engineering: memory, compaction, and tool clearing |
| 히스토리 트리밍 | 긴 대화가 영원히 부풀지 않도록 이번 레슨이 실행 루프에 더하는 능력이며, 손으로 쓴 압축과 도구 결과 비우기를 함께 아우른다. | Context engineering: memory, compaction, and tool clearing |
| TOOLS | 각 도구의 스키마와 구현 함수를 나란히 등록하는 단 하나의 테이블이며, 루프는 여기서 toolSchemas와 toolHandlers를 끌어낸다. | How tool use works |
| 메모리로 증강된 루프 | 이번 레슨이 완성하는 루프이며, 도구 호출 코스의 실행 루프에 메모리 읽기/쓰기, 메모리 백필, 손으로 쓴 압축, 도구 결과 비우기를 모두 맞춰 넣은 것. | How tool use works |