Plano: memória da sessão via Postgres Chat Memory (Z-PRO)
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 <noreply@anthropic.com>
This commit is contained in:
Gustavo
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
6d12c2206a
commit
8c01daba18
@@ -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 <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.
|
||||
Reference in New Issue
Block a user