# 记忆打标签策略

标签是可扩展记忆检索的秘诀。本指南展示如何为记忆打标签，让正确的记忆在正确的时间被找到。

## 为什么标签重要

没有标签，你只有扁平的全文搜索。有了标签，你就有结构化导航：

```bash
# 无标签：搜索一切
GET /memory/search?q=docker

# 有标签：按项目 + 技术过滤
GET /memory/search?q=deployment&tag=synapse&tag=docker
```

标签带来：

- **快速过滤** — `GET /memory/by-tag?tag=production`
- **范围搜索** — `?q=auth&tag=project-x`
- **分组** — 找出某项目的所有 “mistake” 记忆
- **交叉引用** — 共享标签的记忆相互关联

## 标签体系

### 项目标签

用项目名作为标签：

```
synapse, synapse-mcp, synapse-chat, synapse-sdk
```

### 技术标签

用技术名：

```
docker, kubernetes, postgres, fastify, react, typescript
```

### 主题标签

用主题分类：

```
deployment, ci-cd, auth, database, frontend, backend, security
```

### 状态标签

用状态指示：

```
active, completed, blocked, deprecated
```

### 类型标签

用类型指示：

```
decision, mistake, pattern, reference, todo
```

## 打标签规则

### 规则 1：每条记忆 2-5 个标签

太少 = 可发现性差。太多 = 噪声。

```json
// 好：3 个相关标签
{ "tags": ["synapse", "deployment", "docker"] }

// 坏：1 个标签（太窄）
{ "tags": ["synapse"] }

// 坏：10 个标签（噪声）
{ "tags": ["synapse", "deployment", "docker", "vps1", "2026", "june", "ssh", "git", "main", "production"] }
```

### 规则 2：小写、连字符

```
✅ ci-cd, api-key, mind-key
❌ CI-CD, APIKey, MindKey
```

### 规则 3：使用一致的词汇

建立一套标签词汇并坚持使用：

```
# 项目词汇
synapse, synapse-mcp, synapse-chat

# 不要写成：synapse_project, synapseProject, SYNAPSE
```

### 规则 4：按搜索意图打标签

问自己：“我以后会怎么搜这条记忆？”

```json
// 存储部署决策
{
  "content": "Decided to use Docker Swarm for Synapse deployment",
  "tags": ["synapse", "deployment", "docker", "swarm", "decision"]
}

// 你可能会搜索：?q=docker+swarm 或 ?tag=deployment
```

## 模式

### 模式 1：项目 + 主题

```json
{ "tags": ["synapse", "deployment"] }
{ "tags": ["synapse", "auth"] }
{ "tags": ["synapse-mcp", "tools"] }
```

搜索：`?tag=synapse`（所有 Synapse 项目记忆）
搜索：`?tag=synapse&q=deployment`（Synapse 的部署记忆）

### 模式 2：类型 + 领域

```json
{ "tags": ["mistake", "deployment"] }
{ "tags": ["decision", "database"] }
{ "tags": ["pattern", "auth"] }
```

搜索：`?tag=mistake`（所有错误）
搜索：`?tag=mistake&q=deployment`（部署错误）

### 模式 3：层级式

用于项目内的子项目：

```json
{ "tags": ["synapse", "synapse-docs", "markdown"] }
{ "tags": ["synapse", "synapse-mcp", "mcp"] }
{ "tags": ["synapse", "synapse-admin", "ui"] }
```

搜索：`?tag=synapse`（所有 Synapse）
搜索：`?tag=synapse-docs`（仅 docs 子项目）

### 模式 4：状态跟踪

```json
// 活跃项目
{ "tags": ["synapse", "active"], "priority": "high" }

// 已完成项目
{ "tags": ["synapse-v1", "completed"], "priority": "low" }

// 阻塞中
{ "tags": ["synapse-v2", "blocked"], "priority": "high" }
```

## 常见用例

### 找出某项目的所有决策

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=decision&tag=synapse"
```

### 找出某领域的所有错误

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=mistake&tag=deployment"
```

### 找活跃工作

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/by-tag?tag=active"
```

### 找关于某技术的记忆

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=postgres+performance&tag=database"
```

## 标签维护

### 定期审查

```python
# 找出使用少的标签（清理候选）
tags = requests.get(f"{URL}/memory/tags",
    headers={"Authorization": f"Bearer {KEY}"}).json()

for tag, count in tags.items():
    if count < 2:
        print(f"Rare tag: {tag} ({count} memories)")
```

### 合并标签

如果有不一致的标签（`docker` 和 `Docker`），合并它们：

```python
# 找出所有带 "Docker" 标签的记忆
mems = requests.get(f"{URL}/memory/by-tag?tag=Docker",
    headers={"Authorization": f"Bearer {KEY}"}).json()

# 把每条更新为 "docker"
for mem in mems["results"]:
    tags = [t.lower() for t in mem["tags"]]
    update_memory(mem["id"], tags=list(set(tags)))
```

## 最佳实践

> [!TIP]
> - **尽早建立词汇表** — 从第 1 天起就用一致的标签
> - **按搜索意图打标签** — 你以后会怎么找它？
> - **2-5 个标签是最佳点** — 太少或太多都不好
> - **小写 + 连字符** — `ci-cd` 而非 `CI/CD`
> - **定期审查** — 合并重复、移除未用

## 下一步

- [记忆最佳实践](/docs/guides/memory-best-practices)
- [FTS5 搜索](/docs/concepts/fts5-search)
- [任务驱动工作流](/docs/llm-cookbook/task-driven-workflow)