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):

```json
{
  "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**

```bash
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.