# Najlepsze praktyki pamięci

Sposób ustrukturyzowania wspomnień determinuje ich użyteczność. Ten przewodnik
obejmuje wzorce kategoryzowania, tagowania i priorytetyzowania wspomnień, aby
LLM mógł przypomnieć właściwą informację we właściwym czasie.

## Kategorie: wybierać najbardziej konkretną

| Kategoria | Użyć dla | Przykład |
|----------|---------|---------|
| `identity` | Imię użytkownika, rola, dane kontaktowe | `"user_name": "Michael Schäfer"` |
| `preference` | Sympatie, antypatie, styl pracy | `"communication": "Prefers concise responses"` |
| `fact` | Weryfikowalne fakty | `"office_location": "Berlin, Germany"` |
| `project` | Status projektu, decyzje | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Umiejętności użytkownika | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Błędy z przeszłości do uniknięcia | `"mistake_npm_version": "Always bump version"` |
| `context` | Kontekst istotny dla sesji | `"current_focus": "Working on docs system"` |
| `note` | Różne notatki | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> W razie wątpliwości używać `fact` dla weryfikowalnych informacji i `note` dla
> reszty. Nie nadużywać kategoryzacji — lepszy jasny `fact` niż mylący `context`.

## Klucze: znaczące identyfikatory

Pole `key` jest identyfikatorem wspomnienia. Używać znaczących, stabilnych kluczy:

**Dobre klucze:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Złe klucze:**
- `mem_001` (nie znaczący)
- `temp` (nie opisowy)
- `2026-06-27-note` (data nie pomaga w recall)

### Konwencje nazewnictwa kluczy

- `snake_case` (małe litery z podkreśleniami)
- Prefiksować kategorią: `preference_*`, `project_*`, `mistake_*`
- Używać opisowych rzeczowników, nie czasowników
- Utrzymywać poniżej 50 znaków

## Tagi: do wyszukiwania i filtrowania

Tagi umożliwiają szybkie filtrowanie i wyszukiwanie. Dodać 2-5 tagów na
wspomnienie:

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",
  "tags": ["synapse", "deployment", "status", "v1.5.0"]
}
```

### Wzorce tagów

- **Nazwy projektów**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Tematy**: `deployment`, `ci`, `database`, `auth`
- **Status**: `active`, `completed`, `blocked`
- **Wskaźniki priorytetu**: `urgent`, `long-term`

> [!NOTE]
> Tagi są niewrażliwe na wielkość liter. Używać małych liter dla spójności.

## Priorytety: być realistycznym

| Priorytet | Użyć dla | % wspomnień |
|----------|---------|---------------|
| `critical` | Tożsamość użytkownika, informacje prawne, decyzje nieodwracalne | około 5% |
| `high` | Aktywne projekty, ważne preferencje | około 20% |
| `normal` | Większość faktów, notatek, kontekstu | około 65% |
| `low` | Efemeryczne, warto wiedzieć | około 10% |

> [!WARNING]
> Nie oznaczać wszystkiego jako `critical`. Jeśli wszystko jest krytyczne, nic
> nie jest. Zarezerwować `critical` dla rzeczy, których zapomnienie wyrządziłoby
> realną szkodę.

## Kiedy zapisywać, a kiedy nie

### Zawsze zapisywać

- Tożsamość użytkownika (imię, e-mail, rola)
- Długoterminowe preferencje
- Decyzje projektowe i ich uzasadnienie
- Przeszłe błędy i wyciągnięte lekcje
- Zobowiązania względem użytkownika

### Nie zapisywać

- Stan przejściowy (użyć zmiennych)
- Historię konwersacji dosłownie (system czatu to obsługuje)
- Dane wrażliwe (hasła, klucze API)
- Faktory łatwo wyprowadzalne (aktualna data, zawartość plików)
- Kontekst efemeryczny (użyć kategorii `context` z niskim priorytetem)

## Aktualizacja wspomnień

POST `/memory` z tym samym `category` + `key` aktualizuje istniejące wspomnienie:

```python
# Początkowy zapis
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Później: aktualizacja tym samym kluczem
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> Używać stabilnych kluczy, aby aktualizować bez tworzenia duplikatów. LLM
> powinien ponownie POSTować ten sam klucz przy zmianie informacji, a nie
> tworzyć nowe wspomnienia.

## Cykl życia wspomnienia

```
Create → Active → Stale → Archive → Delete
```

- **Create**: POST /memory z pełnym kontekstem
- **Active**: Częsty recall, aktualizacja w razie potrzeby
- **Stale**: Nadal istotne, ale nieaktywnie używane (obniżyć priorytet?)
- **Archive**: Ustawić priorytet na `low`, zachować dla odniesienia historycznego
- **Delete**: DELETE /memory/:id, gdy już nieistotne

### Okresowe czyszczenie

```python
# Znalezienie wspomnień nieaktualizowanych od 90 dni
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Albo usunąć, albo obniżyć priorytet
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Wzorzec: dziedziczenie pamięci

Dla hierarchicznego kontekstu (projekt → podprojekt → zadanie):

```python
# Projekt nadrzędny
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Podprojekt (tagi łączą z nadrzędnym)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Konkretne zadanie (tagi łączą z podprojektem)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

LLM może wtedy wyszukać `q=synapse+docs`, aby znaleźć wszystkie powiązane
wspomnienia.

## Wzorzec: dziennik decyzji

Zapisywać decyzje z uzasadnieniem, aby LLM nie kwestionował ich ponownie:

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## Wzorzec: unikanie błędów

Zapisywać błędy z konkretnymi instrukcjami unikania:

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## Antywzorce do unikania

> [!WARNING]
> - **Zapisywanie logów konwersacji** — system czatu to obsługuje
> - **Zapisywanie całych plików** — użyć magazynu skryptów lub zewnętrznego magazynu
> - **Zapisywanie stanu efemerycznego** — użyć zmiennych
> - **Zapisywanie sekretów** — użyć zmiennych środowiskowych
> - **Duplikowanie wspomnień** — używać stabilnych kluczy
> - **Nadmiarowe tagowanie** — 2-5 tagów na wspomnienie jest optymalne
> - **Wszystko jest krytyczne** — być realistycznym z priorytetami

## Następne kroki

- [Memory API](/docs/api/memory)
- [Trwały agent LLM](/docs/guides/persistent-llm-agent)
- [Strategia tagowania pamięci](/docs/llm-cookbook/memory-tagging-strategy)