# Kioku — Restructure Dev Log (Dual Interface: MCP + CLI)

> Tracking progress for `docs/06-restructure-plan.md`

---

## 2026-02-23

### Phase 0: Refactor — Tách Service Layer ✅

**Completed:**
- [x] Tạo `src/kioku/service.py` — class `KiokuService` chứa toàn bộ business logic
  - 6 tool methods: `save_memory`, `search_memories`, `recall_related`, `explain_connection`, `list_memory_dates`, `get_timeline`
  - 2 resource methods: `read_memory_resource`, `read_entity_resource`
  - 3 prompt methods: `reflect_on_day`, `analyze_relationships`, `weekly_review`
  - `__init__` khởi tạo tất cả infrastructure (embedder, vector_store, graph_store, extractor, keyword_index) với graceful fallback
- [x] Refactor `src/kioku/server.py` — thin MCP wrapper, mỗi `@mcp.tool()` chỉ delegate 1 dòng sang `_svc.<method>()`
- [x] Cập nhật `tests/test_server.py` — monkeypatch `_svc` attributes thay vì module-level globals
- [x] Integration tests: **16/16 passed**
- [x] MCP E2E test (real DBs): **All 6 tools + 2 resources + 3 prompts passed**

**Design decisions:**
- `KiokuService.__init__` nhận optional `Settings` — dùng singleton mặc định nếu không truyền
- Lazy import không cần thiết ở Phase 0 — sẽ làm ở Phase 3 (Optional Dependencies)
- `_svc` là module-level instance trong `server.py` — khởi tạo 1 lần khi import

---

### Phase 1: Thêm CLI Interface ✅

**Completed:**
- [x] Thêm `typer>=0.24.1` vào dependencies
- [x] Tạo `src/kioku/cli.py` — 6 commands: `save`, `search`, `recall`, `explain`, `dates`, `timeline`
  - Lazy-init `KiokuService` để `--help` không trigger slow startup
  - Output JSON với `ensure_ascii=False` cho tiếng Việt
  - Tags nhận comma-separated string (`--tags work,meeting`)
- [x] Thêm `[project.scripts]` entry point: `kioku = "kioku.cli:app"`
- [x] Tạo `tests/e2e_cli.py` — E2E test cho tất cả 6 CLI commands
- [x] CLI E2E test (real DBs): **All 6 commands passed**
- [x] `kioku --help` hiển thị đầy đủ commands

**CLI syntax examples:**
```bash
kioku save "Đi ăn phở với Minh" --mood happy --tags food,friend
kioku search "dự án AI" --limit 5
kioku recall "Minh" --hops 2
kioku explain "Minh" "AI"
kioku dates
kioku timeline --from 2026-02-01 --to 2026-02-23 --limit 10
```

---

## Pending Phases

- [ ] **Phase 2** — ChromaDB Embedded Mode
- [ ] **Phase 3** — Optional Dependencies & PyPI Packaging
- [ ] **Phase 4** — Docker Packaging
- [ ] **Phase 5** — Distribution-Ready
