n8n-nodes-tembory 1.1.30 → 1.1.32

package/README.md

@@ -2,14 +2,44 @@
 
 Node de memoria operacional da Tembory para agentes de IA no n8n.
 
-Versao atual: `1.1.2`.
+Versao atual: `1.1.32`.
 
-## 1.1.2
+## 1.1.32
 
-- Torna a entrada `LLM` obrigatoria no node.
-- Remove opcoes visiveis de vetor, grafo e configuracao legada da interface do node.
-- Forca o resumo SLM como parte do contrato de producao.
-- Mantem o registro de tools, inputs, outputs, status, action ledger, working memory e decision state por fluxo operacional.
+- Adiciona `Modo de Configuracao` com `Simples Recomendado` e `Avancado`.
+- O modo simples usa os defaults validados nos testes reais: contexto estruturado, resumo por contexto ativo, tool history/results/action ledger, backend persistente e diagnostico pesado desligado.
+- O modo avancado continua exibindo todas as opcoes existentes, sem remover nenhum controle.
+- Atualiza a expressao padrao de `Consulta` para ler tambem `$json.body.chatInput`.
+
+## 1.1.31
+
+- Adiciona `agentContextBudget` no payload visual do n8n com caracteres e tokens aproximados injetados no Agent.
+- Mostra `loadedSections` fora do bloco de diagnostico para facilitar debug humano.
+- Melhora o parsing de outputs comuns de tools do n8n, incluindo envelopes `json`, `data`, `body` e `result`.
+- Mantem `outputParsed`, `capturedAt`, `toolTimestamp`, `toolStatus`, conversa e save visual por execucao.
+
+## Contrato operacional atual
+
+O Tembory e memoria operacional generica. Ele nao decide regra de negocio, nao escolhe a tool pelo dominio do cliente e nao substitui o prompt do agente.
+
+O que ele deve guardar e devolver:
+
+- Mensagens recentes por `threadId` ou `sessionId`.
+- Tool calls genericas, independente do nome da tool.
+- Input enviado para a tool.
+- Output bruto retornado pela tool.
+- Output util em `outputParsed`, quando o formato permitir parsing seguro.
+- Status da tool.
+- `capturedAt`, que e quando o Tembory capturou o evento.
+- `toolTimestamp`, que e o timestamp retornado pela propria tool quando existir.
+- `actionLedger`, `workingMemory`, `decisionState`, `operationalState` e resumo ativo.
+
+O que ele nao deve fazer:
+
+- Inventar politica de tool.
+- Considerar uma acao lateral concluida sem tool bem sucedida no turno correto.
+- Transformar observacao ou inferencia em regra obrigatoria.
+- Esconder falha de save no payload visual.
 
 ## Visao geral
 
@@ -43,13 +73,64 @@ Use a credencial `Tembory API` com a API key gerada no SaaS. A API key identific
 
 O campo `Preset Operacional` preenche defaults de producao:
 
-- `Produção Rápida (Thread + SLM)`: padrao recomendado.
-- `Produção Balanceada`: mais contexto, ainda compacto.
-- `Produção Econômica`: reduz resultados e secoes para economizar tokens, mantendo SLM obrigatoria.
-- `Produção Nano/SLM`: otimizado para modelo pequeno.
-- `Diagnóstico Completo`: teste e auditoria.
+- `Producao Rapida (Thread + SLM)`: padrao recomendado para a maioria dos agentes.
+- `Producao Balanceada`: mais contexto, ainda compacto.
+- `Producao Economica`: reduz resultados e secoes para economizar tokens.
+- `Producao Nano/SLM`: otimizado para modelo pequeno.
+- `Diagnostico Completo`: teste e auditoria.
 - `Auditoria`: payload detalhado para depuracao.
 
