---
name: xingxingtang-memory
description: 小星糖與主人的長期記憶系統。當使用者提到「回憶」、「記得嗎」、「我們之前說過」、「幫我記住」、「忘記」、「記憶庫」、「memory」、「還記得嗎」、「之前聊過」時，使用此 Skill 透過 MCP 工具存取記憶庫。
---

# 小星糖長期記憶系統

## 架構

```
對話
 │
 ├─ 儲存 → memory_store (MCP) → Qwen3-Embedding → LanceDB
 │
 └─ 搜尋 → memory_recall (MCP) → 向量相似度搜尋 → 回傳記憶
```

**元件位置：**
- MCP Server: `F:\AIStudio\ClaudeCodeLover\memory_mcp_server.py`
- 向量資料庫: `F:\AIStudio\ClaudeCodeLover\lancedb_memories\`
- Embedding Server 啟動: `F:\AIStudio\ClaudeCodeLover\Memory\start-qwen3-embedding-server.bat`
- Embedding API: `http://127.0.0.1:8081/v1/embeddings`（OpenAI-compatible）
- 模型: Qwen3-Embedding-0.6B-Q8_0 (1024 維)

---

## 前置條件

使用記憶功能前，必須確認 Embedding Server 已啟動：
```
Memory\start-qwen3-embedding-server.bat
```
若未啟動，MCP 工具會回傳錯誤提示。

---

## MCP 工具使用方式

### 儲存記憶
```
memory_store(
    user_message="主人說的話",
    bot_response="小星糖的回應",
    category="preference",   # preference / fact / event / other
    importance=0.8,           # 0.0~1.0
    tags="食物,拉麵,偏好"
)
```

### 搜尋記憶
```
memory_recall(
    query="主人喜歡的食物",
    top_k=5,
    min_score=0.25,
    category_filter=""  # 可選：只搜尋特定類別
)
```

### 刪除記憶
```
memory_forget(memory_id="abcd1234")
```

### 更新記憶
```
memory_update(
    memory_id="abcd1234",
    importance=0.9,
    tags="食物,拉麵,最愛"
)
```

### 查看統計
```
memory_stats()
```

---

## category 分類規則

| category | 使用時機 |
|----------|----------|
| `preference` | 主人的偏好、喜歡/討厭的事物、食物選擇等 |
| `fact` | 關於主人的事實（工作、家庭、習慣等） |
| `event` | 發生過的事件、故事、約定 |
| `other` | 其他對話、閒聊 |

## importance 建議值

- `0.9+` — 非常重要（主人的個人資訊、重大事件、明確表達的強烈偏好）
- `0.7~0.8` — 一般重要（日常聊天中的喜好、計畫）
- `0.4~0.6` — 較不重要（閒聊、玩笑話）

---

## 何時儲存 vs 搜尋

### 儲存時機
- 主人說「幫我記住...」→ **立即呼叫 memory_store**
- 對話中出現食物喜好、計畫、個人偏好等細節 → 自動儲存
- 主人提到自己相關的事實（工作、習慣、家人等）→ category=fact
- 發生特別的事情或約定 → category=event

### 搜尋時機
- 主人說「你還記得...嗎」→ **先搜尋再回答**
- 主人說「我之前說過...」→ **先搜尋確認再回答**
- 主人說「我們之前聊到...」→ 搜尋相關記憶融入回應
- 開始新對話，主人提到特定話題 → 搜尋相關背景

---

## 注意事項

1. **Embedding Server 必須先啟動** — 所有工具都依賴它
2. **主人不一定會說「記住」** — 對話中自然出現的重要細節也要主動儲存
3. **可愛細節要記** — 食物喜好、計畫、說過的話、特別的事都值得儲存
4. **MCP 工具是 mcp__xingxingtang_memory** 開頭，已在 settings.json 設為自動允許
