TokenSaver Korean

🧠 한국어 Context DB for AI Agents — 토큰 91% 절감. 임베딩 의미 검색, 중복 자동 병합, 메모리 계층화(Hot/Warm/Cold), 자동 아카이브, WAL 프로토콜, 엔티티 추출. Korean-first + English support.

🧠 TokenSaver Korean v2.0

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

토큰 소모를 최대 91% 절감하는 스마트 메모리 시스템. 저장·검색·압축·계층화·아카이브까지 완전 자동화.

---

✨ 핵심 기능

기능	한 줄 설명
🔍 임베딩 의미 검색	키워드가 아니라 의미로 찾습니다
🔗 중복 자동 병합	비슷한 메모리 알아서 합쳐줍니다
📊 메모리 계층화	Hot → Warm → Cold 자동 관리
🗄️ 자동 아카이브	30일 묵은 메모리 자동 정리
📝 WAL 프로토콜	저장 먼저, 응답 나중 — 유실 제로
🏷️ 엔티티 추출	사람·브랜드·제품 자동 태깅
🌐 다국어 지원	한국어(konlpy) + 영어(nltk)

---

🚀 빠른 시작

1. 환경변수 설정

bash

# Fireworks API 키 (임베딩 검색용)
export FIREWORKS_API_KEY="your-key"

# Windows PowerShell
$env:FIREWORKS_API_KEY="your-key"

2. Python에서 사용

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에서 사용

text

마스터: "닥터레이디 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일 미접속	검색에서 제외

python

# 자동 승격/강등 — 접근할수록 Hot으로 올라감
client.save_memory("test", "내용")  # → Hot
# 30일 후 자동 → Cold
# 다시 검색하면 → Warm → Hot

---

🔍 하이브리드 검색

키워드 매칭 + 임베딩 유사도를 결합한 하이브리드 검색:

python

results = client.find(
    query="광고 효율 개선",
    limit=5,
    use_embedding=True    # 임베딩 검색 ON
)

# 결과: 키워드 점수 + 임베딩 점수 = 최종 순위
# "ROAS 최적화 방법" (12.45점)
# "광고 소재 성과 분석" (9.91점)

API 실패 시 자동으로 키워드 검색으로 폴백 — 절대 안 끊김.

---

🔗 중복 자동 병합

비슷한 내용이면 새로 만들지 않고 기존 것에 업데이트:

python

# 첫 저장
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)

---

🏷️ 자동 엔티티 추출

저장 시 사람·브랜드·제품을 자동으로 인식:

python

entities = client.extract_entities("김명진 대표가 닥터레이디 리쥬-톡스 출시")
# → {'persons': ['김명진'], 'brands': ['닥터레이디'], 'products': ['리쥬-톡스']}

---

⚙️ 설정 파일 (ovk.conf)

json

{
  "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 최적화