# Strategia tagowania pamięci

Tagi są sekretem skalowalnego pobierania wspomnień. Ten przewodnik pokazuje, jak
tagować wspomnienia, aby właściwe wracały we właściwym czasie.

## Dlaczego tagi mają znaczenie

Bez tagów ma się płaskie wyszukiwanie pełnotekstowe. Z tagami ma się
ustrukturyzowaną nawigację:

```bash
# Bez tagów: przeszukiwanie wszystkiego
GET /memory/search?q=docker

# Z tagami: filtrowanie po projekcie i technologii
GET /memory/search?q=deployment&tag=synapse&tag=docker
```

Tagi umożliwiają:

- **Szybkie filtrowanie** — `GET /memory/by-tag?tag=production`
- **Wyszukiwanie w zakresie** — `?q=auth&tag=project-x`
- **Grupowanie** — znalezienie wszystkich wspomnień „mistake" dla projektu
- **Odsyłanie krzyżowe** — wspomnienia współdzielące tagi są powiązane

## Schemat tagowania

### Tagi projektów

Używać nazw projektów jako tagów:

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

### Tagi technologii

Używać nazw technologii:

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

### Tagi tematyczne

Używać kategorii tematycznych:

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

### Tagi statusu

Używać wskaźników statusu:

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

### Tagi typów

Używać wskaźników typów:

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

## Zasady tagowania

### Zasada 1: 2-5 tagów na wspomnienie

Zbyt mało tagów = słaba wykrywalność. Zbyt wiele = szum.

```json
// Dobrze: 3 istotne tagi
{ "tags": ["synapse", "deployment", "docker"] }

// Źle: 1 tag (zbyt wąsko)
{ "tags": ["synapse"] }

// Źle: 10 tagów (szum)
{ "tags": ["synapse", "deployment", "docker", "vps1", "2026", "june", "ssh", "git", "main", "production"] }
```

### Zasada 2: małe litery, z myślnikami

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

### Zasada 3: używać spójnego słownictwa

Ustanowić słownik tagowania i się go trzymać:

```
# Słownik projektów
synapse, synapse-mcp, synapse-chat

# NIE: synapse_project, synapseProject, SYNAPSE
```

### Zasada 4: tagować z intencją wyszukiwania

Zapytać: „Jak będę szukać tego wspomnienia?"

```json
// Zapis decyzji wdrożeniowej
{
  "content": "Decided to use Docker Swarm for Synapse deployment",
  "tags": ["synapse", "deployment", "docker", "swarm", "decision"]
}

// Prawdopodobne wyszukiwania: ?q=docker+swarm lub ?tag=deployment
```

## Wzorce

### Wzorzec 1: projekt + temat

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

Wyszukiwanie: `?tag=synapse` (wszystkie wspomnienia projektu Synapse)
Wyszukiwanie: `?tag=synapse&q=deployment` (wspomnienia wdrożeniowe w Synapse)

### Wzorzec 2: typ + domena

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

Wyszukiwanie: `?tag=mistake` (wszystkie błędy)
Wyszukiwanie: `?tag=mistake&q=deployment` (błędy wdrożeniowe)

### Wzorzec 3: hierarchiczny

Dla podprojektów w projekcie:

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

Wyszukiwanie: `?tag=synapse` (cały Synapse)
Wyszukiwanie: `?tag=synapse-docs` (tylko podprojekt dokumentów)

### Wzorzec 4: śledzenie statusu

```json
// Aktywny projekt
{ "tags": ["synapse", "active"], "priority": "high" }

// Ukończony projekt
{ "tags": ["synapse-v1", "completed"], "priority": "low" }

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

## Typowe przypadki użycia

### Znalezienie wszystkich decyzji o projekcie

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

### Znalezienie wszystkich błędów w domenie

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

### Znalezienie aktywnej pracy

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

### Znalezienie wspomnień o technologii

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

## Utrzymanie tagów

### Okresowy przegląd

```python
# Znalezienie rzadko używanych tagów (kandydatów do czyszczenia)
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)")
```

### Scalanie tagów

Jeśli istnieją niespójne tagi (`docker` i `Docker`), scalić je:

```python
# Znalezienie wszystkich wspomnień z tagiem „Docker"
mems = requests.get(f"{URL}/memory/by-tag?tag=Docker",
    headers={"Authorization": f"Bearer {KEY}"}).json()

# Aktualizacja każdego na „docker"
for mem in mems["results"]:
    tags = [t.lower() for t in mem["tags"]]
    update_memory(mem["id"], tags=list(set(tags)))
```

## Najlepsze praktyki

> [!TIP]
> - **Ustanowić słownik wcześnie** — spójne tagi od pierwszego dnia
> - **Tagować z intencją wyszukiwania** — jak to znajdziesz później?
> - **2-5 tagów to złoty środek** — zbyt mało lub zbyt wiele jest złe
> - **Małe litery + myślniki** — `ci-cd`, nie `CI/CD`
> - **Przeglądać okresowo** — scalać duplikaty, usuwać nieużywane

## Następne kroki

- [Najlepsze praktyki pamięci](/docs/guides/memory-best-practices)
- [Wyszukiwanie FTS5](/docs/concepts/fts5-search)
- [Przepływ oparty na zadaniach](/docs/llm-cookbook/task-driven-workflow)