n8n-nodes-tembory 1.1.30 → 1.1.31

package/README.md

@@ -2,14 +2,37 @@
 
 Node de memoria operacional da Tembory para agentes de IA no n8n.
 
-Versao atual: `1.1.2`.
+Versao atual: `1.1.31`.
 
-## 1.1.2
+## 1.1.31
 
-- 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 `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 +66,52 @@ 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 `Producao Rapida` em producao normal.
+- Use `Producao Balanceada` quando o agente precisar comparar mais historico.
+- Use `Auditoria` ou `Diagnostico Completo` apenas enquanto estiver depurando.
+
+## 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

@@ -2400,6 +2400,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 +2408,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 +2425,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 +2852,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 +2943,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 +2999,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 +3039,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) {

package/package.json

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