{"title":"Quick Start para agentes LLM","slug":"quick-start-llm","category":"getting-started","summary":"Em 3 chamadas de API: recupere todas as memórias, armazene uma nova, busque. O workflow essencial de LLM.","audience":["llm"],"tags":["llm","agent","quickstart","memory"],"difficulty":"beginner","updated":"2026-06-27","word_count":376,"read_minutes":2,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)\nALWAYS call /memory/recall at the start of every session.\nWichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nFTS5 search: multiple words = AND, \"phrases\" in quotes, prefix* for prefix search\n","lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Quick Start para agentes LLM\n\nVocê perde toda a memória entre sessões. O Synapse é seu cérebro externo. Este\nguia mostra as três chamadas de API essenciais que todo agente LLM precisa\nconhecer.\n\n> [!CRITICAL]\n> Chame `GET /memory/recall` no INÍCIO de CADA sessão.\n> Sem essa chamada, você não tem memória de quem é o usuário, do que prometeu\n> ou no que estava trabalhando da última vez.\n\n## Passo 1: recuperar todas as memórias (SEMPRE PRIMEIRO)\n\n```\nGET /memory/recall\nAuthorization: Bearer YOUR_MIND_KEY\n```\n\nRetorna um resumo estruturado em texto puro de todas as memórias armazenadas.\nFaça parse disso para reconstruir seu modelo mental do usuário, seus projetos e\ninterações passadas.\n\nExemplo de resposta:\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH)\n communication_style\n Prefers concise technical responses, no fluff\n Tags: communication, preference\n\n[003] project (HIGH)\n project_synapse\n Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.\n Tags: synapse, deployment\n ...\n```\n\n## Passo 2: armazenar uma nova memória\n\nQuando você aprender algo que vale a pena lembrar:\n\n```\nPOST /memory\nAuthorization: Bearer YOUR_MIND_KEY\nContent-Type: application/json\n\n{\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"The user's name is Michael Schäfer\",\n \"tags\": [\"person\", \"identity\"],\n \"priority\": \"critical\"\n}\n```\n\n**Categorias:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`\n\n**Prioridades:** `low`, `normal`, `high`, `critical`\n\n> [!TIP]\n> Sempre inclua um campo `key` — um identificador curto para a memória. Isso\n> permite atualizar a mesma memória depois refazendo POST com a mesma key.\n\n## Passo 3: buscar uma memória específica\n\n```\nGET /memory/search?q=Docker+Swarm\nAuthorization: Bearer YOUR_MIND_KEY\n```\n\n> [!TIP]\n> Sintaxe FTS5: múltiplas palavras = busca AND. Frases em aspas: `\"docker swarm\"`.\n> Busca por prefixo: `docker*`. Booleano: `docker OR kubernetes`.\n\n## Ferramentas abertas (sem cabeçalhos de auth)\n\nSe sua ferramenta só consegue abrir URLs (sem cabeçalhos personalizados), use o\nparâmetro `?key=`:\n\n```\nGET /memory/recall?key=YOUR_MIND_KEY\nPOST /memory?key=YOUR_MIND_KEY (+ JSON body)\nGET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff\n```\n\n> [!WARNING]\n> `?key=` é limitado a 60 requisições/minuto. O cabeçalho Bearer não tem limite\n> de taxa. Use o cabeçalho Bearer sempre que possível.\n\n## Workflow completo de sessão\n\n1. **Início da sessão:** `GET /memory/recall` — carregar todas as memórias\n2. **Durante o trabalho:** `GET /memory/search?q=...` — encontrar fatos específicos\n3. **Em nova informação:** `POST /memory` — armazenar (com category, key, tags, priority)\n4. **Periodicamente:** `GET /chat/poll` — verificar mensagens humanas\n5. **Fim da sessão:** Armazenar quaisquer aprendizados finais via `POST /memory`\n\n## Padrões comuns\n\n### Atualizar uma memória existente\n\nFaça POST `/memory` com a mesma `category` e `key` — a memória existente é\natualizada, não duplicada.\n\n### Armazenar status de projeto\n\n```json\n{\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"status\"],\n \"priority\": \"high\"\n}\n```\n\n### Registrar um erro (para não repeti-lo)\n\n```json\n{\n \"category\": \"mistake\",\n \"key\": \"mistake_npm_version_bump\",\n \"content\": \"Always bump package.json version after changes — npm publish fails otherwise.\",\n \"tags\": [\"npm\", \"ci\", \"deployment\"],\n \"priority\": \"high\"\n}\n```\n\n### Verificar mensagens humanas\n\n```\nGET /chat/poll\nAuthorization: Bearer YOUR_MIND_KEY\n```\n\nRetorna mensagens não lidas do humano. Responda com:\n\n```\nPOST /chat/reply\nAuthorization: Bearer YOUR_MIND_KEY\nContent-Type: application/json\n\n{\"content\": \"Got it! Working on it now.\"}\n```\n\n## Próximos passos\n\n- [Autenticação](/docs/getting-started/authentication) — Mind Key vs JWT\n- [Referência da API de Memória](/docs/api/memory) — todos os 22 endpoints de memória\n- [API de Chat](/docs/api/chat) — comunicação assíncrona com humanos\n- [Cookbook de LLM](/docs/llm-cookbook/session-start-pattern) — padrões práticos\n","content_html":"

Quick Start para agentes LLM

\n

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

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

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

\n
GET /memory/recall\nAuthorization: Bearer YOUR_MIND_KEY

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

\n

Exemplo de resposta:

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH)\n  communication_style\n  Prefers concise technical responses, no fluff\n  Tags: communication, preference\n\n[003] project (HIGH)\n  project_synapse\n  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.\n  Tags: synapse, deployment\n  ...

Passo 2: armazenar uma nova memória

\n

Quando você aprender algo que vale a pena lembrar:

\n
POST /memory\nAuthorization: Bearer YOUR_MIND_KEY\nContent-Type: application/json\n\n{\n  "category": "fact",\n  "key": "user_name",\n  "content": "The user's name is Michael Schäfer",\n  "tags": ["person", "identity"],\n  "priority": "critical"\n}

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

\n

Prioridades: low, normal, high, critical

\n
Sempre inclua um campo `key` — um identificador curto para a memória. Isso\npermite atualizar a mesma memória depois refazendo POST com a mesma key.

Passo 3: buscar uma memória específica

\n
GET /memory/search?q=Docker+Swarm\nAuthorization: Bearer YOUR_MIND_KEY
Sintaxe FTS5: múltiplas palavras = busca AND. Frases em aspas: `\"docker swarm\"`.\nBusca por prefixo: `docker*`. Booleano: `docker OR kubernetes`.

Ferramentas abertas (sem cabeçalhos de auth)

\n

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

\n
GET /memory/recall?key=YOUR_MIND_KEY\nPOST /memory?key=YOUR_MIND_KEY (+ JSON body)\nGET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
`?key=` é limitado a 60 requisições/minuto. O cabeçalho Bearer não tem limite\nde taxa. Use o cabeçalho Bearer sempre que possível.

Workflow completo de sessão

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

Padrões comuns

\n

Atualizar uma memória existente

\n

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

\n

Armazenar status de projeto

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

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

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

Verificar mensagens humanas

\n
GET /chat/poll\nAuthorization: Bearer YOUR_MIND_KEY

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

\n
POST /chat/reply\nAuthorization: Bearer YOUR_MIND_KEY\nContent-Type: application/json\n\n{"content": "Got it! Working on it now."}

Próximos passos

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