Skip to main content
O Memory constrói o grafo em jobs: um coordenador planeja a execução e dispara jobs de entidades, de nós e de arestas. Cada tipo de job roda em paralelo no seu próprio pool do Prefect. Esta página é para quem opera a instalação: mostra o fluxo, as variáveis do .env que dimensionam a concorrência e o que mudou nos pools no upgrade.

​
Visão geral

Outros dois pools não participam do fluxo do Memory: strattum-control (rotinas curtas de coordenação) e strattum-knowledge-ingest (ingestão do Knowledge).

​
Como configurar

A configuração é feita só pelo .env da instalação. Não há presets de tamanho: as variáveis abaixo definem quantos jobs rodam ao mesmo tempo e quanta memória cada container recebe. Os padrões foram dimensionados para uma máquina de 32 GB, com 3 jobs por pool. O limite de memória é o teto do container, não uma reserva: um worker parado usa pouco. A concorrência vale por container: cada container comporta esse número de jobs dentro do seu limite de memória, por isso o limite e a concorrência devem ser ajustados juntos.
Depois de alterar o .env, recrie os containers dos workers para a mudança valer.

​
Modo pouca memória

Em máquinas menores, reduza todas as concorrências para 1. Cada pool passa a rodar um job por vez, e os limites de memória podem continuar nos padrões.
.env
A execução fica mais lenta, mas o resultado no grafo é o mesmo.

​
Paralelismo

O Memory executa em três fases, sempre nesta ordem:
  1. Entidades. Todos os jobs de entidades rodam em paralelo, um por tipo de entidade (rótulos que compartilham identificador ficam no mesmo job).
  2. Nós. Começam só depois que todos os jobs de entidades terminam. Os jobs de cada tipo rodam em paralelo.
  3. Arestas. Começam só depois que todos os jobs de nós terminam. Cada tipo de aresta é um job, em paralelo com os demais.
Dentro de uma fase o paralelismo é limitado pela concorrência do pool. As fases em si são sequenciais: isso garante que as identidades estejam completas antes de qualquer escrita no grafo e que as arestas encontrem os dois nós. Um tipo de entidade muito grande é dividido em fatias, que rodam em paralelo dentro da mesma fase. Só uma execução do Memory roda por vez. Ao final, o coordenador faz o fechamento: remove o que não existe mais, reconstrói as linhas do tempo afetadas, atualiza o índice vetorial dos nomes e avança os watermarks. Se algum job falha, nenhuma fonte da execução tem o watermark avançado, e tudo é lido de novo na execução seguinte.

​
Incremental

O Memory processa só o que mudou:
  • O coordenador compara, por fonte, o watermark guardado com a versão atual da tabela. Uma fonte sem mudança não é lida.
  • Um job cujas fontes não mudaram roda dentro do coordenador, em milissegundos, e não vira processo. Uma execução sem nenhuma mudança não dispara jobs.
  • O watermark incremental dos conectores de banco é estrito: o próximo sync traz só as linhas com o campo de cursor maior que o último valor lido. Use como cursor uma coluna que só cresce, como updated_at.
Limitação conhecida: a carga incremental não detecta linhas apagadas na fonte, porque lê só o que é novo ou alterado. Para refletir exclusões na fonte, faça um full refresh. Ele relê todas as fontes por inteiro e remove do grafo o que nenhuma fonte escreveu de novo, sem deixar o grafo vazio durante o processo.

​
Operação e upgrade

​
Pools

Os nomes dos pools seguem o padrão strattum-<área>-<função>: Cada pool tem um container worker, com o nome prefect-worker-<função>.

​
Upgrade

No upgrade, os pools antigos são aposentados automaticamente: strattum-data-workers, strattum-data-control e strattum-ai-workers. O que acontece com eles:
  • Os deployments passam para os pools novos no boot do registrador.
  • Runs ainda na fila (agendadas ou pendentes) no pool antigo são canceladas e recriadas no pool novo pelo próximo agendamento ou notificação.
  • Runs em execução terminam normalmente, e o pool antigo é removido quando não tiver mais nada pendente.
Se o .env da instalação ainda usa os nomes antigos de variável de pool, troque pelas variáveis da tabela acima.
O upgrade migra o catálogo do lakehouse para DuckDB 2.0 e DuckLake 1.1, e a migração é de mão única: imagens anteriores não conseguem abrir o catálogo migrado. Faça backup do banco ducklake_catalog antes do upgrade. Reverter exige restaurar esse backup. Atualize todos os serviços juntos.

​
Como acompanhar

  • Prefect. Cada pool lista seus workers e runs. Os jobs do Memory aparecem como runs de memory_entity_job, memory_node_job e memory_edge_job, com a chave entities:<Tipo>, nodes:<Tipo> ou edges:<TIPO>, e a execução do coordenador como memory_worker. A ordem das fases fica visível nos horários.
  • Console. O estado de cada execução do Memory e dos seus jobs aparece na área de pipelines do Console. Ver Monitoramento.

​
Próximos passos

Manutenção e upgrades

Como a atualização de versão e o backup acontecem.

Monitoramento

Saúde dos serviços, pipelines e frescor dos dados.

Frequência de sync

Como a carga incremental dos conectores é agendada.

Memory

O grafo de entidades que esses pipelines constroem.