Communitygithub.com

메모리 압축 시스템

OpenClaw 제어 UI를 위한 메모리 압축 시스템 — 백그라운드 실행 및 토스트 알림, 구성 가능한 토큰 임계값 기반 자동 트리거, 압축 출력 내 대화 요약 문단, 전용 설정 탭(모델 선택기 포함), 결과 기록 저장.

메모리 압축 시스템란 무엇인가요?

이 기술은 OpenClaw Control UI를 위한 메모리 압축 시스템입니다. 개발자는 이 시스템을 통해 긴 대화 세션의 토큰 사용량을 시각적으로 모니터링하고, 설정된 임계값을 초과하면 자동으로 또는 수동으로 대화 내용을 압축하여 컨텍스트 창을 효율적으로 관리할 수 있습니다. 주요 기능으로는 원형 SVG 프로그레스 링 형태의 컨텍스트 게이지 버튼, 백그라운드에서 실행되며 UI를 차단하지 않는 토스트 알림 기반 압축, 5분 디바운스가 적용된 자동 압축, 압축 결과 앞에 자연어로 작성된 대화 요약 문단 삽입, 전용 설정 탭(모델 선택, 결과 저장, 자동 압축 임계값 조정 가능), OAuth→API 키→폴백 순서의 인증 체계, 그리고 마지막 압축 결과를 JSON 파일에 저장하고 조회할 수 있는 기능을 포함합니다. 이 시스템은 OpenClaw 아키텍처 내에서 백엔드 RPC 호출과 프론트엔드 UI 컴포넌트가 유기적으로 연결되어 동작합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/LeoYeAI/openclaw-master-skills/compaction-ui-enhancements

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Compaction UI v2.1.0

OpenClaw 제어 UI를 위한 메모리 압축 시스템 — 백그라운드 실행 및 토스트 알림, 구성 가능한 토큰 임계값 기반 자동 트리거, 압축 출력 내 대화 요약 문단, 전용 설정 탭(모델 선택기 포함), 결과 기록 저장.

상태: ✅ 활성

구성 요소상태
컨텍스트 게이지 버튼✅ 작동 중
백그라운드 압축 (토스트)✅ 작동 중
자동 압축 트리거✅ 작동 중
대화 요약 문단✅ 작동 중
설정 탭 (플러그인 등록)✅ 작동 중
모델 선택기✅ 작동 중
마지막 결과 저장 및 뷰어✅ 작동 중
설정 지속성 및 다시 불러오기✅ 작동 중
인증 계층 (OAuth > API > 폴백)✅ 작동 중
채팅 기록 필터✅ 작동 중
완전한 백그라운드 격리 (채팅 간섭 없음)✅ 작동 중

기능

1. 컨텍스트 게이지 버튼 (app-render.helpers.ts)

채팅 툴바에 위치한 원형 SVG 프로그레스 링으로, 수동 압축 트리거 역할도 합니다.

  • 위치: renderChatControls() 내 세션 선택기 드롭다운 다음
  • 데이터 소스: sessionsResult.sessions[].totalTokens 및 세션 행의 contextTokens
  • 색상: 녹색 (<60%), 노란색 (60-85%), 빨간색 (≥85%)
  • 비활성화: 사용률이 20% 미만이거나 압축이 진행 중일 때
  • 툴팁: "컨텍스트: XK / YK 토큰 (Z%)" 표시

2. 백그라운드 압축 (토스트)

클릭(또는 자동 트리거) 시 압축이 표준 오른쪽 하단 토스트 시스템을 사용하여 백그라운드에서 실행됩니다. 차단 모달이 없습니다. UI는 완전히 상호작용 가능한 상태를 유지합니다.

  • 실행 중 토스트: 스피너와 함께 "메모리 압축 중" 표시
  • 완료 토스트: 체크 표시와 함께 "압축 완료: XK → YK" 표시 (5초 후 자동 종료)
  • 오류 토스트: 실패 메시지 표시 (5초 후 자동 종료)
  • 모든 백그라운드 프로세스(cron, 지식 추출 등)와 동일한 backgroundJobToasts 시스템 사용

3. 자동 압축

매 채팅 응답(final 이벤트) 후, UI는 설정된 임계값과 토큰 사용량을 비교합니다. 초과 시:

  • 백그라운드 압축이 자동으로 트리거됩니다.
  • 현재 사용률과 함께 "자동 압축 중 (X%)" 토스트가 표시됩니다.
  • 5분 디바운스로 반복 트리거를 방지합니다.
  • 압축 성공 후 채팅이 자동으로 새로고침됩니다.
  • 압축할 내용이 없으면 토스트가 자동으로 제거됩니다.

4. 대화 요약 문단

모든 압축 출력은 이제 구조화된 ## Goal 섹션 앞에 ## Conversation Summary 섹션으로 시작합니다. 이는 3-6문장의 자연어 문단으로, 다음을 포함합니다:

  • 대화의 전반적인 주제 설명
  • 논의 흐름 및 주요 전환점 설명
  • 대화가 어떻게 진행되었는지 요약
  • 과거 시제의 서사적 개요로 작성

