🧠 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,0004,50091%한국어 검색20,0002,00090%메모리 압축30,0003,50088%

---

🗂️ 메모리 계층화#

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

티어기간저장 방식🔥 Hot7일 내전체 내용 + 임베딩🌡️ Warm30일 내요약 + 임베딩❄️ Cold30일+키워드만 (압축)🗄️ Archive30일 미접속검색에서 제외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 최적화