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ę:

# 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.

// 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?"

// 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

{ "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

{ "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:

{ "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

// 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

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

Znalezienie wszystkich błędów w domenie

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

Znalezienie aktywnej pracy

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

Znalezienie wspomnień o technologii

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

Utrzymanie tagów

Okresowy przegląd

# 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:

# 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

Następne kroki

• Najlepsze praktyki pamięci
• Wyszukiwanie FTS5
• Przepływ oparty na zadaniach