100만 토큰 Context가 답이 아니다: AI Agent가 파일 시스템을 외부 기억장치처럼 쓰는 방법
100만 토큰 Context가 답이 아니다: AI Agent가 파일 시스템을 외부 기억장치처럼 쓰는 방법
AI Agent를 오래 사용하다 보면 거의 반드시 한 번은 Context 문제를 만난다.
처음에는 단순하다.
사용자 요구사항
+
관련 코드 몇 개
+
Agent 응답조금 지나면 다음이 붙는다.
Repository 조사
Build Log
Test 결과
공식 문서
Git Diff
Subagent 결과
실패한 가설
Architecture 결정
추가 요구사항장시간 Coding Agent라면 더 심하다.
Session 1
→ Repository 분석
Session 2
→ 구현
Session 3
→ 테스트 실패 분석
Session 4
→ 수정
Session 5
→ Review
Session 6
→ 추가 수정그래서 자연스럽게 이런 생각을 하게 된다.
Context Window가 더 크면
이 문제가 해결되지 않을까?128K보다 200K.
200K보다 1M.
1M보다 더 큰 Context.
실제로 최신 Frontier Model들은 매우 큰 Context Window를 지원하고 있고, 긴 문서나 대형 Repository를 다루는 능력도 계속 좋아지고 있다.
그런데 최근 Agent 연구와 실제 Coding Agent 설계를 보면 방향이 조금 달라지고 있다.
모든 정보를
Model Context 안에 넣는다.보다
정보를 File System에 둔다.
↓
Agent가 필요한 파일을 찾는다.
↓
필요한 부분만 읽는다.
↓
가공한 결과를 다시 파일로 남긴다.
↓
Main Context에는 판단에 필요한 정보만 유지한다.는 구조가 중요해지고 있다.
최근 공개된 연구 Coding Agents are Effective Long-Context Processors에서는 Coding Agent가 방대한 Text Corpus를 파일 시스템에 저장해놓고 grep, Shell, Script 같은 도구를 이용해 직접 탐색하게 하는 방식을 실험했다.
연구진은 최대 3조 Token 규모의 Corpus까지 실험했고, 여러 Long-context Benchmark에서 기존 공개 최고 결과보다 평균적으로 높은 성능을 보고했다.
더 최근에는 아예 Filesystem-Based Memory for LLM Agents라는 연구까지 나왔다.
Agent가 Markdown 파일과 Directory Tree를 장기 기억 저장소처럼 직접 읽고, 수정하고, 재구성하는 방식을 체계적으로 분석한 연구다.
이 흐름에서 중요한 생각은 하나다.
Context Window
=
Agent의 모든 기억으로 볼 필요가 없다는 것이다.
오히려
Context Window
→ Working MemoryFile System
→ External Memory로 역할을 나누는 편이 Agent 구조에 더 잘 맞을 수 있다.
이번 글에서는 이 방식을 Coding Agent에 어떻게 적용할 수 있는지 실제 구조와 파일까지 만들어보면서 정리해본다.
1. 먼저 Context Window가 왜 문제가 되는가
Model Context 안에는 생각보다 많은 정보가 들어간다.
Coding Agent를 예로 들어보자.
System Instructions
AGENTS.md
사용자 Prompt
Tool 정의
MCP Tool 설명
읽은 Source Code
Command 결과
Test Log
Subagent 결과
Conversation History모두 Context를 사용한다.
처음에는 문제가 없다.
하지만 작업이 길어지면 중요한 정보와 중요하지 않은 정보가 섞인다.
예를 들어 로그인 Race Condition을 수정하고 있다고 하자.
정말 중요한 정보는 다음 정도다.
Goal
Race Condition 수정Constraint
Public API 변경 금지Root Cause
Session refresh가 동시에 두 번 실행됨Decision
TokenStore가 아니라
SessionCoordinator에서 직렬화그런데 Context에는 다음도 계속 남아 있을 수 있다.
처음 실행한 grep 결과 400줄
실패한 Build Log 1,200줄
이미 폐기한 가설
관련 없는 File 내용
SDK 문서 전체
Subagent 원본 응답이것이 Context Pollution이다.
2. 큰 Context와 좋은 Context는 다르다
Context Window가 크다고 모든 문제를 자동으로 해결하지는 않는다.
예를 들어 1M Token을 넣을 수 있다고 하자.
다음 두 방식이 있다.
방식 A
Repository 전체
+
문서 전체
+
Log 전체
+
History 전체
↓
Model방식 B
Repository
↓
File System
Documentation
↓
File System
Logs
↓
Artifact
Main Context
↓
Goal + Decision + Relevant Evidence둘 다 Model이 필요한 정보에 접근할 수 있다.
하지만 B에서는 어떤 정보가 현재 판단에 필요한지가 더 명확하다.
최근 OpenAI도 Responses API의 Computer Environment를 설명하면서 비슷한 문제를 지적했다.
모든 입력을 Prompt Context에 직접 넣는 방식은 입력이 커질수록 비싸지고 탐색하기 어려워진다.
대신 Resource를 Container File System에 두고 Model이 필요한 파일을 선택적으로 열거나 Shell로 처리하는 패턴을 권장한다.
3. Context Window를 RAM처럼 생각해보자
개념을 단순화하면 이해하기 쉽다.
컴퓨터에서는 모든 데이터를 RAM에 올려놓지 않는다.
Storage
↓
필요한 Data
↓
RAM
↓
CPUAgent도 비슷하게 볼 수 있다.
File System / Memory Store
↓
Relevant Context
↓
Context Window
↓
Model Reasoning즉 Context Window는 저장소라기보다 현재 작업을 위한 Working Set에 가깝다.
이 관점으로 바꾸면 질문도 바뀐다.
기존 질문:
Context Window가 얼마나 큰가?새 질문:
지금 판단에 필요한 정보만
Context에 올릴 수 있는가?이쪽이 Agent 설계에서는 더 중요하다.
4. 최근 연구: Coding Agent에게 3조 Token을 직접 넣은 것이 아니다
Coding Agents are Effective Long-Context Processors 연구가 재미있는 이유다.
연구에서는 긴 Context를 모두 Model Attention에 넣지 않았다.
대신 Corpus를 파일 시스템에 구성한다.
corpus/
├── part-001.txt
├── part-002.txt
├── part-003.txt
├── ...
└── part-n.txt그리고 Coding Agent에게 일반적인 개발 Tool을 준다.
ls
find
grep
rg
sed
awk
python
ShellAgent는 질문을 받으면 스스로 탐색한다.
Question
↓
검색어 결정
↓
rg 실행
↓
관련 File 찾기
↓
일부 File 읽기
↓
Script로 가공
↓
추가 검색
↓
Answer즉 긴 Context 처리 자체를
Attention에서
Executable Interaction으로 일부 외부화한 것이다.
5. 왜 Coding Agent가 이런 작업에 잘 맞을까
Coding Agent는 원래 파일 시스템 탐색에 익숙하다.
개발할 때 이미 이런 일을 한다.
Repository 구조 확인
↓
관련 Symbol 검색
↓
File 열기
↓
호출 경로 추적
↓
Script 실행
↓
결과 저장이 능력을 Text Corpus에도 그대로 적용할 수 있다.
예를 들어 5GB짜리 Log가 있다고 하자.
좋지 않은 방식:
5GB Log
↓
Model Context불가능하거나 비효율적이다.
Coding Agent 방식:
rg "fatal|exception|timeout" logs/↓
rg "requestId=82A1" logs/↓
python scripts/group_errors.py logs/↓
error-summary.json↓
필요한 부분만 Model이 읽는다.
훨씬 자연스럽다.
6. 그래서 Agent에게 Shell이 중요한 것이다
Agent Tool을 생각하면 흔히 다음부터 떠올린다.
Vector Search
RAG
Embedding
Semantic Retrieval물론 중요하다.
하지만 Coding Agent에서는 이미 매우 강력한 검색 도구가 있다.
grep
ripgrep
find
git
jq
sqlite
Python예를 들어 JSON Log 100만 줄을 Model이 직접 읽는 대신:
jq '
select(.status == "failed")
| {
id,
error,
timestamp
}
' events.json으로 줄일 수 있다.
Model Context에는 가공된 결과만 들어간다.
7. File System Memory의 기본 구조
Agent 프로젝트에서 다음처럼 만들 수 있다.
.ai/
├── context/
│ ├── project/
│ ├── decisions/
│ ├── investigations/
│ └── references/
│
├── tasks/
│ └── current/
│ ├── goal.md
│ ├── plan.md
│ ├── checkpoint.json
│ └── working-memory.md
│
└── artifacts/
├── logs/
├── tests/
├── diffs/
└── reports/이제 Context Window에 모든 정보를 유지하지 않아도 된다.
8. goal.md는 가장 중요한 장기 기억이다
# Goal
로그인 Session Refresh 과정에서 발생하는
중복 Refresh Race Condition을 제거한다.
## Success Criteria
- 동일 Session에서 동시에 Refresh Request가 실행되지 않음
- Public API 유지
- 기존 Auth Tests 통과
- Race 재현 Test 추가Agent Session이 바뀌더라도 이 파일을 읽으면 목표를 다시 알 수 있다.
9. decisions.md에는 결론만 남긴다
# Decisions
## D-001
Race 원인은 TokenStore가 아니다.
SessionCoordinator에서
동시에 두 Refresh Task가 시작되는 것이 원인이다.
## D-002
Public API는 변경하지 않는다.
## D-003
SessionCoordinator 내부에
Single-flight 제어를 추가한다.
## D-004
NetworkClient는 공용 SDK이므로 수정하지 않는다.중요한 것은 사고 과정 전체를 저장하지 않는 것이다.
예를 들어 이런 것은 필요 없다.
처음에는 TokenStore가 문제라고 생각했는데...
그다음 Lock도 생각해봤고...
Actor도 봤지만...최종 결정과 근거만 저장한다.
10. 이것이 Conversation History와 다른 점이다
Conversation History는 시간 순서다.
Turn 1
Turn 2
Turn 3
Turn 4
Turn 5그런데 Agent가 다시 필요한 것은 시간 순서가 아닐 수 있다.
Goal
Architecture
Decision
Known Issue
Test Result즉 File System Memory는 정보를 의미 단위로 재구성할 수 있다.
11. 최근 Filesystem-Based Memory 연구가 이 부분을 직접 다뤘다
2026년 7월 말 공개된 Filesystem-Based Memory for LLM Agents에서는 Agent 장기 기억을 Directory Tree와 Markdown 파일로 유지하는 방식을 실험했다.
흥미로운 점은 Memory 역할을 세 가지로 나눴다는 것이다.
Management Agent
기억을 정리하고 통합Search Agent
필요한 기억 검색Execution Agent
실제 Task 수행개념적으로 보면 다음과 같다.
Task Experience
↓
Memory Manager
↓
filesystem/
├── projects/
├── decisions/
├── people/
├── skills/
└── incidents/그리고 다음 Task에서:
Execution Agent
↓
Search Agent
↓
Relevant Files
↓
Current Context로 가져온다.
12. 하지만 “파일로 저장하면 기억 문제가 해결된다”도 아니다
이 연구의 결과에서 특히 중요한 부분이다.
파일 시스템을 Agent가 직접 정리하게 했다고 해서 항상 답변 정확도가 올라간 것은 아니었다.
연구에서는 잘 조직된 저장 구조가 대규모 Memory에서 검색 비용을 대략 절반 수준으로 줄이는 효과를 보였지만, 조직 구조 자체가 항상 더 좋은 답변으로 이어지지는 않았다.
또 Memory가 계속 쌓이면 문제가 생겼다.
중복
충돌
오래된 정보
잘못된 분류
Directory 비대화그리고 강한 Management Agent를 제외하면 시간이 지나면서 정리 품질도 떨어지는 경향이 나타났다.
즉:
File System
=
완벽한 Memory는 아니다.
관리 전략이 필요하다.
13. 그래서 Memory에는 Lifecycle이 필요하다
Memory를 무한히 추가하면 안 된다.
다음 상태를 둔다.
active
stale
superseded
archived예:
id: decision-014
status: superseded
superseded_by: decision-028새 Architecture 결정이 나오면 기존 결정을 지우기보다 연결한다.
14. Memory Entry 예
---
id: decision-028
type: architecture
status: active
created: 2026-08-12
supersedes:
- decision-014
tags:
- auth
- concurrency
---
# Session Refresh Coordination
Refresh 요청은 SessionCoordinator에서
single-flight 방식으로 직렬화한다.
## Reason
여러 화면에서 동시에 refresh를 요청할 수 있어
TokenStore만 보호해서는 중복 Network Request를 막을 수 없다.
## Evidence
- `SessionCoordinator.swift`
- `SessionRefreshRaceTests.swift`Markdown + Metadata면 사람이 읽기도 쉽다.
15. Working Memory와 Long-term Memory를 나누자
모든 정보를 영구 보관할 필요는 없다.
Working Memory
현재 Task에만 필요하다.
현재 가설
이번 Build 실패
진행 중 File
다음 StepLong-term Memory
다음 작업에서도 가치가 있다.
Architecture Decision
Repository Gotcha
Release Rule
검증 절차
반복되는 Bug Pattern구조:
.ai/
├── memory/
│ └── long-term/
│
└── tasks/
└── current/
└── working-memory.mdTask가 끝나면 Working Memory는 정리한다.
16. Task 종료 시 Memory Promotion을 한다
현재 Task:
tasks/current/안에 여러 정보가 있다.
Task가 끝났다고 모두 Long-term Memory로 옮기지 않는다.
Agent 또는 사람이 판단한다.
이 정보가
다음 Task에서도 유용한가?YES:
memory/로 Promotion.
NO:
archive/또는 삭제.
17. Context Compression과 File Memory는 경쟁 관계가 아니다
긴 Session에서는 Context 압축이 여전히 필요하다.
구조는 다음처럼 보면 된다.
Current Context
↓
압축
↓
Summary하지만 Summary 과정에서 정보가 손실될 수 있다.
그래서 중요한 원본은 File에 둔다.
Current Context
├── Goal
├── Working Discussion
└── Recent Evidence
↓
Important Evidence
→ File System
Decision
→ decisions.md
Test Result
→ artifacts/tests/
↓
Context Compaction압축돼도 필요한 정보는 다시 읽을 수 있다.
18. 최근 Agentic Context Management 연구도 같은 방향이다
최근 공개된 Agentic Context Management 연구는 기존의 자동 Context Compression이 가진 문제를 지적한다.
일반적인 압축:
Token 80% 도달
↓
자동 압축처럼 정해진 임계치에 의해 실행된다.
문제는 Agent의 현재 사고 흐름과 관계없이 압축이 일어난다는 것이다.
이 연구에서는 Agent에게 직접 Context 관리 도구를 주었다.
Agent가 판단한다.
이 내용은 지금 필요 없음.
↓
외부 Memory로 이동필요해지면:
External Memory 검색
↓
다시 Context로 가져옴즉
Runtime이 강제로 압축에서
Agent가 Context를 관리하는 방향이다.
19. 이상적인 Agent Context 구조
개념적으로 다음과 같다.
Long-term Memory
/ \
decisions/ knowledge/
↑ ↑
│ │
└─────────┬───────────┘
│
▼
Retrieval / Search
│
▼
Working Context
│
┌──────────┼──────────┐
│ │ │
▼ ▼ ▼
Goal Current Recent
Plan Evidence
│
▼
Model
│
▼
Tool Use
│
▼
ArtifactsContext Window 자체를 Database처럼 쓰지 않는다.
20. Codex에서 이 구조를 어떻게 쓸까
Repository:
MyProject/
├── AGENTS.md
│
├── .ai/
│ ├── memory/
│ │ ├── architecture/
│ │ ├── gotchas/
│ │ └── decisions/
│ │
│ ├── tasks/
│ │ └── current/
│ │ ├── goal.md
│ │ ├── plan.md
│ │ ├── checkpoint.json
│ │ └── working-memory.md
│ │
│ └── artifacts/
│ ├── tests/
│ ├── logs/
│ └── research/
│
├── Sources/
└── Tests/AGENTS.md에는 모든 내용을 넣지 않는다.
21. AGENTS.md는 Memory Index로 사용한다
거대한 AGENTS.md:
Architecture 200줄
Release 300줄
Test 300줄
Security 200줄
History 500줄보다:
# Project
Swift 6 기반 모바일 애플리케이션.
## Commands
- Build: `make build`
- Tests: `make test`
## Architecture
상세 Architecture는 필요할 때
`.ai/memory/architecture/`에서 확인한다.
## Known Gotchas
관련 작업에서만
`.ai/memory/gotchas/`를 확인한다.
## Current Task
현재 장시간 작업이 있다면
`.ai/tasks/current/goal.md`와
`checkpoint.json`을 먼저 확인한다.처럼 Map을 준다.
22. OpenAI도 “Map을 주고 Manual 전체를 주지 말라”고 설명한다
OpenAI의 Harness Engineering 글에서 흥미로운 경험이 소개됐다.
초기에는 큰 AGENTS.md 하나에 Repository 지식을 모두 넣었다.
하지만 문제가 생겼다.
Context를 많이 사용함
모든 지침이 중요해 보여 우선순위가 사라짐
오래된 정보가 쌓임
검증이 어려움그래서 Repository 자체를 System of Record로 두고 Agent에게 Map을 제공하는 방향으로 전환했다.
이것이 File System Memory 사고방식과 정확히 맞는다.
23. Project Knowledge를 Code 옆에 둔다
예를 들어 Auth Module이 있다.
Sources/
└── Auth/관련 지식을 멀리 떨어뜨리지 않는다.
docs/
└── auth/
├── architecture.md
├── token-refresh.md
└── known-failures.md또는:
Sources/
└── Auth/
└── AGENTS.md처럼 Local Instruction을 둘 수도 있다.
Agent가 해당 영역을 읽을 때 필요한 Context를 같이 가져오는 방식이다.
24. 전체 Repository 설명을 매번 넣지 않는다
예를 들어 Camera Module을 수정한다.
Main Context에 필요한 것:
Camera Architecture
관련 API
Current Goal
Test Strategy필요 없는 것:
Payment Architecture
Release Process
Database Migration Rule
Marketing Analytics파일 시스템을 사용하면 Locality를 만들 수 있다.
25. Subagent와 File Memory를 함께 사용하면 더 강하다
예:
Main Agent
Sol / Opus↓
Explorer
Repository 조사↓
research/auth-flow.md↓
Main Agent는 조사 원문 전체를 받을 필요가 없다.
다음만 받는다.
조사 완료.
Artifact:
.ai/artifacts/research/auth-flow.md
핵심:
SessionCoordinator가 Refresh 진입점.필요하면 Main Agent가 Artifact를 직접 읽는다.
26. Main Context로 반환할 Subagent 결과를 제한한다
좋은 Subagent Return Contract:
{
"status": "completed",
"summary": "Refresh race originates in SessionCoordinator.",
"evidence": [
"Sources/Auth/SessionCoordinator.swift:142",
"Sources/Auth/TokenStore.swift:88"
],
"artifact": ".ai/artifacts/research/auth-race.md",
"uncertainties": [
"Background refresh path not yet verified"
]
}전체 조사 과정은 Artifact에 둔다.
27. 긴 Build Log도 Context에 넣지 않는다
예:
xcodebuild ... > .ai/artifacts/logs/build.log 2>&1Agent에게:
build.log 전체를 Main Context에 복사하지 마.
먼저 실패한 Target과 Error를 추출하고,
필요한 구간만 읽어.라고 한다.
Script:
rg "error:|fatal error:|BUILD FAILED" \
.ai/artifacts/logs/build.log필요하면 특정 줄만 읽는다.
28. Test Result도 구조화한다
{
"command": "make test-auth",
"status": "failed",
"passed": 84,
"failed": 1,
"failedTests": [
"SessionRefreshRaceTests.testConcurrentRefresh"
],
"log": ".ai/artifacts/tests/auth-tests.log"
}Main Context에는 JSON만 올린다.
원본 Log는 File.
29. Documentation도 필요한 부분만 읽는다
공식 SDK Documentation을 통째로 Prompt에 넣는 방식:
Documentation 300페이지
↓
Context대신:
references/
└── sdk/에 두고 Agent에게 질문한다.
현재 사용하는 refresh API의
thread safety와 cancellation 관련 내용만 찾아.Agent가 검색한다.
30. Vector Database가 필요 없는가?
아니다.
File System과 Vector Retrieval은 경쟁 기술이 아니다.
작은 Repository:
File System + grep
충분대규모 Enterprise Knowledge:
Vector Search
+
File System이 더 나을 수 있다.
구조:
Query
↓
Broad Retrieval
Vector Search
↓
Relevant Documents
↓
File System / Working Directory
↓
Agent 직접 탐색즉 RAG가 후보를 찾고 Coding Agent가 후보 안에서 정밀 탐색하는 식이다.
31. File System이 특히 좋은 경우
Source Code
Logs
JSON
CSV
Configuration
Documentation Repository
Test Results
Build Artifacts처럼 이미 구조가 있는 데이터다.
Coding Agent의 기존 Tool을 그대로 활용할 수 있다.
32. Semantic Search가 더 좋은 경우
질문 표현과 문서 표현이 크게 다름
수백만 문서 중 후보를 먼저 찾아야 함
자연어 의미 검색이 중요함
Directory 구조가 약함이다.
그래서 최종 구조는 종종 다음이 된다.
Semantic Retrieval
↓
Filesystem Workspace
↓
Shell / Code Processing
↓
Model Reasoning33. File Memory에서도 Index가 필요하다
Memory가 10개일 때는 문제가 없다.
memory/
├── auth.md
├── camera.md
└── release.md1000개가 되면 Agent도 찾기 어렵다.
그래서 index.md를 만든다.
# Memory Index
## Architecture
- `architecture/auth.md`
- `architecture/network.md`
- `architecture/camera.md`
## Known Gotchas
- `gotchas/generated-code.md`
- `gotchas/signing.md`
## Decisions
- `decisions/ADR-014.md`
- `decisions/ADR-021.md`Agent는 Index부터 읽는다.
34. Index도 너무 커지면 계층화한다
memory/
├── architecture/
│ ├── index.md
│ ├── auth.md
│ └── camera.md
│
├── incidents/
│ ├── index.md
│ ├── 2026-07-auth.md
│ └── 2026-08-build.md
│
└── skills/
├── index.md
└── release.mdDirectory 자체가 Context Navigation 구조가 된다.
35. 이름도 Agent에게 중요한 Metadata다
좋지 않은 이름:
note1.md
note2.md
final2.md
new-final.md좋은 이름:
auth-refresh-race.md
ios-signing-gotchas.md
release-validation.md
camera-frame-pipeline.mdAgent는 File Name도 검색에 사용한다.
36. Memory 파일은 작게 유지한다
architecture.md 하나가 5,000줄이면 다시 Monolithic Context 문제가 생긴다.
나눈다.
architecture/
├── overview.md
├── auth.md
├── network.md
├── camera.md
└── persistence.md각 파일은 하나의 책임을 가진다.
37. Memory에는 Source를 남겨야 한다
Agent가 다음에 읽을 때
왜 이런 결론이 났지?를 확인할 수 있어야 한다.
예:
## Evidence
- `Sources/Auth/SessionCoordinator.swift:120-184`
- PR #812
- `SessionRefreshRaceTests.swift`Memory를 “진실”처럼 쓰지 말고 Evidence와 연결한다.
38. Source가 바뀌면 Memory가 Stale할 수 있다
파일 시스템 기반 Memory의 가장 큰 문제 중 하나다.
예를 들어:
Memory
NetworkClient는 MainActor라고 돼 있다.
3개월 뒤 Architecture가 바뀌었다.
Memory를 갱신하지 않으면 Agent가 잘못된 결정을 할 수 있다.
그래서 Freshness를 둔다.
last_verified: 2026-08-12
sources:
- Sources/Network/NetworkClient.swift39. CI에서 Memory Drift를 검사할 수도 있다
예:
Memory에서 참조하는 File이 삭제됐는가?
링크가 깨졌는가?
관련 Module이 크게 변경됐는가?간단한 Script로 검사할 수 있다.
python scripts/check_memory_links.py고급 구조에서는 Agent가 PR 변경을 보고 관련 Memory Update를 제안하게 할 수 있다.
40. Memory를 Agent에게 무조건 자동 수정시키지 않는다
Agent가 자기 Memory를 자유롭게 계속 고치면 또 다른 문제가 생긴다.
잘못된 판단이 Memory에 들어가 다음 Session까지 전파될 수 있다.
예:
잘못된 분석
↓
Memory 저장
↓
다음 Agent가 읽음
↓
사실처럼 사용그래서 중요한 Memory는 Review가 필요하다.
41. Memory Risk Tier를 나눌 수 있다
Low
검색 결과 Cache
Log Summary
Temporary Notes자동 갱신 가능.
Medium
Known Gotcha
Development Workflow
Test PatternAgent 제안 + Review.
High
Architecture Decision
Security Policy
Release Policy
Production Rule사람 Review 후 반영.
42. Memory Manager Agent를 별도로 둘 수도 있다
장시간 프로젝트라면:
Execution Agent
↓
새 Decision / Result
↓
Memory Manager
↓
분류
중복 검사
기존 Memory와 충돌 검사
↓
Memory Update Proposal구조로 만들 수 있다.
Memory Manager가 코드를 수정할 필요는 없다.
43. Memory Manager Prompt 예
이번 Task에서 장기 보관할 가치가 있는 정보만 추출해.
다음은 저장하지 마.
- 일회성 로그
- 이미 코드에서 쉽게 확인 가능한 사실
- 실패한 가설
- 임시 Debug 정보
다음을 우선해.
- Architecture Decision
- 코드만 보고 알기 어려운 Gotcha
- 반복되는 실패 원인
- 검증된 Workflow
기존 .ai/memory/와 충돌하는 정보가 있으면
자동 덮어쓰지 말고 충돌을 보고해.이 정도면 꽤 실용적이다.
44. Memory Search Agent도 따로 둘 수 있다
Main Agent에게 500개 Memory File을 직접 찾게 하지 않는다.
Search Agent:
Question:
Auth Refresh와 관련된
기존 결정과 Incident를 찾아.↓
결과:
{
"files": [
".ai/memory/architecture/auth.md",
".ai/memory/incidents/2026-05-refresh-loop.md",
".ai/memory/decisions/ADR-021.md"
],
"summary": "Refresh ownership was moved to SessionCoordinator in ADR-021."
}Main Agent는 관련 3개만 읽는다.
45. 여기서 Luna나 Haiku 같은 빠른 모델이 잘 맞는다
Memory Search는 대부분:
검색
분류
요약
관련도 판단이다.
고급 Architecture 판단까지 필요하지 않다면 작은 모델을 사용할 수 있다.
예:
Main
Sol / OpusMemory Search
Luna / HaikuMemory Manager
Terra / Sonnet처럼 역할을 나눌 수 있다.
46. File Memory는 Model Routing과도 연결된다
모든 Context를 Main Agent가 직접 처리하면 비싼 모델이 모든 Token을 소비한다.
File System 구조:
Large Corpus
↓
Luna Search
↓
10개 후보
↓
Terra 정리
↓
3개 핵심 Artifact
↓
Sol 판단으로 만들 수 있다.
Token 비용도 줄일 수 있다.
47. Context Budget을 단계별로 나눠보자
예:
context_budget:
main:
role: reasoning
target: minimal
explorer:
role: retrieval
target: large
reviewer:
role: validation
target: medium
artifacts:
retention: persistentMain Agent가 가장 많은 Raw Context를 가져야 한다는 법은 없다.
오히려 반대일 수 있다.
48. Main Agent에는 “결정 가능한 Context”만 준다
Main Agent Context:
Goal
Constraints
Current Plan
Relevant Evidence
Active Decisions
Current Diff
Verification Result이 정도가 이상적이다.
49. Main Context에서 빼기 좋은 것
전체 Build Log
전체 Documentation
대량 grep 결과
완료된 Subtask 원문
오래된 Plan
실패한 가설의 상세 과정
이미 해결된 Error이런 것은 Artifact나 Memory로 이동한다.
50. Context Hygiene를 자동화할 수도 있다
장시간 Agent에게 다음 Rule을 준다.
각 Phase가 끝날 때:
1. 중요한 Decision을 decisions.md에 반영
2. Test 결과를 Artifact로 저장
3. 완료된 Investigation은 Artifact로 이동
4. Working Memory에서 해결된 항목 제거
5. checkpoint.json 갱신일종의 Garbage Collection이다.
51. Working Memory 예
# Working Memory
## Current Step
SessionCoordinator 수정.
## Active Hypothesis
refreshTask를 저장하고
동시 호출이 동일 Task를 await하도록 한다.
## Open Questions
- cancellation 전파 방식
- logout 시 refreshTask 정리
## Next Verification
SessionRefreshRaceTests 실행.짧다.
Task가 진행되면 계속 갱신한다.
52. 해결된 내용은 Working Memory에서 뺀다
처음:
Open Questions
A
B
C
DA와 B 해결.
나쁜 방식:
A resolved
B resolved
C
D좋은 방식:
C
DA와 B에서 장기 보관할 내용이 있으면 decisions.md로 이동한다.
53. Context도 Garbage Collection이 필요하다
Programming Runtime:
사용하지 않는 Object
↓
GCAgent Runtime:
더 이상 현재 추론에 필요 없는 Context
↓
Externalize / Archive라고 생각하면 된다.
54. 그런데 무엇을 버릴지 Agent가 잘못 판단하면?
이것이 어려운 문제다.
그래서 중요한 정보에는 Pin을 둘 수 있다.
pinned:
- goal
- user_constraints
- security_policy
- unresolved_blockers이 정보는 Context Compaction 대상에서도 보호한다.
55. Pin해야 하는 정보
사용자의 명시적 요구사항
완료 조건
금지 사항
보안 정책
현재 Branch 목적
Unresolved Critical Issue반대로 Raw Tool Output은 Pin하지 않는다.
56. File System Memory와 Checkpoint를 같이 쓰자
장시간 Task:
{
"taskId": "AUTH-142",
"status": "running",
"currentStep": "implementation",
"completed": [
"investigation",
"plan"
],
"memory": [
".ai/memory/decisions/ADR-021.md"
],
"artifacts": [
".ai/artifacts/research/auth-race.md"
]
}Resume할 때 전 Conversation을 다시 넣을 필요가 없다.
57. Resume 절차
Agent 시작
↓
goal.md
↓
checkpoint.json
↓
현재 plan.md
↓
관련 Memory Index
↓
Git Diff
↓
필요 Artifact
↓
Resume굉장히 명확하다.
58. 이 구조가 Long-Horizon Agent에서 특히 중요하다
몇 시간짜리 Task에서는 Conversation History도 어느 정도 버틸 수 있다.
며칠짜리 Task에서는 상황이 달라진다.
Session 종료
Model 변경
Agent 재시작
Repository 변경
사람 개입이 발생한다.
Conversation만 Memory로 쓰면 복구가 어렵다.
파일은 남는다.
59. Repository 자체가 Agent Memory가 된다
이 구조의 좋은 점은 사람도 읽을 수 있다는 것이다.
Agent Memory가 별도의 Black Box Database가 아니라
Markdown
JSON
Source
Git History로 존재한다.
Git으로 Review도 가능하다.
60. Memory도 Pull Request로 관리할 수 있다
예:
Agent
Architecture 변경 발견
↓
memory update
↓
PRDiff:
- Authentication refresh is handled by TokenStore.
+ Authentication refresh is coordinated by SessionCoordinator.사람이 확인한다.
Agent 지식 자체도 Code Review 대상이 된다.
61. File System Memory의 또 다른 장점은 Portability다
Model을 바꿔도 된다.
Codex
↓
Claude Code
↓
Gemini Agent모두 File을 읽을 수 있다.
특정 Vendor Memory API에 완전히 종속되지 않는다.
62. Skill도 File System Memory의 한 종류로 볼 수 있다
다음 구조를 보자.
memory/
사실과 결정skills/
업무 방법둘 다 File System에 존재한다.
예:
memory/
└── signing.mdskills/
└── ios-release/
└── SKILL.md하나는
무엇을 알고 있는가이고
다른 하나는
어떻게 작업하는가다.
63. 최근 Filesystem Memory 연구도 Declarative Memory와 Skill을 같이 본다
앞서 언급한 연구에서는 Task Trajectory에서 Skill을 추출해 같은 파일 저장소 안에 유지하는 구조도 함께 실험했다.
즉 Agent의 장기 지식이 점차 다음처럼 통합될 수 있다.
Agent Workspace
├── knowledge/
├── decisions/
├── experiences/
└── skills/파일 시스템이 단순 Storage가 아니라 Agent Knowledge Architecture가 되는 것이다.
64. 하지만 Repository에 모든 것을 Commit하면 안 된다
다음 정보는 Commit하면 안 된다.
Secret
개인정보
Customer Data
민감한 Log
Access Token
내부 CredentialMemory Pipeline에도 Data Classification이 필요하다.
memory_policy:
public:
persist: true
internal:
persist: true
confidential:
persist: restricted
restricted:
persist: false65. Local Memory와 Shared Memory를 나눈다
.ai/memory/팀 공유.
~/.agent-memory/개인 Local.
예:
팀 공유:
Architecture
Build Rule
Known Gotcha개인 Local:
내가 선호하는 작업 방식
Local Simulator 이름
개인 ShortcutRepository Secret은 어느 쪽에도 넣지 않는다.
66. Memory가 잘못되면 Context Window보다 더 위험할 수도 있다
Context는 Session이 끝나면 사라질 수 있다.
Persistent Memory는 계속 남는다.
잘못된 Memory:
Production에서는 feature X를 사용하지 않는다.그런데 사실은 이미 사용 중이다.
다음 20개 Agent Session이 계속 잘못된 정보를 사용할 수 있다.
그래서 Persistent Memory는 Freshness와 Verification이 중요하다.
67. Source of Truth를 구분한다
우선순위:
Code / Config
↓
공식 Documentation
↓
Decision Record
↓
Agent Memory SummaryMemory와 Code가 충돌하면 Code를 확인한다.
Agent에게도 명시한다.
Memory는 탐색을 위한 도움이다.
현재 Repository 상태와 충돌하면
Repository를 Source of Truth로 사용한다.68. Memory를 “Cache”라고 생각하면 편하다
Cache는 유용하지만 Source of Truth가 아니다.
Source
↓
Memory Cache
↓
AgentCache가 오래됐다면 갱신한다.
이 관점이 안전하다.
69. 실제 Codex Prompt 예
이 작업에서는 Main Context를 작게 유지해.
먼저 다음만 읽어.
- AGENTS.md
- .ai/tasks/current/goal.md
- .ai/tasks/current/checkpoint.json
필요한 과거 정보가 있으면
.ai/memory/index.md에서 관련 파일을 찾고
필요한 파일만 추가로 읽어.
Repository 탐색과 긴 로그 분석은 Subagent에게 맡겨.
Subagent의 원본 조사 내용을 Main Conversation에 복사하지 말고
.ai/artifacts/에 저장해.
Main Agent에게는 다음만 반환해.
- 결론
- 근거
- Artifact 경로
- 아직 확인되지 않은 점
중요한 Architecture 결정이 확정되면
decisions.md 업데이트를 제안해.
실패한 가설과 일회성 로그는 장기 Memory에 저장하지 마.이 정도만으로 Context 사용 방식이 상당히 달라진다.
70. Claude Code에서도 같은 패턴을 쓸 수 있다
Claude Code는 File 탐색과 Subagent를 적극 활용하는 구조다.
Main Claude에게:
Repository 전체를 직접 읽지 마.
Explore Agent에게 Auth 영역을 조사하게 하고
관련 File과 호출 경로만 요약해서 반환하게 해.할 수 있다.
Anthropic도 대형 Codebase에서는 Subagent를 사용해 검색·조사 작업을 별도 Context에서 수행하면 Main Context를 보존하는 데 도움이 된다고 설명한다.
71. CLAUDE.md도 Index 역할만 하게 만들 수 있다
# Project
모바일 애플리케이션 Monorepo.
## Commands
- Build: `make build`
- Tests: `make test`
## Context
Architecture:
`docs/architecture/index.md`
Known Issues:
`.ai/memory/gotchas/index.md`
Current long-running task:
`.ai/tasks/current/`
## Rule
현재 Task에 필요한 문서만 읽는다.
관련 없는 Reference Directory를 한 번에 로드하지 않는다.앞서 다뤘던 “CLAUDE.md를 작게 유지하자”는 흐름과도 연결된다.
72. Context Window가 큰 모델은 여전히 중요하다
여기서 오해하면 안 된다.
Large Context Window
필요 없음이라는 이야기가 아니다.
큰 Context가 특히 좋은 상황이 있다.
여러 File을 동시에 비교
큰 Diff Review
Architecture 관계 파악
긴 Conversation 유지
복합 Evidence를 한 번에 판단중요한 것은
Context Capacity
≠
Context Strategy라는 것이다.
73. Context가 1M이라고 1M을 채우는 것이 목표가 아니다
RAM 64GB가 있다고 항상 64GB를 채우지 않는 것과 같다.
오히려 목표는:
필요한 정보
충분히 포함
+
불필요한 정보
최소화이다.
74. Large Context + External Memory가 함께 가는 방향이 현실적이다
좋은 Agent:
Large Context Window
+
File System
+
Subagent
+
Retrieval
+
Compaction중 하나를 선택하는 것이 아니다.
모두 역할이 다르다.
75. 각각의 역할
Large Context
현재 여러 Evidence를 동시에 생각.
File System
장기적이고 구조화된 외부 저장.
Retrieval
수많은 후보에서 관련 정보 찾기.
Subagent
탐색과 처리 Context를 격리.
Compaction
장시간 Conversation을 줄이기.
이 다섯 개를 함께 쓰는 것이 Agent Context Architecture다.
76. 새 Agent Runtime을 만든다면
구조를 이렇게 잡는다.
User Goal
│
▼
Main Agent
│
┌─────────┼─────────┐
│ │ │
▼ ▼ ▼
Search Explorer Reviewer
Agent Agent Agent
│ │ │
└────┬────┴────┬────┘
│ │
▼ ▼
File System Tools
│
┌────────┼────────┐
│ │ │
Memory Artifacts Skills
│ │ │
└────────┼────────┘
│
▼
Relevant Context
│
▼
Main AgentMain Agent는 중앙 Coordinator다.
Storage 역할까지 맡기지 않는다.
77. 아주 간단하게 시작하려면 5개 파일이면 된다
복잡한 Runtime이 부담스럽다면:
.ai/
├── goal.md
├── decisions.md
├── checkpoint.json
├── memory.md
└── artifacts/이 정도로 시작한다.
78. 개인 개발자 추천 구조
.ai/
├── current/
│ ├── goal.md
│ ├── plan.md
│ └── checkpoint.json
│
├── memory/
│ ├── architecture.md
│ └── gotchas.md
│
└── artifacts/충분하다.
79. 팀 규모가 커지면 확장한다
.ai/
├── memory/
│ ├── index.md
│ ├── architecture/
│ ├── incidents/
│ ├── decisions/
│ └── gotchas/
│
├── tasks/
│ ├── active/
│ └── archive/
│
├── artifacts/
│
└── policies/Memory에 Owner와 Freshness를 추가한다.
80. 이 구조를 적용했을 때 기대하는 변화
기존:
Session 길어짐
↓
Context 가득 참
↓
Compaction
↓
중요 내용 일부 손실
↓
같은 File 다시 탐색
↓
Token 증가개선:
탐색
↓
Artifact 저장
↓
Decision 저장
↓
Main Context 정리
↓
Compaction
↓
필요 시 Memory 재검색
↓
작업 계속이다.
81. Eval도 해볼 수 있다
같은 장시간 Task를 두 방식으로 실행한다.
A
Conversation History 중심B
Filesystem Memory 중심측정:
총 Token
반복 File Read
Repeated Investigation
Resume 성공률
Task 성공률
Human Correction
총 비용이런 Eval이 실제로 중요하다.
82. 특히 Resume Success Rate를 본다
Agent를 일부러 중단한다.
50% 진행
↓
Session 종료다시 시작한다.
Filesystem 구조가 좋다면:
goal
checkpoint
decisions
artifact를 읽고 이어간다.
History에 의존하는 Agent는 처음부터 다시 조사할 가능성이 높다.
83. Retrieval Cost도 봐야 한다
최근 Filesystem Memory 연구에서 재미있는 결과 중 하나가 이것이다.
잘 조직된 File Store는 큰 Memory에서 필요한 내용을 찾는 데 드는 비용을 상당히 줄였다.
즉 File 정리의 효과가
답변 정확도 무조건 상승보다
검색 경제성 개선으로 먼저 나타날 수 있다.
실무적으로 굉장히 중요하다.
Agent 비용에서 Retrieval 자체도 Token과 Tool Call을 쓰기 때문이다.
84. 그래서 Memory 품질 지표를 만들 수 있다
Retrieval Hit Rate
Average Files Opened
Stale Memory Rate
Duplicate Memory Rate
Conflicting Memory
Retrieval Token CostAgent Memory도 운영 대상이다.
85. “많이 기억하는 Agent”보다 “잘 잊는 Agent”가 중요할 수 있다
Agent Memory 이야기를 하면 대부분
어떻게 더 많이 기억할까?를 생각한다.
하지만 장기 운영에서는 반대가 중요해진다.
무엇을 버릴까?
무엇을 Archive할까?
무엇을 갱신할까?
무엇은 다시 검색하면 될까?좋은 Memory System은 저장 기능뿐 아니라 Forgetting Policy가 있다.
86. 모든 Tool Result를 Memory로 저장하지 않는다
예:
git status 결과영구 기억 필요 없음.
Build #142의 전체 로그장기 기억 필요 없음.
Build가 특정 Xcode Version에서 실패하는 반복 Gotcha장기 기억 후보.
이 차이를 두어야 한다.
87. 기억해야 할 것과 다시 계산할 것을 구분한다
다시 쉽게 구할 수 있는 정보:
현재 git status
현재 Package Version
현재 File 내용Memory에 중복 저장하지 않아도 된다.
다시 얻기 어려운 정보:
왜 Architecture를 이렇게 정했는가
지난 Incident에서 무엇이 원인이었는가
어떤 대안을 검토하고 제외했는가Memory 가치가 높다.
88. 최종 Context 정책
정리한다면 다음 정도다.
MAIN CONTEXT
Goal
Constraint
Current Plan
Current Evidence
Open QuestionsFILESYSTEM MEMORY
Architecture
Decision
Gotcha
Prior Incident
Reusable KnowledgeARTIFACT
Log
Test Result
Research
Large Diff
Raw OutputSKILL
Repeatable ProcedureSOURCE CODE
Current Truth역할이 명확하다.
89. 피해야 할 패턴
Repository 전체를 Prompt에 넣기
Context가 커졌다고 무조건 좋은 것이 아니다.
Log 전체를 Main Agent에게 반환
Artifact로 남기고 Error만 추출한다.
AGENTS.md 하나에 모든 지식 저장
Index와 Local Documentation으로 나눈다.
모든 Session 내용을 Memory로 Promotion
Memory가 Garbage Dump가 된다.
Memory를 Source of Truth로 취급
현재 Code와 공식 Config를 우선한다.
Agent에게 Memory를 무제한 자동 수정
오류가 장기적으로 전파될 수 있다.
Context Compaction만 믿기
압축된 Summary에서 정보가 빠질 수 있다.
90. 마무리
Context Window 경쟁은 계속될 것이다.
200K
↓
1M
↓
더 큰 Context는 분명 Agent 성능에 도움이 된다.
하지만 Agent가 실제 개발 현장에서 몇 시간, 며칠, 수십 Session을 이어가게 되면 Context Window 하나만으로는 문제를 해결하기 어렵다.
정보는 계속 늘어나기 때문이다.
그래서 Agent Architecture는 점점 다음처럼 바뀌고 있다.
모든 것을 Context에 넣는다.
↓
필요한 것만 Context에 올린다.그리고 나머지는:
File System
Memory
Artifact
Skill
Repository에 둔다.
최근 연구에서도 Coding Agent가 대규모 Corpus를 File System에서 직접 탐색하고 Shell과 Script를 이용해 필요한 정보를 가공하는 방식이 강한 Long-context 처리 능력을 보였고, 더 최근의 Filesystem Memory 연구는 Directory와 Markdown 자체가 실제 Agent 장기 기억 저장소가 될 수 있다는 가능성과 동시에 정리·오래된 정보·검색 비용 관리라는 새로운 문제도 보여줬다.
결국 중요한 것은 Context Window의 최대 숫자가 아니다.
무엇을 지금 기억할 것인가?
무엇을 File로 내려놓을 것인가?
무엇을 다시 검색할 것인가?
무엇을 영구적으로 잊을 것인가?를 Agent Runtime이 판단할 수 있어야 한다.
한 줄로 정리하면 이렇다.
100만 Token Context의 진짜 가치는
100만 Token을 전부 채우는 데 있는 것이 아니라,
필요할 때 필요한 정보를
충분히 올릴 수 있는 여유를 갖는 데 있다.그리고 장기적으로는
Context Window
=
Working MemoryFile System
=
External Memory라는 구조가 Coding Agent를 오래 안정적으로 운영하는 가장 현실적인 패턴 중 하나가 될 가능성이 크다.
앞으로 좋은 Agent는 단순히 많이 기억하는 Agent가 아니라,
무엇을 Context에 두고, 무엇을 밖으로 내리고, 필요할 때 무엇을 다시 가져와야 하는지 스스로 관리하는 Agent가 될 것이다.
참고 자료
-
Cao et al. — Coding Agents are Effective Long-Context Processors
Coding Agent가 거대한 Corpus를 Model Attention에 직접 넣는 대신 File System과 Shell·Code Tool을 이용해 탐색하도록 구성했을 때의 Long-context 처리 능력을 분석한 연구. -
Zhou et al. — Filesystem-Based Memory for LLM Agents: Organization, Evolution, and Sustainability
Markdown과 Directory Tree를 Agent 장기 기억으로 사용하는 방식을 체계적으로 분석하고 Memory Organization, Search Cost, Store Growth와 Staleness 문제를 다룬 최근 연구. -
Li et al. — ACM: Agentic Context Management for Long Horizon Tasks
고정 Token 임계치 기반 압축 대신 Agent가 스스로 Context를 외부 Memory로 내보내고 필요할 때 다시 검색하는 Agentic Context Management를 제안한 연구. -
OpenAI — From model to agent: Equipping the Responses API with a computer environment
모든 Resource를 Prompt에 직접 넣는 것을 Anti-pattern으로 보고, File System·Shell·Container를 Agent의 작업 Context로 사용해 필요한 Resource를 선택적으로 읽게 하는 공식 자료. -
OpenAI — Harness engineering: leveraging Codex in an agent-first world
거대한AGENTS.md하나에 Repository 지식을 몰아넣는 방식의 문제와, Repository Knowledge를 System of Record로 두고 Agent에게 Map을 제공하는 실제 운영 방식을 설명한 자료. -
Anthropic — Claude Code Advanced Patterns
대형 Repository에서 Subagent와 Context Strategy를 사용해 검색과 조사 Context를 Main Conversation에서 분리하는 Claude Code 운영 방법. -
Anthropic — Claude Code Best Practices
탐색 단계에서 Subagent를 사용해 세부 조사와 검증을 분리함으로써 Main Context를 보존하는 실전 Workflow를 설명한 자료.
핵심 참고 포인트
Coding Agents are Effective Long-Context Processors 연구는 일반적인 Frontier Coding Agent에게 File System과 Terminal을 제공하고 대규모 Text Corpus를 직접 탐색하게 했으며, 최대 3조 Token 규모 Corpus를 포함한 여러 Benchmark에서 기존 공개 최고 결과 대비 평균 17.3% 높은 결과를 보고했다. 중요한 점은 3조 Token을 Model Context에 직접 입력한 것이 아니라 파일 시스템을 통해 필요한 정보를 선택적으로 탐색했다는 것이다.
2026년 7월 말 공개된 Filesystem-Based Memory for LLM Agents는 Agent가 Markdown과 Directory Tree를 장기 기억으로 유지하는 방식을 분석했다. 조직화된 Store는 대규모 Memory에서 Retrieval Cost를 대략 절반으로 줄였지만, 정리된 File Structure 자체가 항상 답변 정확도를 높인 것은 아니며 Memory가 계속 성장할수록 Organization이 무너질 수 있다는 한계도 보고했다.
Agentic Context Management 연구는 Context가 일정 Token에 도달하면 자동 압축하는 고정 정책 대신 Agent가 현재 작업의 중요도를 판단해 내용을 External Memory로 이동하고 필요할 때 다시 검색하는 접근을 제안한다. 이 방식은 Long-horizon Search와 Coding Task에서 Peak Token Pressure를 낮추고 긴 탐색을 지속하는 방향을 보여준다.
OpenAI도 최근 Agent Runtime 설계에서 모든 입력을 Prompt Context에 넣는 것을 Anti-pattern으로 명시하고 있다. Resource는 Container File System에 두고 Model이 File Tool과 Shell을 이용해 필요한 부분만 읽고 가공하도록 만드는 방식을 설명하며, Codex 운영 사례에서도 “1,000페이지짜리 지침서를 주기보다 Map을 주라”는 방향을 사용하고 있다.
따라서 File System Memory는 Large Context Window를 대체하는 기술이라기보다, Large Context를 실제로 낭비하지 않기 위한 Context Architecture로 보는 편이 정확하다.
