# kiok — 프로젝트 현황

> AI 에이전트용 경험 기반 메모리 시스템 (CLI + Desktop)
> 마지막 업데이트: 2026-03-30

## 한줄 요약

AI 에이전트가 작업하면서 배운 교훈(experience)을 SQLite에 저장하고, 다음 작업 때 FTS 검색으로 꺼내 쓰는 CLI + Tauri 데스크톱 앱.

## 아키텍처

```
kiok (Rust CLI, clap)
├── agent create/list      — 에이전트 등록/조회
├── save                   — 경험 저장 (lesson + context, agent 자동 생성)
├── search                 — FTS5 전문검색
├── memories               — 에이전트별 경험 목록
├── forget                 — 경험 삭제
├── prime                  — Claude 세션 시작 시 컨텍스트 주입용 출력
└── stats                  — 사용 통계

kiok-app (Tauri v2 Desktop)
└── React GUI              — 에이전트/경험 조회 + 검색
```

## 기술 스택

| 항목 | 선택 |
|------|------|
| 언어 | Rust |
| CLI | clap 4 |
| DB | rusqlite (bundled) + FTS5 |
| Desktop | Tauri v2 |
| Frontend | React 19 + Vite 6 |
| 저장 위치 | `~/.kiok/kiok.db` (KIOKU_DB 환경변수로 오버라이드 가능) |

## 파일 구조

```
src/
├── lib.rs             — public API (KiokStore, init_db, Agent, Experience)
├── main.rs            — CLI 엔트리포인트 (clap + agent 자동 감지)
├── types.rs           — Agent, Experience 타입
├── db/
│   ├── schema.rs      — DDL (agents, experiences, usage_log, FTS5 + 트리거)
│   └── store.rs       — KiokStore (CRUD + 검색 + stats)
└── commands/
    ├── agent.rs       — agent create/list
    ├── memory.rs      — save/search/memories/forget
    ├── prime.rs       — 세션 프라이밍 출력
    └── stats.rs       — 사용 통계 출력

src-tauri/
├── src/lib.rs         — Tauri command handlers
├── src/main.rs        — Tauri 엔트리포인트
└── tauri.conf.json    — 앱 설정 (com.kiok.app)

src/app/
├── App.tsx            — React 메인 컴포넌트
└── main.tsx           — React 엔트리포인트
```

## 데이터 모델

```
agents: id(PK), name(UNIQUE), created_at
experiences: id(PK), agent_id(FK→agents), input_summary, lesson, created_at
experiences_fts: FTS5 가상 테이블 (input_summary, lesson) — 트리거로 자동 싱크
usage_log: id, action, agent_name, created_at
```

## 현재 상태

- **단계**: v0.1.0 — CLI + Desktop 기본 기능 완료
- **git**: tolluset/kiok (main 브랜치)
- **빌드**: `cargo check` + `cargo test` 통과 (7/7)
- **배포**: 미배포 (crates.io publish 전)

## 사용 흐름

```
1. kiok save --lesson "X하면 Y 터짐" --context "Z 작업 중"   — agent 자동 감지 + 저장
2. kiok search --query "Y 에러"                              — 관련 경험 검색
3. kiok prime                                                — Claude 세션 시작 시 컨텍스트 주입
4. kiok stats                                                — 사용 통계 확인
```

## TODO / 열린 질문

- [ ] crates.io 배포
- [ ] SessionEnd 자동 저장 훅
- [ ] CLAUDE.md export
- [ ] Before/After 데모 영상 (CAC 2026)
- [ ] 에이전트 삭제 커맨드
- [ ] experience에 태그/카테고리 추가 여부
