Il modello di memoria

Il modello di memoria di Synapse è progettato per agenti LLM — sufficientemente strutturato per richiamo affidabile, sufficientemente flessibile per qualsiasi dominio.

Anatomia di 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..."
}

Campi

Categorie

Otto categorie coprono i casi d'uso comuni degli agenti LLM:

Chiavi: identificatori stabili

Il campo key è critico — è come aggiorna le memorie senza creare duplicati.

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

Regole delle chiavi:

• Devono essere uniche all'interno di (category, mind)
• Usi snake_case
• Prefissi con categoria per chiarezza: preference_communication, mistake_npm_version
• Le mantenga stabili — non cambi le chiavi dopo la creazione

Tag: per la ricerca

I tag abilitano filtraggio e ricerca veloce:

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

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

Best practice per i tag:

• 2-5 tag per memoria (non esageri)
• Minuscolo per consistenza
• Usi nomi di progetto, argomenti, tecnologie
• I tag sono case-insensitive

Livelli di priorità

/memory/recall ordina per priorità (critical prima), poi per recency.

Sorgente: user vs agent

Le memorie sono contrassegnate con source:

• user — salvate da un umano (tramite JWT o UI umana)
• agent — salvate da un agente LLM (tramite Mind Key)

Questo influenza:

• Verifica: le memorie user sono auto-verificate, quelle agent no
• Confidenza: user predefinito a 1.0, agent a 0.7
• Richiamo: /memory/recall contrassegna le memorie non verificate con "(unverified)"

Verifica

Il flag verified indica che un umano ha confermato la memoria:

• memorie user: auto-verificate (true)
• memorie agent: non verificate per default (false)

Verifichi le memorie tramite:

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

Confidenza

Il campo confidence (0.0 a 1.0) indica quanto è affidabile la memoria:

• 1.0 — dichiarata direttamente dall'utente
• 0.7 — dedotta dall'agente
• 0.5 — incerta, necessita verifica
• 0.0 — esplicitamente dubitata

Imposti la confidenza durante la memorizzazione:

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

Scadenza

Imposti expires_at per memorie time-sensitive:

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

Le memorie scadute non vengono restituite da /memory/recall (ma esistono ancora nel DB). Usi /memory/expiring?within=7d per vedere le memorie in scadenza prossima.

Ciclo di vita della memoria

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

Comportamento di richiamo

GET /memory/recall restituisce un riassunto in testo semplice ottimizzato per il contesto 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

...

• Ordinate per priorità (critical → low), poi per recency
• Le memorie non verificate sono contrassegnate con [unverified]
• Tag inclusi per contesto
• Testo semplice (nessun parsing JSON necessario)

Prossimi passi

• Memory API
• Best practice per la memoria
• Ricerca FTS5