# Quick Start para agentes LLM

Você perde toda a memória entre sessões. O Synapse é seu cérebro externo. Este
guia mostra as três chamadas de API essenciais que todo agente LLM precisa
conhecer.

> [!CRITICAL]
> Chame `GET /memory/recall` no INÍCIO de CADA sessão.
> Sem essa chamada, você não tem memória de quem é o usuário, do que prometeu
> ou no que estava trabalhando da última vez.

## Passo 1: recuperar todas as memórias (SEMPRE PRIMEIRO)

```
GET /memory/recall
Authorization: Bearer YOUR_MIND_KEY
```

Retorna um resumo estruturado em texto puro de todas as memórias armazenadas.
Faça parse disso para reconstruir seu modelo mental do usuário, seus projetos e
interações passadas.

Exemplo de resposta:

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

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

[002] preference (HIGH)
  communication_style
  Prefers concise technical responses, no fluff
  Tags: communication, preference

[003] project (HIGH)
  project_synapse
  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.
  Tags: synapse, deployment
  ...
```

## Passo 2: armazenar uma nova memória

Quando você aprender algo que vale a pena lembrar:

```
POST /memory
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{
  "category": "fact",
  "key": "user_name",
  "content": "The user's name is Michael Schäfer",
  "tags": ["person", "identity"],
  "priority": "critical"
}
```

**Categorias:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`

**Prioridades:** `low`, `normal`, `high`, `critical`

> [!TIP]
> Sempre inclua um campo `key` — um identificador curto para a memória. Isso
> permite atualizar a mesma memória depois refazendo POST com a mesma key.

## Passo 3: buscar uma memória específica

```
GET /memory/search?q=Docker+Swarm
Authorization: Bearer YOUR_MIND_KEY
```

> [!TIP]
> Sintaxe FTS5: múltiplas palavras = busca AND. Frases em aspas: `"docker swarm"`.
> Busca por prefixo: `docker*`. Booleano: `docker OR kubernetes`.

## Ferramentas abertas (sem cabeçalhos de auth)

Se sua ferramenta só consegue abrir URLs (sem cabeçalhos personalizados), use o
parâmetro `?key=`:

```
GET /memory/recall?key=YOUR_MIND_KEY
POST /memory?key=YOUR_MIND_KEY (+ JSON body)
GET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
```

> [!WARNING]
> `?key=` é limitado a 60 requisições/minuto. O cabeçalho Bearer não tem limite
> de taxa. Use o cabeçalho Bearer sempre que possível.

## Workflow completo de sessão

1. **Início da sessão:** `GET /memory/recall` — carregar todas as memórias
2. **Durante o trabalho:** `GET /memory/search?q=...` — encontrar fatos específicos
3. **Em nova informação:** `POST /memory` — armazenar (com category, key, tags, priority)
4. **Periodicamente:** `GET /chat/poll` — verificar mensagens humanas
5. **Fim da sessão:** Armazenar quaisquer aprendizados finais via `POST /memory`

## Padrões comuns

### Atualizar uma memória existente

Faça POST `/memory` com a mesma `category` e `key` — a memória existente é
atualizada, não duplicada.

### Armazenar status de projeto

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.",
  "tags": ["synapse", "deployment", "status"],
  "priority": "high"
}
```

### Registrar um erro (para não repeti-lo)

```json
{
  "category": "mistake",
  "key": "mistake_npm_version_bump",
  "content": "Always bump package.json version after changes — npm publish fails otherwise.",
  "tags": ["npm", "ci", "deployment"],
  "priority": "high"
}
```

### Verificar mensagens humanas

```
GET /chat/poll
Authorization: Bearer YOUR_MIND_KEY
```

Retorna mensagens não lidas do humano. Responda com:

```
POST /chat/reply
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{"content": "Got it! Working on it now."}
```

## Próximos passos

- [Autenticação](/docs/getting-started/authentication) — Mind Key vs JWT
- [Referência da API de Memória](/docs/api/memory) — todos os 22 endpoints de memória
- [API de Chat](/docs/api/chat) — comunicação assíncrona com humanos
- [Cookbook de LLM](/docs/llm-cookbook/session-start-pattern) — padrões práticos