구현: compact.ts에서 상류 압축 LLM 호출에 사용자 정의 지침이 주입됩니다. 이 지침은 사용자가 제공한 사용자 정의 지침(/compact [지침]) 앞에 추가되어 둘이 공존합니다.

출력 예시:

## Conversation Summary
대화는 사용자가 압축 시스템의 개선 사항(특히 차단 모달에서 백그라운드 토스트로의 전환)을 요청하면서 시작되었습니다. 이후 논의는 자동 압축 컨트롤이 포함된 설정 탭 추가로 이어졌습니다. 이러한 기능을 구현하고 테스트한 후, 사용자는 탭 탐색 간에 설정이 유지되지 않는 문제를 발견했고, 이는 모듈 수준 상태 캐시 수정으로 이어졌습니다. 마지막으로, 사용자는 더 나은 맥락을 위해 압축 출력에 서사적 요약 문단을 추가할 것을 요청했습니다.

## Goal
...

5. 설정 탭 (플러그인 등록)

Agent 탐색 그룹 아래 전용 Compaction 탭으로, 플러그인 UI 아키텍처를 통해 등록됩니다.

등록: plugins-ui.ts → BUILTIN_UI_VIEWS에 id: "compaction", group: "agent", position: 7, icon: "archive"로 등록

카드:

자동 압축 카드

  • 토글: 자동 압축 활성화/비활성화
  • 임계값 슬라이더: 10% ~ 95% (기본값: 60%)
  • 색상 코드: 녹색 (<60%), 노란색 (60-85%), 빨간색 (≥85%)

모델 카드

  • 드롭다운: 압축에 사용할 특정 모델 선택 또는 세션 기본값 사용
  • 프로바이더별 그룹화 및 컨텍스트 창 크기 표시
  • 경고 콜아웃 사용자 지정 모델 선택 시 (API 키 알림)
  • 폴백: 사용자 지정 모델이 실패하면 자동으로 세션 기본값으로 폴백

결과 저장 카드

  • 토글: 압축된 요약 텍스트를 검토용으로 저장하는 기능 선택

마지막 압축 카드

  • Before/After: 2열 그리드의 큰 스타일 토큰 개수
  • 통계: 저장된 토큰, 감소율, 트리거 유형, 타임스탬프, 세션 키
  • 결과 보기: 접을 수 있는 요약 뷰어 (저장이 활성화된 경우)
  • 지우기: 저장된 결과 초기화
  • 힌트: 저장이 꺼져 있을 때 "결과 저장 활성화" 메시지 표시

상태 관리:

  • 모듈 수준 상태는 세션 내에서 재렌더링 간에 유지됩니다.
  • 탭을 방문할 때마다 설정을 백엔드에서 다시 불러옵니다 (2초 지연 임계값).
  • resetCompactionSettingsState()는 테스트 및 탭 전환을 위해 내보내집니다.

6. 인증 계층

압축은 getApiKeyForModel을 통해 resolveApiKeyForProvider를 사용합니다. 이는 채팅과 동일한 인증 체인입니다:

OAuth → API 키 → 폴백

별도의 설정이 필요하지 않습니다. OAuth(Claude Max)가 기본 인증 프로필로 구성된 경우 압축이 자동으로 사용합니다. 사용자 지정 모델 선택도 이 동일한 인증 체인을 독립적으로 사용합니다.

7. 결과 저장

활성화되면 가장 최근 압축 결과가 {agentDir}/compaction-config.json에 저장됩니다:

{
  "settings": {
    "autoEnabled": true,
    "autoThresholdPercent": 60,
    "storeLastResult": true,
    "compactionModel": "anthropic/claude-sonnet-4-6"
  },
  "lastResult": {
    "timestamp": 1709283600000,
    "trigger": "manual",
    "tokensBefore": 50614,
    "tokensAfter": 4766,
    "tokensSaved": 45848,
    "percentReduction": 91,
    "sessionKey": "agent:main:main",
    "summary": "## Conversation Summary\n대화는 ...에 초점을 맞췄습니다.\n\n## Goal\n..."
  }
}

저장이 비활성화된 경우 메타데이터(타임스탬프, 토큰 개수)는 계속 저장되지만 요약 텍스트는 생략됩니다.

8. 채팅 기록 필터

  • NO_REPLY/HEARTBEAT_OK 필터링: 정확히 이 텍스트를 포함하는 어시스턴트 메시지를 건너뜁니다.
  • 압축 구분선: __openclaw.kind === "compaction" 메시지에 대해 레이블이 지정된 구분선을 렌더링합니다.

아키텍처

백엔드 RPC

메서드설명
sessions.compact압축 실행 (완료 후 결과 기록)
compaction.getSettings설정 파일에서 설정 읽기
compaction.saveSettings설정 업데이트 (임계값 자동 클램프 10-95%)
compaction.getLastResult저장된 마지막 압축 결과 가져오기
compaction.clearLastResult저장된 결과 지우기

