> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipelines do Memory: execução paralela

> Como o Memory divide a construção do grafo em jobs paralelos, quais pools do Prefect executam cada etapa e como dimensionar a concorrência no .env.

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

```mermaid theme={null}
flowchart LR
    A["Sync do conector<br/>pool strattum-connector-sync"] -->|raw| B["Clean<br/>pool strattum-clean"]
    B -->|notifica mudança| C["Coordenador<br/>pool strattum-memory-coordinator"]
    C --> D["Jobs de entidades<br/>pool strattum-memory-entities"]
    D -->|todos concluídos| E["Jobs de nós<br/>pool strattum-memory-graph"]
    E -->|todos concluídos| F["Jobs de arestas<br/>pool strattum-memory-graph"]
    F --> G["Fechamento no coordenador<br/>watermarks, limpeza, índice vetorial"]
```

| Etapa | Pool do Prefect | O que faz |
| - | - | - |
| Sync | `strattum-connector-sync` | Extrai a fonte para a camada raw |
| Clean | `strattum-clean` | Constrói as tabelas clean a partir do raw |
| Coordenador | `strattum-memory-coordinator` | Lê a ontologia ativa, decide o que mudou, planeja e dispara os jobs, e fecha a execução |
| Entidades | `strattum-memory-entities` | Resolve identidades e chaves de cada tipo de entidade |
| Nós e arestas | `strattum-memory-graph` | Grava nós e depois arestas no grafo |

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](https://docs.strattum.ai/knowledge/overview.md)).

***

## 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.

| Variável | Padrão | Efeito |
| - | - | - |
| `MEMORY_ENTITY_JOB_CONCURRENCY` | `3` | Jobs de entidades ao mesmo tempo |
| `MEMORY_ENTITY_JOB_MEM_LIMIT` | `3G` | Limite de memória do container dos jobs de entidades |
| `MEMORY_GRAPH_JOB_CONCURRENCY` | `3` | Jobs de nós e de arestas ao mesmo tempo |
| `MEMORY_JOB_WORKER_MEM_LIMIT` | `3G` | Limite de memória do container dos jobs de grafo |
| `CLEAN_WORKER_CONCURRENCY` | `3` | Builds de clean ao mesmo tempo |
| `CLEAN_WORKER_MEM_LIMIT` | `3G` | Limite de memória do container de clean |
| `STRATTUM_RESOURCE_CONCURRENCY` | `3` | Tabelas lidas em paralelo dentro de um sync de conector |
| `DATA_WORKER_MEM_LIMIT` | `3G` | Limite de memória do container de sync de conectores |
| `MEMORY_COORDINATOR_MEM_LIMIT` | `3G` | Limite de memória do coordenador |

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.

> [!NOTE]
>
> 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.

```bash .env theme={null}
MEMORY_ENTITY_JOB_CONCURRENCY=1
MEMORY_GRAPH_JOB_CONCURRENCY=1
CLEAN_WORKER_CONCURRENCY=1
KNOWLEDGE_INGEST_WORKER_CONCURRENCY=1
```

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`.

> [!WARNING]
>
> **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>`:

| Pool | Variável que define o nome |
| - | - |
| `strattum-connector-sync` | `STRATTUM_CONNECTOR_SYNC_WORK_POOL` |
| `strattum-clean` | `STRATTUM_CLEAN_WORK_POOL` |
| `strattum-control` | `STRATTUM_CONTROL_WORK_POOL` |
| `strattum-knowledge-ingest` | `KNOWLEDGE_INGEST_WORK_POOL` |
| `strattum-memory-coordinator` | `MEMORY_WORK_POOL` |
| `strattum-memory-entities` e `strattum-memory-graph` | fixos, sem variável |

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.

> [!WARNING]
>
> 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](https://docs.strattum.ai/admin/monitoring.md).

***

## Próximos passos

> **[Manutenção e upgrades](https://docs.strattum.ai/admin/maintenance-upgrades.md)**
>
> Como a atualização de versão e o backup acontecem.

> **[Monitoramento](https://docs.strattum.ai/admin/monitoring.md)**
>
> Saúde dos serviços, pipelines e frescor dos dados.

> **[Frequência de sync](https://docs.strattum.ai/data-pipelines/sync-frequency.md)**
>
> Como a carga incremental dos conectores é agendada.

> **[Memory](https://docs.strattum.ai/memory/overview.md)**
>
> O grafo de entidades que esses pipelines constroem.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.