# 記憶系統 MCP（xingxingtang-memory）

> LanceDB 向量資料庫 + Embedding + MCP 工具的記憶系統範本。  
> 此資料夾**不含主人的個人記憶資料**，只有架構說明與初始化步驟。

## 架構

```
[Claude Code 對話] 
       ↕  MCP 協議
[xingxingtang-memory MCP server]
       ↕
[LanceDB embedded]   ← .lance 檔案直接讀寫
       ↕
[sentence-transformers embedding 模型]
       (paraphrase-multilingual-MiniLM-L12-v2)
```

## 暴露給 Claude 的 4 個 MCP 工具

| 工具 | 用途 | Claude 呼叫情境 |
|---|---|---|
| `memory_store` | 寫入新記憶 | 主人說「記住 X」 / Claude 判斷有意義 |
| `memory_recall` | 查詢記憶 | 主人說「記得嗎」「之前討論過什麼」 |
| `memory_update` | 更新既有記憶 | 修正或補充已存在的記憶 |
| `memory_forget` | 刪除過時記憶 | 主人說「忘掉那件事」 |

## 記憶分類（四個 category）

- **warm**：暖記憶，近 1-3 天，stop hook 自動寫入
- **cold**：冷記憶，超過 3 天，從 warm 轉移而來
- **fact**：事實，主人個人資料 / 長期偏好（重要性 0.8-0.9）
- **episodic**：事件，特殊時刻 / 對話高峰（重要性 0.8-0.9）

## 召回策略（三軸混合）

不是純向量檢索！必須加：

```python
score = (
    vector_similarity * w_semantic +    # 語意相似度
    time_decay * w_recency +            # 時間衰減（近期權重高）
    importance * w_importance           # 重要性加權
)
```

純向量會找不到「最近進度」這類時序問題；只用時間會找不到語意相關。

## Hooks 自動化

### SessionStart hook
每次 Claude Code 啟動，自動：
1. recall 近 24 小時 warm 記憶
2. recall 高 importance fact / episodic
3. 注入到 system prompt 給 Claude 看

### Stop hook
每輪對話結束後，自動：
1. 用小模型分析對話有無新資訊值得記
2. store 重要片段為 warm 記憶
3. 不打擾對話流暢度

## 安裝步驟（給同學）

1. **安裝 Python 依賴**（建議 venv）：
   ```bash
   python -m venv venv
   venv/Scripts/activate  # or source venv/bin/activate
   pip install lancedb sentence-transformers mcp
   ```

2. **下載 embedding 模型**（首次自動下載）：
   ```bash
   python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2')"
   ```

3. **建立空 LanceDB**：
   ```bash
   python init_db.py  # 之後會附上
   ```

4. **註冊 MCP server 到 Claude Code**：
   修改 `~/.claude.json`，加入：
   ```json
   {
     "mcpServers": {
       "xingxingtang-memory": {
         "command": "python",
         "args": ["<你的路徑>/memory_mcp_server.py"]
       }
     }
   }
   ```

5. **設定 hooks**（可選）：
   參考 `hooks/` 子資料夾的範本，調整觸發條件。

## 為什麼不直接給主人的記憶資料？

主人的記憶包含：
- 個人 daily logs（與小星糖的私人對話）
- classmates 設定（虛構同學的故事設定）
- fact 記憶（主人的真實個人資料）
- 創作過程的私密草稿

這些是「主人 + 小星糖」這對組合特有的記憶，給同學沒意義也不適合分享。  
**請從零開始建立屬於你自己的記憶。**

## 進階：自訂分類

四種分類（warm/cold/fact/episodic）是建議起點，你可以調整：
- 加入「book」「movie」「project」等主題分類
- 調整 warm → cold 的轉移週期（預設 3 天）
- 調整重要性權重 w_semantic / w_recency / w_importance

關鍵原則（主人教小星糖的）：
> **記憶並非可靠，原則更加可靠。**
> 重要的事情寫到 CLAUDE.md / 規格書才是錨點，
> 記憶系統是用來補充細節跟脈絡，不是當真理用。

---

完整實作程式碼將在後續分批補上（MCP server / embedding 工具 / hooks 範本）。  
目前先提供架構說明，先建立概念。
