From 6d12c2206a06b713a393f546a035135b00c3aa0c Mon Sep 17 00:00:00 2001 From: Gustavo Date: Tue, 11 Aug 2026 10:29:40 -0300 Subject: [PATCH] =?UTF-8?q?Spec:=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 Troca o node de memória do AI Agent (Simple Memory, em RAM, não sobrevive a reinício do n8n) pelo node oficial Postgres Chat Memory, mesma configuração de sessão (sessionKey, contextWindowLength). Infraestrutura: um container Postgres com um banco por cliente/clínica, mesma filosofia de isolamento já usada nos outros parâmetros de configuração do projeto. Tabela criada automaticamente pelo node, sem setup manual de schema. Nada a migrar (histórico atual só existe em RAM). Co-Authored-By: Claude Sonnet 5 --- ...26-08-11-memoria-sessao-postgres-design.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-11-memoria-sessao-postgres-design.md diff --git a/docs/superpowers/specs/2026-08-11-memoria-sessao-postgres-design.md b/docs/superpowers/specs/2026-08-11-memoria-sessao-postgres-design.md new file mode 100644 index 0000000..2c074cf --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-memoria-sessao-postgres-design.md @@ -0,0 +1,84 @@ +# Design — Memória da Sessão via Postgres Chat Memory + +**Data:** 2026-08-11 +**Status:** Aprovado pelo usuário, aguardando plano de implementação. + +## Objetivo + +O node atual de memória do AI Agent (`Memória da Sessão`, tipo +`memoryBufferWindow`/"Simple Memory") guarda o histórico da conversa só +em RAM do processo do n8n. Isso tem duas limitações reais de produção: +não sobrevive a um reinício do n8n (deploy, crash, atualização) — a +conversa em andamento "esquece" tudo — e não funciona em setups com +múltiplos workers (queue mode), já que cada worker teria sua própria +memória isolada. Este design troca esse node pelo node oficial `Postgres +Chat Memory`, que persiste o histórico num banco Postgres. + +## Infraestrutura + +O usuário vai provisionar **um container Postgres**, com **um banco de +dados por cliente/clínica** dentro desse container — mesma filosofia de +isolamento por cliente já usada nos outros parâmetros de configuração +(`docId` do Google Doc, `baseUrl`/`apiId` dos MCP Servers). Isso significa +que cada workflow de agente terá sua própria Credential Postgres no n8n, +apontando pro mesmo host/porta do container mas pro banco específico +daquele cliente. + +## Escopo desta etapa + +Aplicado só ao Z-PRO (`Agendamento - GChat - Z-PRO (clínica exemplo)`, +`yG2mi6ECBpPv4Hmn`), único workflow de agente em produção real até +agora. Klingo/SysLife/ClinicAll ainda não têm workflow de agente — o +padrão fica pronto pra replicar quando esses forem criados. + +## Componentes + +### Troca de node (porta `ai_memory` do AI Agent) + +Sai: `Memória da Sessão` (`@n8n/n8n-nodes-langchain.memoryBufferWindow`). + +Entra: `Memória da Sessão (Postgres)` +(`@n8n/n8n-nodes-langchain.memoryPostgresChat`, v1.4), com: + +- `sessionIdType: customKey`, `sessionKey: ={{ $json.sessionId }}` — + idêntico ao node atual, mesma expressão, mesmo comportamento de + sessão por `protocol`/atendimento. +- `contextWindowLength: 20` — idêntico ao valor atual. +- `tableName: n8n_chat_histories` — nome padrão do node, **criado + automaticamente na primeira execução**, sem setup manual de schema. + Se outros clientes futuros usarem o mesmo Postgres (bancos separados + por cliente, ver "Infraestrutura"), cada banco terá sua própria + instância dessa tabela — sem risco de misturar histórico entre + clientes, já que são bancos fisicamente separados. +- Credential `postgres` — criada manualmente pelo usuário na UI do n8n + (mesmo padrão de todas as outras credenciais deste projeto), apontando + pro banco específico do Z-PRO dentro do container. + +### Migração de histórico + +**Não há nada a migrar.** O histórico atual vive só em RAM — ao trocar +o node, conversas em andamento simplesmente recomeçam do zero na +próxima mensagem. Não é uma perda de dado nova introduzida por esta +mudança: é exatamente o que já acontece hoje a cada reinício do n8n, +só que agora deixa de acontecer daqui pra frente. + +## Fora de escopo + +- Aplicar o mesmo padrão em Klingo/SysLife/ClinicAll — fica para quando + esses tiverem workflow de agente. +- Provisionar o container Postgres em si — infraestrutura de + responsabilidade do usuário, fora do escopo deste design (que cobre + só a integração no n8n). +- Qualquer política de retenção/limpeza de histórico antigo na tabela + `n8n_chat_histories` — não solicitado, YAGNI por enquanto. + +## Testes + +Sem framework automatizado (workflow n8n). Validação manual: enviar uma +conversa de teste com múltiplas mensagens (protocolo novo), confirmar +que o agente mantém contexto entre mensagens (ex.: lembra o nome já +informado). Confirmar na tabela `n8n_chat_histories` do Postgres que o +histórico foi persistido de fato (consulta direta ao banco). Se +possível, reiniciar o processo do n8n (ou simular) e confirmar que uma +conversa em andamento mantém o histórico depois do reinício — validação +do ganho real desta mudança.