+Recomendacao pratica:
+
+- Use `Modo Simples Recomendado` em producao normal.
+- Use `Producao Balanceada` quando o agente precisar comparar mais historico.
+- Use `Auditoria` ou `Diagnostico Completo` apenas enquanto estiver depurando.
+
+No modo simples, o node aplica automaticamente:
+
+- `Modo de Recuperacao`: operacional estruturado.
+- `Formato do Contexto`: producao estruturado.
+- `Preset Operacional`: producao rapida.
+- `Fonte do Resumo do SLM`: contexto ativo.
+- Tool history, resultados de tools, action ledger, working memory, decision state, operational state e memory compression ligados.
+- Persistencia no backend e active summary ligados.
+- Diagnostico pesado, scores, semantic fallback e tool facts desligados.
+- TTL de tool history em 36000 segundos.
+- Ultimas tools mantidas no contexto compacto: 50.
+
+## Uso com `$fromAI()`
+
+Em tools conectadas ao AI Agent, o n8n permite que o modelo preencha parametros dinamicamente com `$fromAI()`. Isso e responsabilidade do Agent e da tool do n8n. O Tembory apenas fornece contexto operacional para o Agent, incluindo conversa, tools anteriores, inputs, outputs e timestamps.
+
+Referencia oficial do n8n: https://docs.n8n.io/advanced-ai/examples/using-the-fromai-function/
+
+## Payload visual do n8n
+
+No output do node durante uma execucao, o Tembory mostra um resumo compacto para humano:
+
+- `memorySummary.intent`: classificacao operacional leve do turno.
+- `memorySummary.conversation`: contagem e ultimas mensagens.
+- `memorySummary.conversationTimeline`: timeline curta com timestamps.
+- `memorySummary.toolEvents`: ultimas tool calls com input, output, `outputParsed`, status e timestamps.
+- `memorySummary.lastSave`: ultimo save persistido.
+- `memorySummary.loadedSections`: quais blocos foram injetados no contexto do Agent.
+- `memorySummary.agentContextBudget`: tamanho aproximado do contexto enviado ao Agent.
+
+Exemplo de budget:
+
+```json
+{
+  "agentContextBudget": {
+    "messages": 1,
+    "chars": 4200,
+    "approxTokens": 1050,
+    "largestSections": [
+      { "section": "tools", "chars": 1600, "approxTokens": 400 }
+    ]
+  }
+}
+```
+
 ## Blocos de contexto
 
 Quando habilitados, o agente recebe:

package/dist/nodes/Tembory/TemboryMemory.node.js

@@ -1276,8 +1276,44 @@ const mergeRemoteThreadState = (store, key, state) => {
     if (typeof state.activeSummary === 'string' && state.activeSummary)
         store.activeSummary[key] = state.activeSummary;
 };
