Pular para conteúdo

As páginas sem tradução abrem em inglês e são identificadas como inglês.

Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.

Personalizar o pipeline de extração

memory.set_from_messages executa sua transcrição por uma lista ordenada de etapas que compartilham um único estado. Uma requisição pode substituir essa lista por meio de pipeline_steps: reordenar ou pular etapas, ou chamar uma etapa em processo que um operador registrou. Esta página trata apenas da lista de etapas; Extração trata do que a extração faz.

pipeline_steps é um campo do corpo HTTP. Ele fica oculto do schema da ferramenta MCP e não é um parâmetro do helper memory.set_from_messages do SDK Python; envie-o por HTTP ou por call(...). Os tipos de entrada de op gerados (sdk/python/loom/ops.py, sdk/typescript/src/generated/ops.ts) o incluem.

O pipeline padrão

DEFAULT_PIPELINE em server/memory/app/pipeline.py:

Etapa O que faz
loom.fetch_namespace_categories Carrega a taxonomia de tags do namespace para o extrator.
loom.fetch_existing_memories Memórias existentes mais próximas (até 50), mostradas ao extrator.
loom.llm_extract A chamada de extração.
loom.drop_recall_echoes Descarta fatos que repetem memórias fornecidas à sessão.
loom.drop_session_echoes Descarta fatos que repetem o que as próprias chamadas do Loom da sessão trouxeram.
loom.drop_activity_narration Descarta narração de atividade de ferramentas sem resultado duradouro.
loom.drop_non_durable Sessões de código: descarta retratos de status, tarefas de manutenção e planos.
loom.verify_durable Sessões de código: passada de verificação sobre os fatos restantes.
loom.hash_dedup Descarta fatos cujo hash canônico já está armazenado.
loom.bulk_write Envia regras do bot (about="agent") para a fila de learnings e grava o restante via memory.bulk_set.

Uma sessão de código é uma transcrição cujas extra_tags carregam uma tag de origem de agente de código (source:claude-code, source:codex, source:cursor), ou um replay de trajetória. As duas etapas de código deixam passar inalteradas as outras transcrições.

Um pipeline_steps vazio executa esta lista. Um não vazio executa exatamente as etapas que ele nomeia, em ordem, sobre um único estado compartilhado. Deixar de fora loom.bulk_write significa que nada é gravado: a resposta ainda informa o que foi extraído.

Executar um pipeline mais curto

Extrair e gravar sem contexto de deduplicação, para uma importação única de dados sabidamente novos:

curl -s "$LOOM_BASE_URL/v1/memory.set_from_messages" \
  -H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' -d '{
  "org": "acme",
  "namespace": "support",
  "agent": "importer",
  "messages": [{ "role": "user", "content": "..." }],
  "pipeline_steps": [{ "step_id": "loom.llm_extract" }, { "step_id": "loom.bulk_write" }]
}'

Isso exige um provedor de LLM real (LOOM_LLM_PROVIDER e sua chave); o provedor falso da stack padrão não extrai fatos significativos.

Comportamento das etapas

Cada descritor é {"step_id": ..., ...}; o objeto inteiro é passado à etapa como sua configuração.

  • No máximo 16 etapas por requisição.
  • Etapas hook.* são recusadas com 422 VALIDATION_FAILED: o servidor não faz nenhuma chamada de saída em nome do chamador.
  • IDs de etapa desconhecidos são ignorados e informados em pipeline_errors na resposta como unknown_step:<id>.
  • Etapas fail-open. Uma etapa de busca que falha registra o erro em pipeline_errors (fetch_existing_failed:<error>, por exemplo) e o pipeline continua.
  • loom.llm_extract falha de forma fechada: um erro de extração aborta a requisição com 502, de modo que uma transcrição nunca receba silenciosamente written=[] como resposta. Ela aceita {"judge": true} em seu descritor para ativar o filtro de julgamento; judge_extraction=true na requisição faz o mesmo para a lista padrão.
  • Tempo. O stage_ms da resposta traz o tempo de relógio de cada etapa (step.<step_id>). Cada etapa também é executada dentro de um span do OpenTelemetry chamado pipeline.step, com o ID da etapa como atributo.

Registrar uma etapa em processo

Um operador registra uma etapa em código que o processo do servidor importa na inicialização:

from server.memory.app.pipeline import WorkflowState, register_step


async def spam_filter(state: WorkflowState, config: dict) -> WorkflowState:
    state.extracted_facts = [
        f for f in state.extracted_facts if "spam" not in str(f.get("value", "")).lower()
    ]
    return state


register_step("operator.spam_filter", spam_filter)

As requisições podem então nomear {"step_id": "operator.spam_filter"}; quaisquer outras chaves do descritor chegam como config. A etapa é executada em processo, com acesso de leitura e escrita a todo o WorkflowState: identidade, mensagens, memórias existentes, fatos extraídos, contadores. register_step substitui um registro existente com o mesmo ID, então uma etapa de operador também pode substituir uma etapa embutida.

Uma etapa que substitui loom.bulk_write deve deixar de fora do que grava os fatos com about="agent": essas são as regras do bot, que a etapa embutida envia para a fila de learnings.

Aviso: uma etapa que descarta ou reescreve extracted_facts muda o que todo chamador que a nomeia armazena. Uma etapa posicionada depois de loom.bulk_write vê as linhas gravadas em state.written, mas não consegue desfazer a gravação.

Para adicionar uma etapa embutida ao próprio Loom, adicione a função e sua chamada a register_step em server/memory/app/pipeline.py, coloque-a em DEFAULT_PIPELINE e execute make bench-quick antes e depois: a lista padrão molda toda extração.

Limites

  • As etapas são executadas em sequência; não há ramificação nem paralelismo.
  • A lista padrão é global; não há pipeline por namespace.
  • Não há retry no nível da etapa.

Relacionados