KLINGO-CLINICAL-SYSLIFE-GCHAT/docs/superpowers/plans/2026-08-11-memoria-sessao-postgres.md

Memória da Sessão via Postgres Chat Memory Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task (não subagent-driven-development — as tasks são chamadas de API do n8n, não commits de código; não há diff de git pra revisar por task). Steps use checkbox (- [ ]) syntax for tracking.

Goal: Trocar o node de memória do AI Agent no workflow Z-PRO em produção (memoryBufferWindow, em RAM) pelo node oficial Postgres Chat Memory, persistindo o histórico de conversa num Postgres.

Architecture: Troca de node na porta ai_memory do AI Agent — mesmos parâmetros de sessão (sessionKey, contextWindowLength), só muda o backend de armazenamento. Tabela n8n_chat_histories criada automaticamente pelo node.

Tech Stack: n8n (devn8n.gtigrupo.com.br), @n8n/n8n-nodes-langchain.memoryPostgresChat v1.4, workflow Agendamento - GChat - Z-PRO (clínica exemplo) (yG2mi6ECBpPv4Hmn, ativo em produção).

Global Constraints

• Mesma configuração de sessão do node atual: sessionKey: ={{ $json.sessionId }}, contextWindowLength: 20 — nenhum comportamento de sessão muda, só o armazenamento.
• Nenhuma credencial é criada automaticamente pela automação — pré-requisito manual do usuário.
• O workflow está ativo em produção — validar (n8n_validate_workflow) depois de cada mudança, testar antes de encerrar.
• Não há histórico a migrar (ver spec) — a troca do node é o suficiente, sem step de migração de dados.

Spec de referência: docs/superpowers/specs/2026-08-11-memoria-sessao-postgres-design.md

---

Pré-requisito (ação manual do usuário)

Criar no n8n uma Credential do tipo Postgres (Settings → Credentials → New → "Postgres"), com os dados de conexão do banco do Z-PRO dentro do container provisionado (host, porta, nome do banco, usuário, senha). Nomear como Postgres - Z-PRO clínica exemplo. Anotar o ID gerado — será necessário na Task 2.

---

Task 1: Verificar a estrutura atual antes de modificar

Interfaces:

• Consumes: workflow yG2mi6ECBpPv4Hmn (produção, ativo).

• Step 1: Ler a estrutura atual

n8n_get_workflow com {"id": "yG2mi6ECBpPv4Hmn", "mode": "structure"}. Confirmar que "Memória da Sessão" (memoryBufferWindow) ainda conecta via ai_memory (índice 0) em "AI Agent". Se a estrutura tiver mudado desde este plano ter sido escrito, ajustar os steps seguintes de acordo.

---

Task 2: Trocar o node de memória (operação atômica)

Interfaces:

• Consumes: ID da credencial Postgres do Pré-requisito.

• Produces: node "Memória da Sessão (Postgres)" conectado ao AI Agent; node "Memória da Sessão" (RAM) removido.

• Step 1: Adicionar o node novo, conectar, e remover o antigo — tudo numa chamada só

Fazer numa única chamada n8n_update_partial_workflow (o node antigo ficaria órfão se removido antes de conectar o novo, e o n8n rejeita salvar com nós desconectados — por isso tudo junto):

{
  "id": "yG2mi6ECBpPv4Hmn",
  "operations": [
    {
      "type": "addNode",
      "node": {
        "id": "memoria-sessao-postgres",
        "name": "Memória da Sessão (Postgres)",
        "type": "@n8n/n8n-nodes-langchain.memoryPostgresChat",
        "typeVersion": 1.4,
        "position": [640, -96],
        "parameters": {
          "sessionIdType": "customKey",
          "sessionKey": "={{ $json.sessionId }}",
          "tableName": "n8n_chat_histories",
          "contextWindowLength": 20
        },
        "credentials": {
          "postgres": { "id": "SUBSTITUIR_PELO_ID_DA_CREDENCIAL", "name": "Postgres - Z-PRO clínica exemplo" }
        }
      }
    },
    { "type": "addConnection", "source": "Memória da Sessão (Postgres)", "target": "AI Agent", "sourceOutput": "ai_memory", "targetIndex": 0 },
    { "type": "removeNode", "nodeName": "Memória da Sessão" }
  ]
}

Substitua "SUBSTITUIR_PELO_ID_DA_CREDENCIAL" pelo ID real da credencial criada no Pré-requisito (buscar via n8n_manage_credentials action: "list", procurando "Postgres - Z-PRO clínica exemplo").

• Step 2: Validar

n8n_validate_workflow com {"id": "yG2mi6ECBpPv4Hmn"}. Esperado: errorCount: 0, sem nós desconectados, sem referência ao node antigo.

---

Task 3: Teste real de ponta a ponta

Interfaces:

• Consumes: node trocado e validado da Task 2.

• Step 1: Conversa de teste com múltiplas mensagens — confirmar que o contexto persiste

Enviar ao webhook de produção duas mensagens em sequência, mesmo protocol (sessão nova, ex.: teste-memoria-postgres-01):

1. Primeira mensagem: informar um nome fictício (ex.: "Meu nome é Teste Postgres Memoria").
2. Segunda mensagem (mesmo protocolo): perguntar algo que só faz sentido se o agente lembrar da primeira (ex.: "qual nome você anotou?"). Confirmar que a resposta reflete o nome da primeira mensagem — prova que o histórico está sendo mantido entre as duas chamadas via Postgres (não via RAM, já que são duas execuções de workflow separadas).

• Step 2: Confirmar persistência direto no banco

Se houver acesso de consulta ao Postgres, rodar um SELECT na tabela n8n_chat_histories (criada automaticamente) e confirmar que as mensagens da conversa de teste do Step 1 estão lá, associadas ao sessionId usado (teste-memoria-postgres-01).

---

Task 4: Atualizar o runbook e commit

Interfaces:

• Consumes: resultado validado da Task 3.

• Step 1: Adicionar seção ao runbook

Adicionar uma seção nova em docs/n8n-agendamento-runbook.md (numerada na sequência, após a seção 15) documentando a troca: node antigo removido, node novo com Postgres, tabela n8n_chat_histories, e a nota de que não houve migração de histórico (nada a migrar). Incluir o padrão a replicar quando Klingo/SysLife/ClinicAll tiverem workflow de agente: um banco por cliente dentro do mesmo container Postgres, uma credencial por workflow.

• Step 2: Commit

cd "D:\PROJETOS\KLINGO-CLINICAL-SYSLIFE-GCHAT-AGENDAMENTO"
git add docs/n8n-agendamento-runbook.md
git commit -m "docs: registra troca da memória da sessão para Postgres (Z-PRO)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>"

---

Observação sobre execução

Mesmo padrão dos planos anteriores que mexem em produção real (ver o plano da configuração via Google Docs): validar depois de cada mudança, testar de ponta a ponta antes de encerrar. A Task 2 precisa ser feita como uma única chamada atômica (adicionar + conectar + remover) — tentar em passos separados falha a validação de nós desconectados do n8n no meio do caminho, exatamente como aconteceu na implementação da Task 2 do plano de configuração via Google Docs.