{"title":"El modelo de memoria","slug":"memory-model","category":"concepts","summary":"Cómo se estructuran las memorias — categorías, claves, etiquetas, prioridades, fuentes, verificación.","audience":["human","llm"],"tags":["concept","memory","model","structure"],"difficulty":"intermediate","updated":"2026-06-27","word_count":770,"read_minutes":4,"lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# El modelo de memoria\n\nEl modelo de memoria de Synapse está diseñado para agentes LLM — lo\nsuficientemente estructurado para recall fiable, lo suficientemente flexible\npara cualquier dominio.\n\n## Anatomía de una memoria\n\n```json\n{\n \"id\": \"mem_abc123\",\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed on vps1. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"v1.5.0\"],\n \"priority\": \"high\",\n \"source\": \"agent\",\n \"verified\": false,\n \"confidence\": 0.85,\n \"expires_at\": null,\n \"mind_id\": \"m_xyz789\",\n \"created_at\": \"2026-06-27T...\",\n \"updated_at\": \"2026-06-27T...\"\n}\n```\n\n## Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|-------|------|----------|-------------|\n| `id` | string | auto | ID único (mem_xxx) |\n| `category` | enum | ✅ | Una de 8 categorías |\n| `key` | string | ✅ | Identificador estable (usado para actualizaciones) |\n| `content` | string | ✅ | El contenido de la memoria (cualquier texto) |\n| `tags` | string[] | – | Para búsqueda y filtrado |\n| `priority` | enum | – | low, normal, high, critical (predeterminado: normal) |\n| `source` | enum | auto | user, agent (quién la almacenó) |\n| `verified` | bool | auto | ¿La ha verificado un humano? |\n| `confidence` | float | – | 0.0 a 1.0 (predeterminado: 1.0 para user, 0.7 para agent) |\n| `expires_at` | timestamp | – | Cuándo olvidar esta memoria |\n| `mind_id` | string | auto | A qué mind pertenece |\n| `created_at` | timestamp | auto | Primera vez almacenada |\n| `updated_at` | timestamp | auto | Última modificación |\n\n## Categorías\n\nOcho categorías cubren los casos de uso comunes de agentes LLM:\n\n| Categoría | Propósito | Contenido de ejemplo |\n|----------|---------|-----------------|\n| `identity` | Quién es el usuario | \"User is Michael Schäfer, software engineer in Berlin\" |\n| `preference` | Preferencias del usuario | \"Prefers concise technical responses\" |\n| `fact` | Hechos verificables | \"Office is in Berlin, timezone Europe/Berlin\" |\n| `project` | Estado del proyecto | \"Synapse v1.5.0 deployed, working on v1.6.0 docs\" |\n| `skill` | Habilidades del usuario | \"Advanced Python, 10+ years\" |\n| `mistake` | Errores pasados | \"Forgot to bump npm version — CI failed\" |\n| `context` | Contexto de sesión | \"Currently reviewing PR #42\" |\n| `note` | Notas varias | \"Try Redis for caching next sprint\" |\n\n## Claves: identificadores estables\n\nEl campo `key` es crítico — es la forma de actualizar memorias sin crear\nduplicados.\n\n```python\n# First store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed\", priority=\"high\")\n```\n\n**Reglas de key:**\n\n- Debe ser única dentro de (categoría, mind)\n- Use `snake_case`\n- Prefije con la categoría para claridad: `preference_communication`, `mistake_npm_version`\n- Manténgala estable — no cambie las keys tras la creación\n\n## Etiquetas: para búsqueda\n\nLas etiquetas permiten filtrado y búsqueda rápida:\n\n```bash\n# Find all memories with tag \"docker\"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker\n```\n\n**Mejores prácticas de etiquetado:**\n\n- 2-5 etiquetas por memoria (no etiquete en exceso)\n- Minúsculas para consistencia\n- Use nombres de proyecto, temas, tecnologías\n- Las etiquetas son insensibles a mayúsculas/minúsculas\n\n## Niveles de prioridad\n\n| Prioridad | Cuándo usarla | Comportamiento de recall |\n|----------|-------------|-----------------|\n| `critical` | Identidad, legal, irreversible | Siempre al inicio del recall |\n| `high` | Proyectos activos, preferencias clave | Destacada en el recall |\n| `normal` | La mayoría de memorias (predeterminado) | Orden de recall estándar |\n| `low` | Efímera, bueno saberlo | Puede resumirse |\n\n`/memory/recall` ordena por prioridad (critical primero), luego por recencia.\n\n## Origen: usuario vs agente\n\nLas memorias se etiquetan con `source`:\n\n- `user` — almacenada por un humano (vía JWT o interfaz humana)\n- `agent` — almacenada por un agente LLM (vía Mind Key)\n\nEsto afecta:\n\n- **Verificación**: las memorias `user` se auto-verifican, las `agent` no\n- **Confianza**: `user` por defecto a 1.0, `agent` a 0.7\n- **Recall**: `/memory/recall` marca las memorias no verificadas con \"(unverified)\"\n\n> [!NOTE]\n> Trate las memorias con origen `agent` con el escepticismo apropiado. Pueden\n> estar inferidas o asumidas en lugar de haber sido declaradas directamente por\n> el usuario.\n\n## Verificación\n\nEl flag `verified` indica que un humano ha confirmado la memoria:\n\n- memorias `user`: auto-verificadas (`true`)\n- memorias `agent`: por defecto no verificadas (`false`)\n\nVerifique memorias vía:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n> [!NOTE]\n> La verificación requiere JWT (auth humana), no Mind Key (auth de agente).\n> Esto garantiza que solo los humanos puedan marcar memorias como verificadas.\n\n## Confianza\n\nEl campo `confidence` (0.0 a 1.0) indica cuán fiable es la memoria:\n\n- 1.0 — declarada directamente por el usuario\n- 0.7 — inferida por el agente\n- 0.5 — incierta, necesita verificación\n- 0.0 — explícitamente dudosa\n\nEstablezca la confianza al almacenar:\n\n```json\n{\n \"category\": \"preference\",\n \"key\": \"prefers_dark_mode\",\n \"content\": \"User seems to prefer dark mode (based on their IDE screenshots)\",\n \"confidence\": 0.5,\n \"source\": \"agent\"\n}\n```\n\n## Expiración\n\nEstablezca `expires_at` para memorias sensibles al tiempo:\n\n```json\n{\n \"category\": \"context\",\n \"key\": \"current_meeting_topic\",\n \"content\": \"Discussing Q3 roadmap\",\n \"expires_at\": \"2026-06-28T00:00:00Z\"\n}\n```\n\nLas memorias expiradas no se devuelven en `/memory/recall` (pero siguen\nexistentes en la BD). Use `/memory/expiring?within=7d` para ver memorias que\nexpiran pronto.\n\n## Ciclo de vida de una memoria\n\n```\n ┌─────────────────┐\n │ Create │\n │ POST /memory │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Active │ ◀──── PUT /memory/:id (update)\n │ (in recall) │\n └────────┬────────┘\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌──────────┐ ┌──────────┐ ┌──────────┐\n │ Expired │ │ Verified │ │ Deleted │\n │ (in DB) │ │ (flag) │ │ (gone) │\n └──────────┘ └──────────┘ └──────────┘\n```\n\n## Comportamiento de recall\n\n`GET /memory/recall` devuelve un resumen en texto plano optimizado para el\ncontexto del LLM:\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH) [verified]\n communication_style\n Prefers concise technical responses\n Tags: communication\n\n[003] project (HIGH) [unverified]\n synapse_status\n v1.5.0 deployed, working on v1.6.0 docs\n Tags: synapse, deployment\n\n...\n```\n\n- Ordenado por prioridad (critical → low), luego por recencia\n- Las memorias no verificadas se marcan con `[unverified]`\n- Etiquetas incluidas para contexto\n- Texto plano (no se necesita parsing JSON)\n\n## Próximos pasos\n\n- [API de Memory](/docs/api/memory)\n- [Mejores prácticas de memoria](/docs/guides/memory-best-practices)\n- [Búsqueda FTS5](/docs/concepts/fts5-search)\n","content_html":"

El modelo de memoria

\n

El modelo de memoria de Synapse está diseñado para agentes LLM — lo\nsuficientemente estructurado para recall fiable, lo suficientemente flexible\npara cualquier dominio.

\n

Anatomía de una memoria

\n
{\n  "id": "mem_abc123",\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed on vps1. CI green.",\n  "tags": ["synapse", "deployment", "v1.5.0"],\n  "priority": "high",\n  "source": "agent",\n  "verified": false,\n  "confidence": 0.85,\n  "expires_at": null,\n  "mind_id": "m_xyz789",\n  "created_at": "2026-06-27T...",\n  "updated_at": "2026-06-27T..."\n}

Campos

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CampoTipoObligatorioDescripción
idstringautoID único (mem_xxx)
categoryenum✅Una de 8 categorías
keystring✅Identificador estable (usado para actualizaciones)
contentstring✅El contenido de la memoria (cualquier texto)
tagsstring[]–Para búsqueda y filtrado
priorityenum–low, normal, high, critical (predeterminado: normal)
sourceenumautouser, agent (quién la almacenó)
verifiedboolauto¿La ha verificado un humano?
confidencefloat–0.0 a 1.0 (predeterminado: 1.0 para user, 0.7 para agent)
expires_attimestamp–Cuándo olvidar esta memoria
mind_idstringautoA qué mind pertenece
created_attimestampautoPrimera vez almacenada
updated_attimestampautoÚltima modificación
\n

Categorías

\n

Ocho categorías cubren los casos de uso comunes de agentes LLM:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CategoríaPropósitoContenido de ejemplo
identityQuién es el usuario"User is Michael Schäfer, software engineer in Berlin"
preferencePreferencias del usuario"Prefers concise technical responses"
factHechos verificables"Office is in Berlin, timezone Europe/Berlin"
projectEstado del proyecto"Synapse v1.5.0 deployed, working on v1.6.0 docs"
skillHabilidades del usuario"Advanced Python, 10+ years"
mistakeErrores pasados"Forgot to bump npm version — CI failed"
contextContexto de sesión"Currently reviewing PR #42"
noteNotas varias"Try Redis for caching next sprint"
\n

Claves: identificadores estables

\n

El campo key es crítico — es la forma de actualizar memorias sin crear\nduplicados.

\n
# First store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore("project", "project_synapse_status", "v1.5.0 deployed", priority="high")

Reglas de key:

\n\n

Etiquetas: para búsqueda

\n

Las etiquetas permiten filtrado y búsqueda rápida:

\n
# Find all memories with tag "docker"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker

Mejores prácticas de etiquetado:

\n\n

Niveles de prioridad

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PrioridadCuándo usarlaComportamiento de recall
criticalIdentidad, legal, irreversibleSiempre al inicio del recall
highProyectos activos, preferencias claveDestacada en el recall
normalLa mayoría de memorias (predeterminado)Orden de recall estándar
lowEfímera, bueno saberloPuede resumirse
\n

/memory/recall ordena por prioridad (critical primero), luego por recencia.

\n

Origen: usuario vs agente

\n

Las memorias se etiquetan con source:

\n\n

Esto afecta:

\n\n
Trate las memorias con origen `agent` con el escepticismo apropiado. Pueden\nestar inferidas o asumidas en lugar de haber sido declaradas directamente por\nel usuario.

Verificación

\n

El flag verified indica que un humano ha confirmado la memoria:

\n\n

Verifique memorias vía:

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"
La verificación requiere JWT (auth humana), no Mind Key (auth de agente).\nEsto garantiza que solo los humanos puedan marcar memorias como verificadas.

Confianza

\n

El campo confidence (0.0 a 1.0) indica cuán fiable es la memoria:

\n\n

Establezca la confianza al almacenar:

\n
{\n  "category": "preference",\n  "key": "prefers_dark_mode",\n  "content": "User seems to prefer dark mode (based on their IDE screenshots)",\n  "confidence": 0.5,\n  "source": "agent"\n}

Expiración

\n

Establezca expires_at para memorias sensibles al tiempo:

\n
{\n  "category": "context",\n  "key": "current_meeting_topic",\n  "content": "Discussing Q3 roadmap",\n  "expires_at": "2026-06-28T00:00:00Z"\n}

Las memorias expiradas no se devuelven en /memory/recall (pero siguen\nexistentes en la BD). Use /memory/expiring?within=7d para ver memorias que\nexpiran pronto.

\n

Ciclo de vida de una memoria

\n
                  ┌─────────────────┐\n                  │     Create      │\n                  │  POST /memory   │\n                  └────────┬────────┘\n                           │\n                           ▼\n                  ┌─────────────────┐\n                  │     Active      │ ◀──── PUT /memory/:id (update)\n                  │  (in recall)    │\n                  └────────┬────────┘\n                           │\n              ┌────────────┼────────────┐\n              │            │            │\n              ▼            ▼            ▼\n        ┌──────────┐ ┌──────────┐ ┌──────────┐\n        │ Expired  │ │ Verified │ │ Deleted  │\n        │ (in DB)  │ │ (flag)   │ │ (gone)   │\n        └──────────┘ └──────────┘ └──────────┘

Comportamiento de recall

\n

GET /memory/recall devuelve un resumen en texto plano optimizado para el\ncontexto del LLM:

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH) [verified]\n  communication_style\n  Prefers concise technical responses\n  Tags: communication\n\n[003] project (HIGH) [unverified]\n  synapse_status\n  v1.5.0 deployed, working on v1.6.0 docs\n  Tags: synapse, deployment\n\n...
\n

Próximos pasos

\n\n","urls":{"html":"/docs/concepts/memory-model","text":"/docs/concepts/memory-model?format=text","json":"/docs/concepts/memory-model?format=json","llm":"/docs/concepts/memory-model?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}