수정된 파일

파일목적
src/gateway/server-methods/compaction.ts설정 RPC, 설정 I/O, 결과 기록
src/gateway/server-methods/sessions.tssessions.compact RPC (압축 후 결과 기록)
src/gateway/server-methods/plugins-ui.ts플러그인 뷰 등록
src/gateway/server-methods.ts핸들러 연결
src/gateway/server-methods-list.ts메서드 등록
src/gateway/method-scopes.ts스코프 등록
src/agents/pi-embedded-runner/compact.ts채팅 요약 명령어 주입
ui/src/ui/app-render.helpers.ts컨텍스트 게이지 + 백그라운드 토스트 트리거
ui/src/ui/app-gateway.tsfinal 이벤트 후 자동 압축 확인
ui/src/ui/views/compaction-settings.ts설정 탭 뷰
ui/src/ui/app-render.ts뷰 연결 + 임포트
ui/src/ui/views/chat.ts채팅 기록 필터

설정 파일

{agentDir}/compaction-config.json — 에이전트별, 첫 번째 설정 저장 시 생성됩니다.

플러그인 등록

압축 탭은 plugins-ui.ts에 내장 플러그인 뷰로 등록됩니다:

{
  id: "compaction",
  label: "Compaction",
  subtitle: "메모리 관리",
  icon: "archive",
  group: "agent",
  position: 7,
  pluginId: "compaction-ui",
}

알려진 문제점

  • 탭 방문 간 설정이 유지되지 않음: v2.1.0에서 수정되었습니다. 모듈 수준의 _state.loaded 플래그가 다시 불러오기를 방지하고 있었습니다. 이제 탭에 다시 진입할 때 2초마다 다시 불러옵니다.
  • 모델 선택기에는 API 키가 필요합니다: 사용자 지정 모델을 선택하는 경우 프로바이더의 API 키가 구성되었는지 확인하세요. UI에 경고 콜아웃이 표시됩니다.
  • 압축 모델 형식: "provider/model" 형식이어야 합니다 (예: "anthropic/claude-sonnet-4-6"). 잘못된 형식은 자동으로 무시되고 세션 기본값으로 폴백됩니다.
  • parentId 스킵-셋 전파는 메시지 전용이어야 합니다: readSessionMessages에서 메모리 플러시 메시지를 필터링할 때 스킵 셋은 message 필드가 있는 항목을 통해서만 전파되어야 합니다. 메시지가 아닌 프로토콜 항목(type:"custom")은 논리적 턴을 연결합니다. 해당 ID가 스킵 셋에 들어가면 나머지 대화 전체가 숨겨집니다. 수정 방법: 스킵 셋에 대해 parsed?.message 항목만 확인하고 해당 ID만 스킵 셋에 추가합니다.
  • 차단 모달 없음 — 절대: app-render.helpers.ts의 게이지 버튼은 절대 전체 화면 오버레이 모달을 렌더링해서는 안 됩니다. 압축은 백그라운드 프로세스입니다. 모든 상태는 오른쪽 하단 토스트 시스템을 통해 전달됩니다. compactState.phase에 조건부로 설정된 position:fixed; inset:0 오버레이를 제거하세요. 버튼은 실행 중에 스피너 아이콘을 표시할 수 있지만 UI를 차단해서는 안 됩니다.

변경 로그

v2.1.0

  • 대화 요약 문단: 압축 출력이 이제 구조화된 섹션 앞에 ## Conversation Summary 서사 문단으로 시작합니다.
  • 모델 선택기: 압축에 사용할 특정 모델을 선택하거나 세션 기본값을 사용할 수 있으며, 프로바이더별로 그룹화된 드롭다운을 제공합니다.
  • 설정 다시 불러오기 수정: 탭이 이제 설정을 영구 캐싱하는 대신 2초마다 백엔드에서 다시 불러옵니다.
  • 참조 파일 업데이트: references/를 현재 소스와 동기화했습니다.

v2.0.0

  • 백그라운드 압축: 차단 전체 화면 모달을 백그라운드 작업 토스트로 대체했습니다.
  • 자동 압축: 토큰 사용량이 임계값을 초과할 때 채팅 응답 후 트리거됩니다 (설정 가능, 기본값 60%, 5분 디바운스).
  • 설정 탭: Agent 탐색 그룹 아래 플러그인 등록된 Compaction 탭.
  • 결과 기록: sessions.compact가 압축 전/후 토큰 개수와 선택적 요약을 기록합니다.
  • 인증 계층: 채팅과 동일한 OAuth → API → 폴백 체인.
  • 설정 RPC: compaction.getSettings, compaction.saveSettings, compaction.getLastResult, compaction.clearLastResult.

v1.0.0

  • 초기 릴리스: 컨텍스트 게이지 버튼, 애니메이션 단계가 있는 차단 모달, LLM 요약을 사용한 sessions.compact RPC, 채팅 기록 NO_REPLY/HEARTBEAT_OK 필터링, 압축 구분선.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

관련 스킬