# Agent Memory (에이전트 메모리)

*읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다.*

> **Agent Memory** = **읽고 고칠 수 있는 노트** + **언제든 버려도 되는 인덱스**입니다. 모든 노트는 출처를 밝히고, 인덱스(전문 검색, 벡터, 그래프, 개요)는 노트의 파생물일 뿐이며, 백그라운드 유지 관리 작업은 수정을 **제안**만 할 뿐 원본 저널을 고쳐 쓰지 않습니다.

**AN-07** · 적합성 수준: L2 Memory · 그룹: 지식

## 해결하려는 문제

메모리 프레임워크는 메모리를 불투명한 데이터베이스에 넣습니다. 들여다보거나, diff를 보거나, 옮기거나, 고칠 수 없고, 확실히 지우기도 어렵고, 인덱스와 임베딩 모델에 묶입니다. 게다가 메모리 자체가 공격 표면입니다. 한 [2026년 연구](https://arxiv.org/abs/2606.04329)에서 영속 메모리 오염은 두 에이전트에서 평균 50.46%의 공격 성공률에 이르렀고, [또 다른 연구](https://arxiv.org/abs/2607.05189)는 정교하게 만든 이메일 한 통으로 파일 시스템 백엔드와 벡터 메모리 백엔드 모두를 공략하는 데 성공했습니다.

한편 “어떤 메모리 아키텍처가 가장 좋은가”는 전혀 결론이 나지 않았습니다. 벤치마크끼리 서로 모순됩니다. 특정 검색 알고리즘에 걸지 않는 설계만이 3년의 변화를 견딜 수 있습니다.

## 동작 방식

- **노트가 진실입니다.** YAML 프런트매터가 있는 Markdown: `kind`(episodic, semantic, procedural, preference), `subject`, `sources`, `confidence`, `valid_from`, `valid_to`, `supersedes`, `origin`, `reviewed`.
- **덮어쓰지 말고 갱신하세요.** 새로운 사실은 옛 사실을 `supersedes`합니다. 유효 시간과 기록 시간은 따로 둡니다. 사실은 변하는데 흔한 벤치마크는 그것을 거의 시험하지 않기 때문입니다.
- **인덱스는 캐시입니다.** BM25(예: SQLite FTS5), 벡터(여러 개가 공존할 수 있음), 선택적인 그래프. 모든 파생물은 자신의 **레시피**와 **입력**을 지닙니다. 임베딩 모델을 바꾸는 것은 백그라운드 재계산이며, 새 인덱스가 기준 불러오기 테스트를 통과할 때까지 옛 인덱스는 유지됩니다.
- **두 종류의 파생.** 결정론적인 것(청킹, BM25, 고정된 모델의 임베딩)은 재현할 수 있고, 생성형인 것(LLM 요약, 추출된 사실)은 “다시 생성해 비교”할 수밖에 없으므로 `generated: true`로 표시하고 유일한 사본으로 쓰지 않습니다.
- **쓰기 경로.** `nas_remember`는 (출처와 함께) 노트를 현재 브랜치에 쓰고, 오염은 상속됩니다. `external` 오염이 있는 세션의 노트는 검토되지 않음으로 표시되어 **격리**에 들어갑니다. 불러올 수는 있지만 **자동으로 로드되지 않고** `MEMORY.md`에도 들어가지 않습니다.
- **읽기 경로.** `nas_recall` = 검색, 후보, 예산 뷰와 증거 포인터. 각 노트의 출처와 검토 상태를 보여 줍니다.
- **유지 관리 작업**(밤새 또는 한가할 때): 중복 제거, 에피소드를 의미 사실로 통합, 모순 표시, 낡은 사실 폐기, 인덱스 재구축. 작업은 브랜치에 제안을 만들어 사람이나 에이전트가 검토하게 하며, **원본 저널은 절대 지우지 않습니다.** “후회율”(롤백되는 제안의 비율)을 측정합니다.
- **기준 불러오기 테스트(golden recall).** 홈마다 “질문, 기대하는 노트” 쌍의 집합을 두고, 모델이나 인덱서가 바뀔 때 자동으로 실행합니다.

## 작게 시작하기

- 프런트매터가 있는 `memory/notes/*.md`와 검색용 SQLite FTS5.
- CI에서 기준 질문 열 개를 실행합니다.
- 벡터 인덱스와 유지 관리 작업은 나중에 더해도 됩니다. “출처”와 “검토된 노트만 자동 로드”를 먼저 제대로 하세요.

## 인터페이스 스케치

설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다.

*memory/notes/customer-acme.md*

```markdown
---
id: mem_4kq2
kind: semantic
subject: customer/acme
valid_from: 2026-10-02
valid_to: null
confidence: 0.8
origin: agent
reviewed: true
sources:
  - nas://home-box/agents/cleo/journal/2026-10-02.md@9f2c1de#L12-L18
supersedes: [mem_1xa9]
---
Acme renewed for 24 months; the champion moved from Dana to Luis.
```

## 명세가 요구하는 것

- 노트는 Memory 계층 없이도 읽을 수 있어야 합니다(Store에 있는 평범한 파일).
- 모든 파생물은 레시피와 입력을 지녀야 하며, 인덱스는 버릴 수 있고 다시 만들 수 있어야 합니다.
- 오염된 세션이 쓴 노트는 검토되기 전에는 자동으로 로드되어서는 안 됩니다.
- 새로운 사실은 덮어쓰지 않고 `supersedes`로 옛 사실을 대체해야 합니다.
- 유지 관리 작업은 브랜치에서 일하며 제안만 해야 하고, 원본 저널을 지워서는 안 됩니다.
- 모든 홈에는 기준 불러오기 테스트를 두고, 모델이나 인덱서가 바뀔 때마다 실행하는 것이 좋습니다.

## 빌려 온 것과 새로운 것

아래에 나오는 것은 모두 이미 자리 잡은 생각이며, OpenClaw의 메모리 아키텍처는 이미 출처 라벨, 계층별 격리, 통합 과정에서의 오염 전파를 하고 있습니다. **새로운 것은** OpenClaw가 이것을 **하나의 런타임 안에서** 하는 반면, 우리는 **공유 스토리지에서** 해서 어떤 런타임이든 혜택을 받게 하자고 제안하는 것, 그리고 인덱스를 버려도 되는 캐시로 강등해 메모리를 잃지 않고 검색 알고리즘을 바꿀 수 있게 하는 것입니다.

- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [Letta: is a filesystem all you need?](https://www.letta.com/blog/benchmarking-ai-agent-memory/)
- [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture)
- [Long-term memory security survey](https://arxiv.org/abs/2604.16548)
- [Graphiti](https://github.com/getzep/graphiti)
- [MemGPT](https://arxiv.org/abs/2310.08560)

## 솔직한 한계

- 생성형 파생물은 비트 단위로 똑같이 재현할 수 없습니다.
- 유지 관리 작업은 실수를 사실로 “굳힐” 수 있습니다. 그래서 제안만 하고 직접 고치지 않습니다.
- 어떤 메모리 아키텍처가 가장 좋은지는 아직 결론이 나지 않았습니다.

## 열린 질문

- 에이전트가 직접 메모리를 써야 할 때는 언제이고, 유지 관리 작업이 써야 할 때는 언제인가?
- 모델 버전을 넘나드는 회귀 기준은 무엇인가?

## 자주 묻는 질문

### 왜 벡터 데이터베이스가 아니라 파일인가요?

파일은 읽고, 고치고, diff를 보고, 가지고 나갈 수 있는 진실입니다. 벡터 인덱스는 여러 버전이 공존할 수 있고 언제든 다시 만들 수 있는 파생 캐시입니다. Letta의 벤치마크는 `grep`과 파일 도구만 가진 에이전트도 충분히 경쟁력이 있음을 보여 주었지만 벤치마크끼리 서로 모순되므로, 이 설계는 특정 검색 알고리즘에 걸지 않습니다.

### 메모리 오염은 어떻게 막나요?

나쁜 것이 절대 쓰이지 않는다고 보장할 수는 없지만, 결과는 제한할 수 있습니다. 외부에서 온 콘텐츠에는 `external` 라벨이 붙고, 오염된 세션이 쓴 노트는 격리되어 자동으로 로드되지 않으며, 병합은 검토를 거치고, 문제가 생기면 출처 사슬을 따라 영향받은 노트까지 가서 롤백할 수 있습니다.

### 임베딩 모델을 바꾸면 메모리를 마이그레이션해야 하나요?

아닙니다. 노트는 그대로이고, 인덱스만 새 레시피로 백그라운드에서 다시 계산됩니다. 새 인덱스가 기준 불러오기 테스트를 통과할 때까지 옛 인덱스는 유지됩니다.

## 관련 개념

- [Budgeted Reads (예산 읽기)](https://agentnas.com/ko/concepts/budgeted-reads/): 파일을 개요, 섹션, 줄 범위, 전체로 읽되, 예산에 맞춰 단계적으로 낮춥니다.
- [Cascade Forget (연쇄 망각)](https://agentnas.com/ko/concepts/cascade-forget/): 계보를 따라 파생물을 삭제하고, 이력은 보존 등급으로 다루며, 하지 못한 일을 보고합니다.
- [Trust Labels (신뢰 라벨)](https://agentnas.com/ko/concepts/trust-labels/): 작은 라벨 두 개와 세션 오염으로 Rule of Two를 강제합니다.

---

표준 URL: https://agentnas.com/ko/concepts/agent-memory/
최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0