# 메모리 태깅 전략

태그는 확장 가능한 메모리 검색의 비결입니다. 이 가이드는 적절한 시기에
올바른 메모리가 돌아오도록 메모리를 태깅하는 방법을 보여줍니다.

## 태그가 중요한 이유

태그가 없으면, 평면적인 전문 검색만 있습니다. 태그가 있으면, 구조화된
탐색이 가능합니다:

```bash
# Without tags: search everything
GET /memory/search?q=docker

# With tags: filter by project + technology
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
// Good: 3 relevant tags
{ "tags": ["synapse", "deployment", "docker"] }

// Bad: 1 tag (too narrow)
{ "tags": ["synapse"] }

// Bad: 10 tags (noise)
{ "tags": ["synapse", "deployment", "docker", "vps1", "2026", "june", "ssh", "git", "main", "production"] }
```

### 규칙 2: 소문자, 하이픈

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

### 규칙 3: 일관된 어휘 사용

태깅 어휘를 설정하고 고수하십시오:

```
# Project vocabulary
synapse, synapse-mcp, synapse-chat

# NOT: synapse_project, synapseProject, SYNAPSE
```

### 규칙 4: 검색 의도로 태그

"이 메모리를 어떻게 검색할 것인가?"라고 자문하십시오.

```json
// Storing a deployment decision
{
  "content": "Decided to use Docker Swarm for Synapse deployment",
  "tags": ["synapse", "deployment", "docker", "swarm", "decision"]
}

// You'll likely search: ?q=docker+swarm or ?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` (문서 하위 프로젝트만)

### 패턴 4: 상태 추적

```json
// Active project
{ "tags": ["synapse", "active"], "priority": "high" }

// Completed project
{ "tags": ["synapse-v1", "completed"], "priority": "low" }

// Blocked
{ "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
# Find rarely-used tags (candidates for cleanup)
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
# Find all memories with "Docker" tag
mems = requests.get(f"{URL}/memory/by-tag?tag=Docker",
    headers={"Authorization": f"Bearer {KEY}"}).json()

# Update each to use "docker" instead
for mem in mems["results"]:
    tags = [t.lower() for t in mem["tags"]]
    update_memory(mem["id"], tags=list(set(tags)))
```

## 모범 사례

> [!TIP]
> - **어휘를 일찍 설정** — 첫날부터 일관된 태그
> - **검색 의도로 태그** — 나중에 어떻게 찾을 것인가?
> - **2-5개 태그가 적정 지점** — 너무 적거나 너무 많으면 안 됨
> - **소문자 + 하이픈** — `CI/CD`가 아닌 `ci-cd`
> - **주기적 검토** — 중복 병합, 미사용 제거

## 다음 단계

- [메모리 모범 사례](/docs/guides/memory-best-practices)
- [FTS5 검색](/docs/concepts/fts5-search)
- [작업 기반 워크플로우](/docs/llm-cookbook/task-driven-workflow)