Mnemosyne MCP

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 專案概要

Mnemosyne MCP 是一個主動的、有狀態的軟體知識圖譜引擎，採用 gRPC-First 架構，支援 AI 代理和人類開發者進行協作開發。目前已完成 Sprint 0 基礎設施搭建階段。

## 核心架構

### gRPC-First 架構模式
- **gRPC 伺服器**: 核心業務邏輯入口 (port: 50051)
- **REST Gateway**: 外部 HTTP/JSON 兼容層 (port: 8000)
- **抽象層**: `GraphStoreClient` 介面統一圖資料庫操作
- **驅動層**: FalkorDB 驅動實作具體資料庫操作

### 程式碼架構 (`src/mnemosyne/`)
```
├── api/           # FastAPI REST Gateway
├── core/          # 配置管理、日誌等核心功能
├── interfaces/    # 抽象介面定義 (GraphStoreClient)
├── drivers/       # 資料庫驅動實作 (FalkorDB)
├── schemas/       # Pydantic 數據模型
└── cli/           # 命令行工具
```

## 開發命令

### 環境設置
```bash
make dev-setup      # 快速設置開發環境 (包含 uv venv 創建)
make install        # 安裝依賴套件 (使用 uv)
make docker-up      # 啟動 FalkorDB 服務
uv venv             # 創建虛擬環境
uv pip install -e ".[dev]"  # 直接使用 uv 安裝
```

### 開發流程
```bash
make serve          # 啟動開發伺服器 (API + CLI)
make doctor         # 系統診斷檢查
make test           # 執行所有測試
make test-unit      # 僅執行單元測試
make ci-check       # CI 流程檢查 (lint + test)
```

### 程式碼品質
```bash
make format         # 格式化程式碼 (black + isort)
make lint           # 執行 lint 檢查 (flake8 + mypy)
```

### 測試與驗證
```bash
make test-cov       # 執行測試並生成覆蓋率報告
make sprint0-verify # Sprint 0 完成狀態驗證
```

## 關鍵配置

### 環境設置
- 主配置：`src/mnemosyne/core/config.py` (Pydantic Settings)
- 環境文件：`.env` (開發) / `configs/{environment}.yaml`
- FalkorDB 預設連接：`localhost:6379`

### API 設計原則
1. **契約優先**: 所有新 API 必須先在 `.proto` 文件中定義
2. **gRPC 核心**: 業務邏輯優先在 gRPC 服務中實作
3. **REST 轉譯**: FastAPI 端點僅進行 HTTP ↔ gRPC 協議轉換

## 開發最佳實踐

### 程式碼規範
- Python 3.10+，使用 black (line-length=88) 格式化
- 型別註解強制要求 (mypy 嚴格模式)
- Pydantic v2 用於數據模型驗證
- 使用 `uv` 進行快速依賴管理，不再使用 Poetry
- 標準 PEP 621 配置格式 (pyproject.toml)

### 測試策略
- 測試分類：`unit`, `integration`, `e2e` markers
- 27+ 單元測試已全部通過
- 使用 pytest 框架，支援異步測試

### 分支管理 (GitHub Flow)
- **主分支**: `main` - 永遠保持可部署狀態
- **功能分支**: `feature/*` - 短生命週期，從 main 切出，完成後立即合併
- **工作流程**:
  1. 從 main 切出 feature 分支: `git checkout -b feature/feature-name`
  2. 完成開發後推送並開 Pull Request
  3. CI/CD 檢查通過後使用 Squash & Merge 合併回 main
  4. main 分支自動觸發部署流程
- **優勢**: 極簡管理、快速迭代、適合 MVP 開發

## 重要文件參考

- **產品需求**: `docs/DEVELOPEMENT/PRD.md`
- **技術架構**: `docs/DEVELOPEMENT/TAB.md`
- **API 規格**: `docs/DEVELOPEMENT/API.md`
- **Sprint 計劃**: `docs/DEVELOPEMENT/mvp_sprint.md`

## 當前狀態 (Sprint 0 完成)

✅ 基礎設施與抽象層完成
✅ Docker Compose 環境
✅ GraphStoreClient 抽象介面
✅ FalkorDB 驅動整合
✅ 完整 API 骨架 & 健康檢查
✅ CLI 工具與開發工具鏈

下階段：實現第一個 ECL (Extract→Cognify→Load) 閉環