El modelo de memoria

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

Anatomía de una memoria

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

Campos

Categorías

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

Claves: identificadores estables

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

# First store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

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

Reglas de key:

• Debe ser única dentro de (categoría, mind)
• Use snake_case
• Prefije con la categoría para claridad: preference_communication, mistake_npm_version
• Manténgala estable — no cambie las keys tras la creación

Etiquetas: para búsqueda

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

# Find all memories with tag "docker"
GET /memory/by-tag?tag=docker

# FTS5 search within tagged subset
GET /memory/search?q=swarm&tag=docker

Mejores prácticas de etiquetado:

• 2-5 etiquetas por memoria (no etiquete en exceso)
• Minúsculas para consistencia
• Use nombres de proyecto, temas, tecnologías
• Las etiquetas son insensibles a mayúsculas/minúsculas

Niveles de prioridad

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

Origen: usuario vs agente

Las memorias se etiquetan con source:

• user — almacenada por un humano (vía JWT o interfaz humana)
• agent — almacenada por un agente LLM (vía Mind Key)

Esto afecta:

• Verificación: las memorias user se auto-verifican, las agent no
• Confianza: user por defecto a 1.0, agent a 0.7
• Recall: /memory/recall marca las memorias no verificadas con "(unverified)"

Verificación

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

• memorias user: auto-verificadas (true)
• memorias agent: por defecto no verificadas (false)

Verifique memorias vía:

curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"

Confianza

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

• 1.0 — declarada directamente por el usuario
• 0.7 — inferida por el agente
• 0.5 — incierta, necesita verificación
• 0.0 — explícitamente dudosa

Establezca la confianza al almacenar:

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

Expiración

Establezca expires_at para memorias sensibles al tiempo:

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

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

Ciclo de vida de una memoria

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

Comportamiento de recall

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

Mind: Michael's Mind
Memories: 12 total (10 verified, 2 unverified)

[001] identity (CRITICAL) [verified]
  user_name
  Michael Schäfer
  Tags: person, identity

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...

• Ordenado por prioridad (critical → low), luego por recencia
• Las memorias no verificadas se marcan con [unverified]
• Etiquetas incluidas para contexto
• Texto plano (no se necesita parsing JSON)

Próximos pasos

• API de Memory
• Mejores prácticas de memoria
• Búsqueda FTS5