+const SIMPLE_MODE_OVERRIDES = {
+    operationPreset: 'productionFast',
+    summarySource: 'activeContext',
+    includeContextHeader: true,
+    compactStateSections: true,
+    includeSummary: true,
+    includeToolHistory: true,
+    includeToolResults: true,
+    includeProfileFacts: true,
+    includeOperationalState: true,
+    includeActionLedger: true,
+    includeWorkingMemory: true,
+    includeDecisionState: true,
+    includeMemoryCompression: true,
+    includeRecentMessages: true,
+    includeRecentHighlights: false,
+    includeEntityTimeline: false,
+    persistBackendMemories: true,
+    persistActiveSummary: true,
+    includeActiveSummary: true,
+    enableTransientSummaryCache: true,
+    includeScores: false,
+    includeDiagnostics: false,
+    persistToolFactsToTembory: false,
+    includeToolHistorySemanticFallback: false,
+    contextMaxChars: 10000,
+    toolHistoryLastN: 50,
+    toolHistoryTTLSeconds: 36000,
+    recentMessagesLastN: 50,
+    connectedModelSummaryInputMaxChars: 4200,
+    connectedModelSummaryMaxChars: 1200,
+    activeSummaryMaxChars: 1800,
+    activeSummaryRetentionDays: 30,
+};
 const applyOperationalPreset = (advanced = {}) => {
-    const preset = String(advanced.operationPreset || 'productionFast');
+    const configurationMode = String(advanced.configurationMode || 'advanced');
+    const simpleOverrides = configurationMode === 'simple' ? SIMPLE_MODE_OVERRIDES : {};
+    const preset = String(simpleOverrides.operationPreset || advanced.operationPreset || 'productionFast');
     const presets = {
         productionFast: {
             summarySource: 'activeContext',
@@ -1491,7 +1527,7 @@ const applyOperationalPreset = (advanced = {}) => {
         },
     };
     const presetKey = preset === 'lab' ? 'diagnostic' : preset;
-    const resolved = { ...(presets[presetKey] || {}), ...advanced };
+    const resolved = { ...(presets[presetKey] || {}), ...advanced, ...simpleOverrides, configurationMode };
     if (/^production/i.test(presetKey)) {
         resolved.compactForAgent = true;
         resolved.compactStateSections = true;
@@ -1534,7 +1570,12 @@ const readAdvancedOptions = (ctx, itemIndex) => {
         grouped = flattenAdvancedGroups(ctx.getNodeParameter('advancedGroups', itemIndex, {}) || {});
     }
     catch { }
-    return { ...legacy, ...grouped };
+    let configurationMode = 'simple';
+    try {
+        configurationMode = String(ctx.getNodeParameter('configurationMode', itemIndex, 'simple') || 'simple');
+    }
+    catch { }
+    return { ...legacy, ...grouped, configurationMode };
 };
 const pruneByLimit = (items, limit) => items.slice(Math.max(0, items.length - Math.max(1, Number(limit) || 1)));
 const dedupeRecentMessages = (items) => {
@@ -2400,6 +2441,7 @@ const normalizeToolResultEnvelope = (value) => {
     }
     if (!parsed || typeof parsed !== 'object')
         return parsed;
+    const keys = Object.keys(parsed);
     if (typeof parsed.response === 'string') {
         const nested = normalizeToolResultEnvelope(parsed.response);
         if (nested !== undefined)
@@ -2407,6 +2449,12 @@ const normalizeToolResultEnvelope = (value) => {
     }
     if (parsed.response && typeof parsed.response === 'object')
         return normalizeToolResultEnvelope(parsed.response);
+    if (parsed.json !== undefined && keys.every((key) => ['json', 'pairedItem', 'pairedItems'].includes(key)))
+        return normalizeToolResultEnvelope(parsed.json);
+    for (const key of ['data', 'body', 'result', 'results', 'value']) {
+        if (parsed[key] !== undefined && keys.length === 1)
+            return normalizeToolResultEnvelope(parsed[key]);
+    }
     return parsed;
 };
 const compactParsedToolOutputForSideChannel = (parsed) => {
@@ -2418,6 +2466,13 @@ const compactParsedToolOutputForSideChannel = (parsed) => {
         return parsed;
     if (parsed.output !== undefined)
         return cleanContextValue(stripNoisyToolFields(parsed.output));
+    const keys = Object.keys(parsed);
+    if (parsed.json !== undefined && keys.every((key) => ['json', 'pairedItem', 'pairedItems'].includes(key)))
+        return compactParsedToolOutputForSideChannel(parsed.json);
+    for (const key of ['data', 'body', 'result', 'results', 'value']) {
+        if (parsed[key] !== undefined && keys.length === 1)
+            return compactParsedToolOutputForSideChannel(parsed[key]);
+    }
     return cleanContextValue(stripNoisyToolFields(parsed));
 };
 const toolResultTimestampFromParsed = (parsed) => {
@@ -2838,6 +2893,69 @@ const loadedSectionsForSideChannel = (parsed = {}, memoryAudit = {}) => cleanCon
     recentHighlights: Array.isArray(parsed.recentHighlights),
     contextHealth: Boolean(parsed.contextHealth),
 });
+const budgetEntryForSideChannel = (section, value) => {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = typeof value === 'string' ? value : safeStringify(value);
+    if (!text)
+        return undefined;
+    return {
+        section,
+        chars: text.length,
+        approxTokens: approxTokenCount(text),
+    };
+};
+const agentContextBudgetForSideChannel = (messages = [], parsed = {}) => {
+    const list = Array.isArray(messages) ? messages : [];
+    const messageBudgets = list.map((message, index) => {
+        const content = messageContentOf(message);
+        const role = messageTypeOf(message) || message.role || 'message';
+        return {
+            index,
+            role,
+            chars: content.length,
+            approxTokens: approxTokenCount(content),
+        };
+    });
+    const totalChars = messageBudgets.reduce((sum, item) => sum + item.chars, 0);
+    const sectionCandidates = [
+        ['instruction', parsed.instruction],
+        ['conversation', parsed.conversation],
+        ['current_turn_focus', parsed.current_turn_focus || parsed.currentTurn || parsed.current_turn],
+        ['action_directive', parsed.action_directive],
+        ['turn_brief', parsed.turnBrief || parsed.turn_brief],
+        ['summary', parsed.summary],
+        ['working_memory', parsed.workingMemory || parsed.working_memory],
+        ['decision_state', parsed.decisionState || parsed.decision_state],
+        ['operational_state', parsed.operationalState || parsed.operational_state],
+        ['tools', parsed.tools],
+        ['action_ledger', parsed.actionLedger || parsed.action_ledger],
+        ['memory_compression', parsed.memoryCompression || parsed.memory_compression],
+        ['profile', parsed.profile || parsed.profileFacts || parsed.profile_facts],
+        ['memory_audit', parsed.memoryAudit || parsed.memory_audit],
+        ['dedupe', parsed.dedupeSummary || parsed.dedupe_summary],
+    ];
+    const sections = sectionCandidates
+        .map(([section, value]) => budgetEntryForSideChannel(section, value))
+        .filter(Boolean)
+        .sort((a, b) => b.approxTokens - a.approxTokens);
+    const approxTokens = approxTokenCount(list.map((message) => messageContentOf(message)).join('\n'));
+    const warnings = [];
+    if (approxTokens > 12000)
+        warnings.push('agent context above 12k approximate tokens');
+    else if (approxTokens > 8000)
+        warnings.push('agent context above 8k approximate tokens');
+    if (sections[0] && sections[0].approxTokens > Math.max(2000, approxTokens * 0.45))
+        warnings.push(`largest section is ${sections[0].section}`);
+    return cleanContextValue({
+        messages: list.length,
+        chars: totalChars,
+        approxTokens,
+        byMessage: messageBudgets.slice(0, 8),
+        largestSections: sections.slice(0, 8),
+        warnings,
+    });
+};
 const summarizeMemoryMessagesForSideChannel = (messages = []) => {
     const list = Array.isArray(messages) ? messages : [];
     const summary = { messages: list.length };
@@ -2866,6 +2984,7 @@ const summarizeMemoryMessagesForSideChannel = (messages = []) => {
         const lastSave = compactLastSaveForSideChannel(memoryAudit.last_save || parsed.state?.last_save || {});
         const fullDedupeSummary = parsed.dedupeSummary || parsed.diagnostics?.dedupeSummary || undefined;
         const loadedSections = loadedSectionsForSideChannel(parsed, memoryAudit);
+        const agentContextBudget = agentContextBudgetForSideChannel(list, parsed);
         summary.userId = parsed.userId;
         summary.project = parsed.project || undefined;
         summary.retrievalMode = parsed.retrievalMode;
@@ -2921,6 +3040,8 @@ const summarizeMemoryMessagesForSideChannel = (messages = []) => {
             graph: Array.isArray(parsed.graph) ? parsed.graph.length : undefined,
             recentHighlights: Array.isArray(parsed.recentHighlights) ? parsed.recentHighlights.length : undefined,
         });
+        summary.loadedSections = loadedSections;
+        summary.agentContextBudget = agentContextBudget;
         summary.lastSave = Object.keys(lastSave).length ? lastSave : undefined;
         summary.dedupe = fullDedupeSummary ? compactDedupeForSideChannel(fullDedupeSummary) : undefined;
         summary.workingMemory = cleanContextValue({
@@ -2959,11 +3080,11 @@ const summarizeMemoryMessagesForSideChannel = (messages = []) => {
 };
 const contextSizeOfMessages = (messages = []) => {
     const perMessage = (messages || []).map((message, index) => {
-        const content = String(message.content || '');
+        const content = messageContentOf(message);
         return { index, role: message.role || 'system', chars: content.length, approx_tokens: approxTokenCount(content) };
     });
     const chars = perMessage.reduce((sum, item) => sum + item.chars, 0);
-    return { chars, approx_tokens: approxTokenCount((messages || []).map((m) => m.content || '').join('\n')), messages: perMessage };
+    return { chars, approx_tokens: approxTokenCount((messages || []).map((m) => messageContentOf(m)).join('\n')), messages: perMessage };
 };
 const wrapTemboryMemory = (memory, ctx, memoryKey, itemIndex = 0) => new Proxy(memory, {
     get(target, prop) {
@@ -3435,10 +3556,34 @@ class TemboryMemory {
                     default: '={{ $json.project || $json.projectId || $json.accountId || $json.body?.account?.id || "" }}',
                     description: 'Namespace operacional do workflow para separar clientes/workspaces. Nao e o Project ID da credencial; a API key do Tembory ja identifica o projeto comercial.',
                 },
+                {
+                    displayName: 'Modo de Configuração',
+                    name: 'configurationMode',
+                    type: 'options',
+                    options: [
+                        {
+                            name: 'Simples Recomendado',
+                            value: 'simple',
+                            description: 'Usa os defaults validados em producao: contexto estruturado, SLM por contexto ativo, tool history/results/action ledger, backend persistente e diagnostico pesado desligado.',
+                        },
+                        {
+                            name: 'Avançado',
+                            value: 'advanced',
+                            description: 'Exibe todas as opcoes para ajuste fino de memoria, resumo, auditoria, TTL e payload.',
+                        },
+                    ],
+                    default: 'simple',
+                    description: 'No modo simples o Tembory escolhe a configuracao recomendada. No modo avancado todos os campos continuam disponiveis.',
+                },
                 {
                     displayName: 'Modo de Recuperação de Contexto',
                     name: 'retrievalMode',
                     type: 'options',
+                    displayOptions: {
+                        show: {
+                            configurationMode: ['advanced'],
+                        },
+                    },
                     options: [
                         { name: 'Operacional Estruturado', value: 'basic', description: 'Usa estado da thread, histórico de tools, mensagens recentes e resumo ativo, sem busca vetorial' },
                         { name: 'Resumo', value: 'summary', description: 'Retorna um resumo simples em texto' },
@@ -3450,13 +3595,18 @@ class TemboryMemory {
                     displayName: 'Consulta',
                     name: 'query',
                     type: 'string',
-                    default: '={{ $json.query || $json.lastUserMessage || $json.chatInput || $json.body?.consolidated_text || $json.body?.message || $json.body?.text || "" }}',
+                    default: '={{ $json.query || $json.lastUserMessage || $json.chatInput || $json.body?.chatInput || $json.body?.consolidated_text || $json.body?.message || $json.body?.text || "" }}',
                     description: 'Mensagem atual usada para montar o contexto operacional, inferir intenção e recuperar memórias relevantes. Em AI Agent, mantenha a expressão padrão para ler o chatInput do item.',
                 },
                 {
                     displayName: 'Chave de Memória',
                     name: 'memoryKey',
                     type: 'string',
+                    displayOptions: {
+                        show: {
+                            configurationMode: ['advanced'],
+                        },
+                    },
                     default: 'chat_history',
                     description: 'Chave sob a qual a memória será retornada',
                 },
@@ -3464,6 +3614,11 @@ class TemboryMemory {
                     displayName: 'Formato do Contexto',
                     name: 'payloadFormat',
                     type: 'options',
+                    displayOptions: {
+                        show: {
+                            configurationMode: ['advanced'],
+                        },
+                    },
                     options: [
                         { name: 'Produção Estruturado', value: 'structured' },
                         { name: 'Auditoria Texto', value: 'auditText' },
@@ -3478,6 +3633,11 @@ class TemboryMemory {
                     displayName: 'Configuração Tembory',
                     name: 'advancedGroups',
                     type: 'fixedCollection',
+                    displayOptions: {
+                        show: {
+                            configurationMode: ['advanced'],
+                        },
+                    },
                     placeholder: 'Adicionar Grupo',
                     default: '',
                     typeOptions: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-nodes-tembory",
-  "version": "1.1.30",
+  "version": "1.1.32",
   "description": "Tembory node for n8n AI Agents with operational memory, tool history and decision state",
   "license": "MIT",
   "homepage": "https://tembory.com",