# O modelo de memória O modelo de memória do Synapse é projetado para agentes LLM — estruturado o suficiente para recall confiável, flexível o suficiente para qualquer domínio. ## Anatomia de uma memória ```json { "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 | Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | `id` | string | auto | ID único (mem_xxx) | | `category` | enum | ✅ | Uma das 8 categorias | | `key` | string | ✅ | Identificador estável (usado para updates) | | `content` | string | ✅ | O conteúdo da memória (qualquer texto) | | `tags` | string[] | – | Para busca e filtragem | | `priority` | enum | – | low, normal, high, critical (padrão: normal) | | `source` | enum | auto | user, agent (quem armazenou) | | `verified` | bool | auto | Um humano verificou isso? | | `confidence` | float | – | 0.0 a 1.0 (padrão: 1.0 para user, 0.7 para agent) | | `expires_at` | timestamp | – | Quando esquecer esta memória | | `mind_id` | string | auto | Qual mind é dono disso | | `created_at` | timestamp | auto | Quando foi armazenada | | `updated_at` | timestamp | auto | Última modificação | ## Categorias Oito categorias cobrem os casos de uso comuns de agentes LLM: | Categoria | Finalidade | Exemplo de conteúdo | |-----------|------------|---------------------| | `identity` | Quem é o usuário | "User is Michael Schäfer, software engineer in Berlin" | | `preference` | Preferências do usuário | "Prefers concise technical responses" | | `fact` | Fatos verificáveis | "Office is in Berlin, timezone Europe/Berlin" | | `project` | Status de projeto | "Synapse v1.5.0 deployed, working on v1.6.0 docs" | | `skill` | Habilidades do usuário | "Advanced Python, 10+ years" | | `mistake` | Erros passados | "Forgot to bump npm version — CI failed" | | `context` | Contexto de sessão | "Currently reviewing PR #42" | | `note` | Notas diversas | "Try Redis for caching next sprint" | ## Keys: identificadores estáveis O campo `key` é crítico — é como você atualiza memórias sem criar duplicatas. ```python # 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") ``` **Regras de key:** - Deve ser única dentro de (category, mind) - Use `snake_case` - Prefixe com a categoria para clareza: `preference_communication`, `mistake_npm_version` - Mantenha estável — não mude keys após a criação ## Tags: para busca Tags permitem filtragem e busca rápidas: ```bash # Find all memories with tag "docker" GET /memory/by-tag?tag=docker # FTS5 search within tagged subset GET /memory/search?q=swarm&tag=docker ``` **Melhores práticas de tags:** - 2-5 tags por memória (não exagere) - Minúsculas para consistência - Use nomes de projeto, tópicos, tecnologias - Tags são case-insensitive ## Níveis de prioridade | Prioridade | Quando usar | Comportamento de recall | |------------|-------------|-------------------------| | `critical` | Identidade, jurídico, irreversível | Sempre no topo do recall | | `high` | Projetos ativos, preferências-chave | Em destaque no recall | | `normal` | Maioria das memórias (padrão) | Ordem padrão de recall | | `low` | Efêmero, bom saber | Pode ser resumido | `/memory/recall` ordena por prioridade (critical primeiro), depois por recenticidade. ## Source: User vs Agent Memórias são marcadas com `source`: - `user` — armazenada por um humano (via JWT ou interface humana) - `agent` — armazenada por um agente LLM (via Mind Key) Isso afeta: - **Verificação:** memórias `user` são auto-verificadas, memórias `agent` não - **Confiança:** `user` padrão 1.0, `agent` padrão 0.7 - **Recall:** `/memory/recall` marca memórias não verificadas com "(unverified)" > [!NOTE] > Trate memórias de source `agent` com ceticismo apropriado. Elas podem ser > inferidas ou presumidas em vez de diretamente declaradas pelo usuário. ## Verificação O flag `verified` indica que um humano confirmou a memória: - Memórias `user`: auto-verificadas (`true`) - Memórias `agent`: padrão não verificadas (`false`) Verifique memórias via: ```bash curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \ -H "Authorization: Bearer YOUR_JWT" ``` > [!NOTE] > Verificação requer JWT (auth humana), não Mind Key (auth de agente). Isso > garante que apenas humanos possam marcar memórias como verificadas. ## Confiança O campo `confidence` (0.0 a 1.0) indica quão confiável é a memória: - 1.0 — diretamente declarada pelo usuário - 0.7 — inferida pelo agente - 0.5 — incerta, precisa verificação - 0.0 — explicitamente duvidosa Defina a confiança ao armazenar: ```json { "category": "preference", "key": "prefers_dark_mode", "content": "User seems to prefer dark mode (based on their IDE screenshots)", "confidence": 0.5, "source": "agent" } ``` ## Expiração Defina `expires_at` para memórias sensíveis ao tempo: ```json { "category": "context", "key": "current_meeting_topic", "content": "Discussing Q3 roadmap", "expires_at": "2026-06-28T00:00:00Z" } ``` Memórias expiradas não são retornadas por `/memory/recall` (mas ainda existem no DB). Use `/memory/expiring?within=7d` para ver memórias expirando em breve. ## Ciclo de vida da memória ``` ┌─────────────────┐ │ Create │ │ POST /memory │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Active │ ◀──── PUT /memory/:id (update) │ (in recall) │ └────────┬────────┘ │ ┌────────────┼────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Expired │ │ Verified │ │ Deleted │ │ (in DB) │ │ (flag) │ │ (gone) │ └──────────┘ └──────────┘ └──────────┘ ``` ## Comportamento de recall `GET /memory/recall` retorna um resumo em texto puro otimizado para contexto de 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 prioridade (critical → low), depois por recenticidade - Memórias não verificadas marcadas com `[unverified]` - Tags incluídas para contexto - Texto puro (sem necessidade de parsing JSON) ## Próximos passos - [API de Memória](/docs/api/memory) - [Melhores práticas de memória](/docs/guides/memory-best-practices) - [Busca FTS5](/docs/concepts/fts5-search)