# Mejores prácticas de memoria

La forma en que estructure las memorias determina cuán útiles son. Esta guía
cubre patrones para categorizar, etiquetar y priorizar memorias para que el LLM
pueda recuperar la información correcta en el momento adecuado.

## Categorías: elija la más específica

| Categoría | Usar para | Ejemplo |
|----------|---------|---------|
| `identity` | Nombre, rol, info de contacto | `"user_name": "Michael Schäfer"` |
| `preference` | Gustos, disgustos, estilo de trabajo | `"communication": "Prefers concise responses"` |
| `fact` | Hechos verificables | `"office_location": "Berlin, Germany"` |
| `project` | Estado del proyecto, decisiones | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Habilidades del usuario | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Errores pasados a evitar | `"mistake_npm_version": "Always bump version"` |
| `context` | Contexto relevante para la sesión | `"current_focus": "Working on docs system"` |
| `note` | Notas varias | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> En caso de duda, use `fact` para información verificable y `note` para todo
> lo demás. No sobrecategorice — mejor un `fact` claro que un `context`
> confuso.

## Claves: identificadores significativos

El campo `key` es el identificador de la memoria. Use claves significativas y
estables:

**Buenas claves:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Malas claves:**
- `mem_001` (no significativa)
- `temp` (no descriptiva)
- `2026-06-27-note` (la fecha no ayuda al recall)

### Convenciones de nomenclatura de claves

- `snake_case` (minúsculas con guiones bajos)
- Prefije con la categoría: `preference_*`, `project_*`, `mistake_*`
- Use sustantivos descriptivos, no verbos
- Mantenga por debajo de 50 caracteres

## Etiquetas: para búsqueda y filtrado

Las etiquetas permiten filtrado y búsqueda rápida. Añada 2-5 etiquetas por
memoria:

```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"]
}
```

### Patrones de etiquetado

- **Nombres de proyecto**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Temas**: `deployment`, `ci`, `database`, `auth`
- **Estado**: `active`, `completed`, `blocked`
- **Indicadores de prioridad**: `urgent`, `long-term`

> [!NOTE]
> Las etiquetas son insensibles a mayúsculas/minúsculas. Use minúsculas para
> consistencia.

## Prioridades: sea realista

| Prioridad | Usar para | % de memorias |
|----------|---------|---------------|
| `critical` | Identidad del usuario, info legal, decisiones irreversibles | ~5% |
| `high` | Proyectos activos, preferencias importantes | ~20% |
| `normal` | La mayoría de hechos, notas, contexto | ~65% |
| `low` | Efímera, bueno saberlo | ~10% |

> [!WARNING]
> No marque todo como `critical`. Si todo es crítico, nada lo es. Reserve
> `critical` para cosas que causarían un daño real si se olvidan.

## Cuándo almacenar y cuándo no

### Almacene siempre

- Identidad del usuario (nombre, email, rol)
- Preferencias a largo plazo
- Decisiones del proyecto y su justificación
- Errores pasados y lecciones aprendidas
- Compromisos adquiridos con el usuario

### No almacene

- Estado transitorio (use variables en su lugar)
- Historial de conversación literal (lo gestiona el sistema de chat)
- Datos sensibles (contraseñas, API keys)
- Hechos fácilmente derivables (fecha actual, contenidos de archivos)
- Contexto efímero (use la categoría `context` con prioridad baja)

## Actualizar memorias

POST `/memory` con la misma `category` + `key` actualiza la memoria existente:

```python
# Initial store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Later: update with same key
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> Use claves estables para poder actualizar sin crear duplicados. El LLM debe
> volver a hacer POST con la misma clave a medida que la información cambia, no
> crear nuevas memorias.

## Ciclo de vida de la memoria

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

- **Create**: POST /memory con contexto completo
- **Active**: Recall frecuente, actualizar según sea necesario
- **Stale**: Aún relevante pero no usado activamente (¿bajar prioridad?)
- **Archive**: Establecer prioridad a `low`, conservar como referencia histórica
- **Delete**: DELETE /memory/:id cuando ya no sea relevante

### Limpieza periódica

```python
# Find memories not updated in 90 days
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):
        # Either delete or lower priority
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Patrón: herencia de memoria

Para contexto jerárquico (proyecto → subproyecto → tarea):

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

# Sub-project (tags link to parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Specific task (tags link to sub-project)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

El LLM puede entonces buscar `q=synapse+docs` para encontrar todas las memorias
relacionadas.

## Patrón: log de decisiones

Almacene decisiones con su justificación para que el LLM no las vuelva a
cuestionar:

```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")
```

## Patrón: evitar errores

Almacene errores con instrucciones específicas de prevención:

```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")
```

## Antipatrones a evitar

> [!WARNING]
> - **Almacenar logs de conversación** — lo gestiona el sistema de chat
> - **Almacenar archivos completos** — use script store o almacenamiento externo
> - **Almacenar estado efímero** — use variables
> - **Almacenar secretos** — use variables de entorno
> - **Duplicar memorias** — use claves estables
> - **Sobreetiquetar** — 2-5 etiquetas por memoria es lo ideal
> - **Todo es crítico** — sea realista con las prioridades

## Próximos pasos

- [API de Memory](/docs/api/memory)
- [Agente LLM persistente](/docs/guides/persistent-llm-agent)
- [Estrategia de etiquetado de memoria](/docs/llm-cookbook/memory-tagging-strategy)