# 세션 및 메모리

## 세션

### 세션 작동 방식

에이전트와의 모든 대화는 **세션**에서 이루어집니다. 세션은 컨텍스트를 인코딩하는 키로 식별됩니다, 어떤 에이전트인지, 어떤 채널인지, 어떤 채팅인지.

세션은 모든 메시지, 도구 호출, 결과의 완전한 기록(추가 전용 JSONL)을 유지합니다. 이 기록이 에이전트에게 진행 중인 대화에 대한 컨텍스트를 제공합니다.

### 세션 키

세션은 컨텍스트에 따라 자동으로 라우팅됩니다:

| 패턴 | 의미 |
|------|------|
| `agent:main:main` | 메인 직접 대화 |
| `agent:<id>:<channel>:group:<id>` | 특정 채널의 그룹 채팅 |
| `agent:<id>:<channel>:channel:<id>` | 채널/룸 대화 |
| `cron:<jobId>` | 예약된 작업 실행 |
| `hook:<uuid>` | 웹훅 트리거 실행 |

### 세션 수명 주기

- **일일 초기화**, 세션은 구성 가능한 시간(기본값 로컬 오전 4시)에 자동으로 초기화됩니다. 기록을 보존하면서 매일 새로운 대화 컨텍스트를 만듭니다.
- **유휴 만료**, 구성 가능한 기간 동안 활성화되지 않은 세션은 자동으로 초기화될 수 있습니다.
- **수동 초기화**, `/new` 또는 `/reset` 명령으로 언제든지 새로 시작합니다.

### 토큰 추적

세션은 비용 모니터링 및 컨텍스트 창 관리를 위해 누적 토큰 사용량(입력, 출력, 캐시 읽기, 캐시 쓰기)을 추적합니다.

---

## 컴팩션

### 컴팩션이란 무엇인가?

대화가 모델의 컨텍스트 창 제한에 가까워지면, Neotask는 이를 **컴팩션**합니다, 이전 메시지를 요약된 개요로 압축하고 해당 요약과 최근 메시지로 새 세션을 시작합니다.

### 작동 방식

1. **감지**, 컨텍스트 사용량 모니터링 (기본 트리거: 컨텍스트 창의 80%)
2. **요약**, 이전 메시지가 컴팩션 항목으로 요약됨
3. **새 세션**, 상단에 요약이 주입된 상태로 새 세션 시작
4. **보존**, 이전 기록은 히스토리를 위해 보존되지만 더 이상 컨텍스트에 로드되지 않음

### 구성

- **활성화/비활성화**, 자동 컴팩션 토글
- **임계값**, 컴팩션을 트리거하는 컨텍스트 창 비율 (기본값 80%)
- **최소 메시지 수**, N개 미만의 메시지가 있으면 컴팩션하지 않음

### 수동 컴팩션

`/compact` 명령으로 언제든지 수동으로 컴팩션을 트리거할 수 있습니다. 중요한 정보를 잃지 않으면서 컨텍스트를 초기화하고 싶을 때 유용합니다.

---

## 메모리

### 에이전트 메모리

각 에이전트는 세션 간에 중요한 정보를 지속하기 위한 메모리 시스템을 가집니다:

- **MEMORY.md**, 중요한 사실, 선호도, 컨텍스트가 저장되는 에이전트 워크스페이스의 마크다운 파일
- **메모리 디렉토리**, 구조화된 지식을 위한 `memory/`의 추가 파일

### 벡터 검색

Neotask는 에이전트 메모리에 대한 벡터 유사도 검색을 지원합니다:

1. **인덱싱**, 메모리 파일이 임베딩을 사용하여 인덱싱됨
2. **검색**, 에이전트가 자연어로 메모리를 쿼리함 ("사용자가 API 선호도에 대해 뭐라고 했나요?")
3. **회상**, 관련 메모리가 유사도 순으로 반환됨

### 메모리 플러그인 (LanceDB)

LanceDB 메모리 플러그인은 고급 벡터 저장소를 제공합니다:

- 영구 벡터 데이터베이스
- 구성 가능한 청크 크기 및 오버랩
- 효율적인 유사도 검색
- 메모리 파일 변경 시 자동 재인덱싱

### 자동 회상

세션 시작 시 관련 메모리를 자동으로 회상하여 에이전트의 컨텍스트에 주입할 수 있습니다. 이를 통해 전체 대화 기록을 로드하지 않고도 에이전트가 세션 간 연속성을 가질 수 있습니다.

---

## 세션 지속성

모든 세션 데이터는 로컬에 저장됩니다:

- **세션 메타데이터**, `sessions.json`은 활성 세션, 마지막 활동, 토큰 수, 구성을 추적합니다
- **기록**, 개별 세션 기록은 `.jsonl` 파일로 저장됩니다
- **복구**, 세션은 데이터 손실 없이 게이트웨이 재시작 후에도 유지됩니다

### 정리

- 구성 가능한 기간(기본값 30일) 동안 접근하지 않은 세션은 정리 대상이 됩니다
- UI 또는 API를 통해 수동 세션 관리가 가능합니다
- 컴팩션된 기록은 보관되지만 검토할 수 있습니다