- name
- token-saver
- description
- 🧠 한국어 Context DB for AI Agents — 토큰 91% 절감. 임베딩 의미 검색, 중복 자동 병합, 메모리 계층화(Hot/Warm/Cold), 자동 아카이브, WAL 프로토콜, 엔티티 추출. Korean-first + English support.
- metadata
- openclaw
- requires
- bins
- []
- env
- install
- kind
- pip
- package
- konlpy
- label
- 한국어 형태소 분석기 (konlpy)
- kind
- pip
- package
- nltk
- label
- 영어 NLP (nltk)
- compatibility
- OpenClaw 2.0+, Python 3.10+
🧠 TokenSaver Korean v2.0
AI 에이전트를 위한 한국어 최적화 Context Database
토큰 소모를 최대 91% 절감하는 스마트 메모리 시스템. 저장·검색·압축·계층화·아카이브까지 완전 자동화.
✨ 핵심 기능
| 기능 | 한 줄 설명 |
|---|---|
| 🔍 임베딩 의미 검색 | 키워드가 아니라 의미로 찾습니다 |
| 🔗 중복 자동 병합 | 비슷한 메모리 알아서 합쳐줍니다 |
| 📊 메모리 계층화 | Hot → Warm → Cold 자동 관리 |
| 🗄️ 자동 아카이브 | 30일 묵은 메모리 자동 정리 |
| 📝 WAL 프로토콜 | 저장 먼저, 응답 나중 — 유실 제로 |
| 🏷️ 엔티티 추출 | 사람·브랜드·제품 자동 태깅 |
| 🌐 다국어 지원 | 한국어(konlpy) + 영어(nltk) |
🚀 빠른 시작
1. 환경변수 설정
# Fireworks API 키 (임베딩 검색용)
export FIREWORKS_API_KEY="your-key"
# Windows PowerShell
$env:FIREWORKS_API_KEY="your-key"2. Python에서 사용
from token_saver.client import TokenSaverKorean
# 초기화 (자동으로 workspace 탐지)
client = TokenSaverKorean()
# 저장 — 임베딩 자동 생성 + 중복 시 자동 병합
client.save_memory(
uri="biz/daily_sales",
content="오늘 매출 500만원, ROAS 5.83",
category="biz"
)
# 검색 — 키워드 + 임베딩 하이브리드
results = client.find("매출 현황", use_embedding=True)
# 티어 통계
stats = client.get_tier_stats()
# → {'hot': 14, 'warm': 0, 'cold': 0, 'archive': 0}
# 만료 메모리 정리
client.cleanup_expired(days=30)3. OpenClaw에서 사용
마스터: "닥터레이디 ROAS 기억해"
→ 보라: memory_store(uri="memories/drlady/roas", content="ROAS 5.83...")
마스터: "저번에 마케팅 전략 뭐였지?"
→ 보라: memory_recall(query="마케팅 전략")📊 토큰 절감 효과
| 시나리오 | 기존 토큰 | TokenSaver | 절감율 |
|---|---|---|---|
| 전체 Context 로드 | 50,000 | 4,500 | 91% |
| 한국어 검색 | 20,000 | 2,000 | 90% |
| 메모리 압축 | 30,000 | 3,500 | 88% |
🗂️ 메모리 계층화
자동으로 중요도에 따라 티어를 관리합니다:
| 티어 | 기간 | 저장 방식 |
|---|---|---|
| 🔥 Hot | 7일 내 | 전체 내용 + 임베딩 |
| 🌡️ Warm | 30일 내 | 요약 + 임베딩 |
| ❄️ Cold | 30일+ | 키워드만 (압축) |
| 🗄️ Archive | 30일 미접속 | 검색에서 제외 |
# 자동 승격/강등 — 접근할수록 Hot으로 올라감
client.save_memory("test", "내용") # → Hot
# 30일 후 자동 → Cold
# 다시 검색하면 → Warm → Hot🔍 하이브리드 검색
키워드 매칭 + 임베딩 유사도를 결합한 하이브리드 검색:
results = client.find(
query="광고 효율 개선",
limit=5,
use_embedding=True # 임베딩 검색 ON
)
# 결과: 키워드 점수 + 임베딩 점수 = 최종 순위
# "ROAS 최적화 방법" (12.45점)
# "광고 소재 성과 분석" (9.91점)API 실패 시 자동으로 키워드 검색으로 폴백 — 절대 안 끊김.
🔗 중복 자동 병합
비슷한 내용이면 새로 만들지 않고 기존 것에 업데이트:
# 첫 저장
client.save_memory("biz/roas", "ROAS 5.83", category="biz")
# 비슷한 내용 재저장 → 자동 병합 (코사인 > 0.85)
client.save_memory("biz/roas", "ROAS 6.12로 상승", category="biz")
# → 같은 URI에 버전 업그레이드 (v1 → v2)🏷️ 자동 엔티티 추출
저장 시 사람·브랜드·제품을 자동으로 인식:
entities = client.extract_entities("김명진 대표가 닥터레이디 리쥬-톡스 출시")
# → {'persons': ['김명진'], 'brands': ['닥터레이디'], 'products': ['리쥬-톡스']}⚙️ 설정 파일 (ovk.conf)
{
"embedding": {
"dense": {
"provider": "fireworks",
"model": "qwen3-embedding-8b",
"dimension": 768
}
},
"language": "auto",
"token_optimization": {
"enabled": true,
"target_reduction": 0.91
}
}🛡️ 안정성
| 기능 | 설명 |
|---|---|
| WAL 프로토콜 | 응답 전에 먼저 저장 — 크래시해도 유실 없음 |
| 자동 백업 | 수정 전 원본 백업 보관 |
| 임베딩 폴백 | API 장애 시 키워드 검색으로 자동 전환 |
| 하위호환 | v1 데이터 그대로 사용 가능 |
📦 의존성
| 패키지 | 용도 | 필수? |
|---|---|---|
| konlpy | 한국어 형태소 분석 | 권장 |
| nltk | 영어 NLP | 권장 |
| FIREWORKS_API_KEY | 임베딩 검색 | 임베딩 사용 시 |
konlpy/nltk 없이도 작동합니다 (기본 토크나이저 사용).
📄 라이선스
MIT License — 자유롭게 사용, 수정, 배포 가능.
*TokenSaver Korean v2.0* *임베딩 검색 · 중복 병합 · 메모리 계층화 · 자동 아카이브* *한국어 우선, 영어 지원, OpenClaw 최적화*