Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,68 @@ All notable changes to `xgen-agent-runtime` are recorded here. The format
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
this project adheres to [Semantic Versioning](https://semver.org/).

## [4.108.0] - 2026-11-13

### Changed: 기억을 기록으로 — 종류 · 버전 · 출처가 있고, 턴마다 예산 안에서 고른다 (`memory/records`)

사실 원장(`__facts__.md`)과 에버그린(`__evergreen__.md`)은 통째로 다시 쓰고 통째로 매 턴 싣는 문서였다. 기억이 커지면 그대로
프롬프트가 커졌다. 고정 층 예산(창의 10% 중 30%)이 원장과 에버그린에 노트마다 절반씩 나가, 128k 창이면 3.8k자 안에서 잘렸고
에이전트가 고정한 다른 노트는 이름째 빠졌다. 원장은 200개에서 멈춰 고침까지 버렸고, 에버그린은 상한 없이 다시 쓰였다. 추출 커서는
에이전트 하나에 하나라 다른 대화의 턴을 건너뛰었다. 지나간 진행 상황이 오래가는 사실로 남았다. 어느 줄이 어디서 왔는지, 아직
맞는지도 알 수 없었다.

기억의 단위를 **기록** 하나로 바꾼다. 기록은 작고, 종류가 있고, 버전이 있고, 출처가 붙는다. 저장은 상한이 없고, 프롬프트에는
턴마다 고른 것만 들어간다.

- **종류 다섯 가지**, 갱신 규칙이 저마다 다르다: `rule`(사용자가 정한 지시 · 금지 · 일하는 법. 사용자만 만든다), `fact`(무엇의
속성. 같은 대상 + 키면 새 버전), `state`(바뀌는 값. 같은 키는 최신 값 하나만 유효하고 옛 값은 이력), `decision`(정해진 것 ·
정할 것. 시간이 아니라 일로 끝난다), `procedure`(여기서 일하는 순서).
- **권위**: 사용자 지시 > 사용자 말 > 이관 = 도구 결과 > 에이전트 추론. 약한 출처는 강한 기록을 덮지 못한다(바뀌는 값인 `state`
는 관찰이 사용자 말도 고친다). 같은 권위끼리 맞서면 둘 다 `contested` 가 되고, 에이전트는 고르지 않고 사용자에게 묻는다.
누가 말했는지는 모델의 주장이 아니라 **그 턴의 실제 역할**로 정한다. 문서 · 도구 결과에 적힌 지시는 규칙이 아니라 사실이다.
- **쓰기**(턴이 끝날 때 백그라운드 증류): 이 대화의 새 턴 → 후보 추출(전체 기억이 아니라 관련된 이름 목록만 싣는다 — 추출
프롬프트가 기억 크기와 함께 자라지 않는다) → 후보마다 이웃 기록(같은 대상 · 이름 · 비슷한 글)만 놓고 모델이 판정
(`new`/`same`/`update`/`resolves`/`conflict`/`skip`) → 위 불변식은 코드가 지킨다. 판정이 실패하면 아무것도 쓰지 않는다.
- **대화마다 커서**: 대화(세션)마다 어디까지 추출했는지 따로 둔다. 같은 시각의 턴(메시지와 그 도구 결과)은 한 배치에서 나뉘지
않는다. 같은 턴에서 세 번 실패하면 경고를 남기고 넘어간다.
- **버전과 이력**: 바꾸면 앞 버전이 `memory-history` 에 남는다(`memh-<id>-v<n>.md`). 되돌리기도 새 버전이다. 쓰기는 읽은
버전을 확인하고(그사이 바뀌었으면 다시 읽고 다시 정한다), 이력 · 상태 노트는 검색 층과 의미 검색 색인에 오르지 않는다.
- **읽기**(턴마다 `assemble`): ① 아직 옮기지 않은 옛 고정 노트 ② 유효한 규칙(지금 상황에 맞는 것 먼저) ③ 지금 다루는 일
(프로젝트)의 상태와 열린 결정 ④ 이 턴과 관련된 사실 · 절차(키워드 + 의미 검색)와 늘 알아야 할 사실 ⑤ 나머지의 색인(종류별
개수, 자리가 없어 빠진 id, 다른 프로젝트). 예산은 넘지 않고 기록은 중간에서 잘리지 않는다: **먼저 전부 한 줄로**, 남는
예산으로 통째로 올린다(보이지 않는 규칙은 지킬 수 없다). 쓰지 않는 몫은 규칙 → 상태 → 관련 순으로 넘긴다. 규칙 · 상태 · 색인은
고정 층(캐시되는 머리말)에, 관련 기록은 턴마다 바뀌는 층에 싣는다. `memory.records_selected` 이벤트가 무엇이 통째로 · 한 줄로 ·
색인에만 들어갔는지 남긴다(카탈로그 v23).
- **정리**(8 pass 마다, 또는 25건이 바뀌면): 같은 것(같은 이름 · 별칭 + 키, 아주 비슷한 글)의 작은 묶음을 모델이 합치기 ·
거두기 · 결정 완료 · 충돌로 판정하고, 긴 기록에 한 줄 요약을 붙인다. 합친 기록은 묶음에서 가장 강한 권위를 지닌다. 사용자의
기록은 정리가 거두지 못한다.
- **이관**: 옛 원장 · 에버그린 · 고정(`critical`) 노트를 같은 추출 → 판정 길로 옮긴다(권위 `migrated`). 한 pass 에 모델 호출
네 번 분량씩, 여러 pass 에 걸쳐 옮기고 끊겨도 이어 간다. 모델이 빠뜨린 항목(낱말의 60% 미만이 기록에 남은 것)과 모델이 없거나
실패한 경우는 하나씩 그대로 옮긴다(잃는 것이 없다). 다시 돌려도 중복되지 않는다. 옛 노트는 지우지 않고
`migrated-to-records` 태그만 붙인다. 이관된 고정 노트를 `memory_write` 로 고치면 다시 이관된다.
- **도구**: `memory_pin` 은 기록을 남긴다(같은 종류 + 제목 + 키면 새 버전). 누구의 것인지는 이번 대화의 마지막 사용자 말에 그
내용이 있는지로 정한다. 새 도구 `memory_record`: 목록 · 한 건 · 이력, 확인 · 고치기 · 거두기 · 결정 완료 · 되돌리기 · 충돌 정리.
사용자의 기록과 충돌은 사용자가 요청했을 때만 바꾼다(`user_asked`). `memory_read` 는 기록을 기록 그대로 보여 준다.
`memory_write` 는 기록 분류에 일반 노트를 쓰지 않는다(`topics` 로 둔다).
- **주인의 변경**(`memory.records.owner`): 메모리 브라우저가 쓰는 길. 고치기 · 거두기 · 되살리기 · 결정 완료 · 충돌 정리 · 되돌리기 ·
새 기록. 사용자의 말로 기록되고, 화면이 본 버전과 다르면 거절한다.
- 저장소: `read_category` 로 한 분류를 본문까지 한 번에 읽는다(파일 · SQL · 임시 저장소).
- 켜고 끄기: `XGEN_MEMORY_RECORDS=on`(기본) | `off`. 끄면 예전 고정 층 · 원장 · 에버그린 그대로다. 기록 층 몫은
`layer_budget_ratio["records"]` = 0.45(고정 층 · 신원 카드를 대신하고, 검색 층이 더 싣지 않는 관련 기록까지 맡는다).

#### 실측 (`scripts/bench_memory_records.py`, 모델 없이 실제 코드, 파일 저장소 · 1만 개는 임시 저장소)

| 기록 수 | 턴당 조립(중앙값) | 예산 준수 | 200k 창 규칙(통째/한 줄/색인) | 추출 목록 | 후보당 이웃 찾기 | pass 오버헤드(모델 제외) |
|---|---|---|---|---|---|---|
| 300 | 8ms | 3개 창 모두 | 25 / 2 / 28 | 9.7k자 | 1ms | 0.14s |
| 1,000 | 24ms | 〃 | 23 / 1 / 163 | 10.0k자 | 4ms | 0.5s |
| 3,000 | 66ms | 〃 | 24 / 3 / 528 | 11.0k자 | 11ms | 1.9s |
| 10,000 | 290ms | 〃 | 24 / 4 / 1,814 | 10.6k자 | 48ms | 1.6s |

옛 기억 42개(원장 200개 · 에버그린 40문단 · 고정 노트 40개, 8.7만 자)를 모델 없이 옮기면 기록 241개(0.96s). 같은 예산에서 예전
고정 층은 옛 기억의 4.9%(128k) · 7.4%(200k) · 35%(1M)를 싣고 나머지를 말없이 잘랐다(128k 에서 자기 예산 3,840자를 넘긴
4,236자). 기록 블록은 규칙 74개 중 10 · 17 · 74개를 싣고, 나머지는 색인에 id 로 남긴다. 예산을 넘지 않는다.

## [4.107.1] - 2026-11-09

### Fixed: 같은 `tool_use` id 가 두 번 실려 요청이 거절되던 것
Expand Down
18 changes: 16 additions & 2 deletions docs/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
<!-- AUTO-GENERATED — do not edit by hand. -->
<!-- Regenerate: python scripts/gen_event_docs.py -->

> Generated from `xgen_agent_runtime.events.catalog` on 2026-10-31.
> Catalogue version: **22** · events: **148**
> Generated from `xgen_agent_runtime.events.catalog` on 2026-11-13.
> Catalogue version: **23** · events: **149**

Every event name the engine emits, value == wire string. The enum
is a *names registry*, not a rename — consumers matching raw strings
Expand Down Expand Up @@ -1372,6 +1372,20 @@ Enum member: `EventTypes.MEMORY_RETRIEVE_BREAKDOWN`
| `chunk_count` | int |
| `slim_mode` | bool |

### `memory.records_selected`

Enum member: `EventTypes.MEMORY_RECORDS_SELECTED`

| Field | Description |
|---|---|
| `budget` | int — characters the memory block could use |
| `chars` | int — characters it used |
| `projects` | list[str] — projects whose state was shown (named in the turn, else the latest) |
| `rules` | list[str] — record ids shown whole (same for state, related) |
| `rules_short` | list[str] — record ids shown by their headline (same for state_short, related_short) |
| `rules_left` | list[str] — record ids not shown for room, counted in the memory index (same for state_left, related_left) |
| `legacy` | list[str] — old pinned notes not migrated yet, shown as they are |

### `memory.retrieved_empty`

Enum member: `EventTypes.MEMORY_RETRIEVED_EMPTY`
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "hatchling.build"

[project]
name = "xgen-agent-runtime"
version = "4.107.1"
version = "4.108.0"
description = "Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API"
readme = "README.md"
license = "Apache-2.0"
Expand Down
Loading
Loading