TokenSaver Korean

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

Security Scan

The skill mostly matches its stated purpose (a Korean-optimized context DB using Fireworks embeddings) but contains hard-coded local file access and initializer logic that could upload private workspace files to an external embedding API without being clearly documented.

Purpose & Capability

The declared purpose (Korean-first context DB with embedding search, dedup, tiers, WAL) aligns with the code and requirements: the client uses an embedding API and NLP libs (konlpy/nltk). Requesting FIREWORKS_API_KEY matches the EmbeddingManager which posts to api.fireworks.ai. However some README/installation hints (npm steps for an otherwise Python package) and the presence of a platform-specific initializer script suggest sloppy packaging or environment assumptions.

Instruction Scope

SKILL.md describes generic initialization and 'automatic workspace detection', but init_bora_context.py contains hard-coded Windows paths (C:\Users\Roken\.openclaw\workspace\...) and will read local files (MEMORY.md, USER.md, SOUL.md, AGENTS.md, IDENTITY.md) and then call client.save_memory() and generate embeddings. That means local workspace documents could be read and (via the embedding API) transmitted externally; this behavior is not explicitly surfaced in SKILL.md and is scope-creep from a user-perspective.

Install Mechanism

There is no remote download or opaque installer: dependencies are standard Python packages (konlpy, nltk) referenced in SKILL.md and pyproject. No suspicious external URL downloads or extract operations were found. The only network call in code is to the Fireworks embeddings endpoint which is expected for an embedding-based skill.

Credentials

Only FIREWORKS_API_KEY is required, which is proportionate to using an external embedding provider. However the key would be used to send content (possibly sensitive) to the fireworks.ai API; requiring a single embedding API key is reasonable but the combination with the initializer that reads local files increases the risk of unintended data transmission. No other unrelated secrets are requested.

Persistence & Privilege

The skill does not request always:true and does not attempt to modify other skills or system-wide configs. It stores embeddings and some JSON files locally (embeddings.json, wal.json) which is expected for a local context DB. The initializer modifies/reads local workspace files only (no evidence of escalating privileges), but that local access is environment-specific and should be reviewed.

What to consider before installing

This skill appears to implement what it claims, but exercise caution before installing or running it: - Inspect and (if needed) remove or edit init_bora_context.py before running. It contains hard-coded Windows paths that read several workspace files and then save them into the memory DB; these files could contain sensitive info and will be sent (for embedding) to the external Fireworks API if a key is present. - Only provide a FIREWORKS_API_KEY you trust. Treat that key as granting the embedding service access to any text you send. - If you want to try the skill safely, run it in an isolated environment or test VM, and do not export your real workspace paths or secrets into that environment. - Confirm you are happy with local storage of embeddings.json/wal.json and where client.save_memory persists data. - The README contains an odd npm-related instruction for installing a Python package—review packaging/install steps carefully before copying files into ~/.openclaw or running automated install commands. If you want higher assurance, ask the author for a version of the initializer that prompts before reading files or accepts explicit file paths, and a minimal README that documents exactly which local paths the skill will read and what data it will send to api.fireworks.ai.

🧠 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 최적화