🧠 TokenSaver Korean v2.0

AI 에이전트를 위한 한국어 최적화 Context Database

토큰 소모를 최대 91% 절감하는 스마트 메모리 시스템.

저장·검색·압축·계층화·아카이브까지 완전 자동화.

✨ 핵심 기능

🚀 빠른 시작

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="마케팅 전략")

📊 토큰 절감 효과

🗂️ 메모리 계층화

자동으로 중요도에 따라 티어를 관리합니다:

# 자동 승격/강등 — 접근할수록 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
  }
}

🛡️ 안정성

📦 의존성

> konlpy/nltk 없이도 작동합니다 (기본 토크나이저 사용).

📄 라이선스

MIT License — 자유롭게 사용, 수정, 배포 가능.

TokenSaver Korean v2.0

임베딩 검색 · 중복 병합 · 메모리 계층화 · 자동 아카이브

한국어 우선, 영어 지원, OpenClaw 최적화