From 8c01daba185d0e18df083eb46b88efeabb801463 Mon Sep 17 00:00:00 2001 From: Gustavo Date: Tue, 11 Aug 2026 10:31:02 -0300 Subject: [PATCH] =?UTF-8?q?Plano:=20mem=C3=B3ria=20da=20sess=C3=A3o=20via?= =?UTF-8?q?=20Postgres=20Chat=20Memory=20(Z-PRO)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 4 tasks: verificar estrutura atual, trocar o node numa operação atômica (add + connect + remove, mesma lição da implementação anterior sobre nós desconectados), testar persistência real de contexto entre duas execuções separadas do workflow, atualizar runbook + commit. Co-Authored-By: Claude Sonnet 5 --- .../2026-08-11-memoria-sessao-postgres.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-11-memoria-sessao-postgres.md diff --git a/docs/superpowers/plans/2026-08-11-memoria-sessao-postgres.md b/docs/superpowers/plans/2026-08-11-memoria-sessao-postgres.md new file mode 100644 index 0000000..4fd8c98 --- /dev/null +++ b/docs/superpowers/plans/2026-08-11-memoria-sessao-postgres.md @@ -0,0 +1,161 @@ +# 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 " +``` + +--- + +## 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.