Active Memory é um subagente de memória bloqueante opcional, pertencente ao plugin, que é executado antes da resposta principal em sessões conversacionais qualificadas. Ela existe porque a maioria dos sistemas de memória é capaz, mas reativa. Eles dependem do agente principal para decidir quando pesquisar a memória, ou do usuário para dizer coisas como “lembre-se disso” ou “pesquise na memória”. Nesse ponto, o momento em que a memória teria feito a resposta parecer natural já passou. Active Memory dá ao sistema uma oportunidade limitada de trazer à tona memórias relevantes antes que a resposta principal seja gerada.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Início rápido
Cole isto emopenclaw.json para uma configuração com padrões seguros — plugin ativado, limitado ao
agente main, apenas sessões de mensagem direta, herdando o modelo da sessão
quando disponível:
plugins.entries.active-memory.enabled: trueativa o pluginconfig.agents: ["main"]inclui apenas o agentemainno Active Memoryconfig.allowedChatTypes: ["direct"]limita o uso a sessões de mensagem direta (inclua grupos/canais explicitamente)config.model(opcional) fixa um modelo dedicado de recuperação; quando não definido, herda o modelo da sessão atualconfig.modelFallbacké usado somente quando nenhum modelo explícito ou herdado é resolvidoconfig.promptStyle: "balanced"é o padrão para o modorecent- Active Memory ainda é executada somente em sessões de chat interativas persistentes qualificadas
Recomendações de velocidade
A configuração mais simples é deixarconfig.model indefinido e permitir que Active Memory use
o mesmo modelo que você já usa para respostas normais. Esse é o padrão mais seguro
porque segue seu provedor, autenticação e preferências de modelo existentes.
Se você quiser que Active Memory pareça mais rápida, use um modelo de inferência dedicado
em vez de reutilizar o modelo principal de chat. A qualidade da recuperação importa, mas a latência
importa mais do que no caminho da resposta principal, e a superfície de ferramentas do Active Memory
é estreita (ela chama apenas as ferramentas de recuperação de memória disponíveis).
Boas opções de modelo rápido:
cerebras/gpt-oss-120bpara um modelo de recuperação dedicado de baixa latênciagoogle/gemini-3-flashcomo fallback de baixa latência sem alterar seu modelo principal de chat- seu modelo normal de sessão, deixando
config.modelindefinido
Configuração do Cerebras
Adicione um provedor Cerebras e aponte Active Memory para ele:chat/completions para o
modelo escolhido — a visibilidade em /v1/models por si só não garante isso.
Como vê-la
Active Memory injeta um prefixo oculto de prompt não confiável para o modelo. Ela não expõe tags brutas<active_memory_plugin>...</active_memory_plugin> na
resposta normal visível ao cliente.
Alternância de sessão
Use o comando do plugin quando quiser pausar ou retomar Active Memory para a sessão de chat atual sem editar a configuração:plugins.entries.active-memory.enabled, o direcionamento de agentes nem outra
configuração global.
Se você quiser que o comando grave a configuração e pause ou retome Active Memory para
todas as sessões, use a forma global explícita:
plugins.entries.active-memory.config.enabled. Ela deixa
plugins.entries.active-memory.enabled ativado para que o comando continue disponível para
reativar Active Memory mais tarde.
Se você quiser ver o que Active Memory está fazendo em uma sessão ao vivo, ative as
alternâncias de sessão que correspondem à saída desejada:
- uma linha de status do Active Memory, como
Active Memory: status=ok elapsed=842ms query=recent summary=34 chars, quando/verbose on - um resumo de depuração legível, como
Active Memory Debug: Lemon pepper wings with blue cheese., quando/trace on
/trace raw, o bloco rastreado Model Input (User Role) mostrará
o prefixo oculto do Active Memory como:
Quando ela é executada
Active Memory usa duas barreiras:- Inclusão pela configuração
O plugin deve estar ativado, e o id do agente atual deve aparecer em
plugins.entries.active-memory.config.agents. - Elegibilidade estrita em tempo de execução Mesmo quando ativada e direcionada, Active Memory só é executada em sessões de chat interativas persistentes qualificadas.
Tipos de sessão
config.allowedChatTypes controla quais tipos de conversas podem executar Active
Memory.
O padrão é:
config.allowedChatIds e
config.deniedChatIds depois de escolher os tipos de sessão permitidos.
allowedChatIds é uma allowlist explícita de ids de conversa resolvidos. Quando ela
não está vazia, Active Memory só é executada quando o id da conversa da sessão está nessa
lista. Isso restringe todos os tipos de chat permitidos de uma vez, incluindo mensagens
diretas. Se você quiser todas as mensagens diretas mais apenas grupos específicos, inclua
os ids dos pares diretos em allowedChatIds ou mantenha allowedChatTypes focado na
implantação de grupo/canal que você está testando.
deniedChatIds é uma denylist explícita. Ela sempre prevalece sobre
allowedChatTypes e allowedChatIds, portanto uma conversa correspondente é ignorada
mesmo quando seu tipo de sessão seria permitido de outra forma.
Os ids vêm da chave de sessão persistente do canal: por exemplo, Feishu
chat_id / open_id, id de chat do Telegram ou id de canal do Slack. A correspondência
não diferencia maiúsculas de minúsculas. Se allowedChatIds não estiver vazia e o OpenClaw não conseguir resolver um
id de conversa para a sessão, Active Memory ignora a rodada em vez de
adivinhar.
Exemplo:
Onde ela é executada
Active Memory é um recurso de enriquecimento conversacional, não um recurso de inferência para toda a plataforma.| Superfície | Executa Active Memory? |
|---|---|
| Sessões persistentes da Control UI / chat web | Sim, se o plugin estiver ativado e o agente for direcionado |
| Outras sessões de canal interativas no mesmo caminho de chat persistente | Sim, se o plugin estiver ativado e o agente for direcionado |
| Execuções headless de uma única tentativa | Não |
| Execuções de Heartbeat/em segundo plano | Não |
Caminhos internos genéricos de agent-command | Não |
| Execução de subagente/auxiliar interno | Não |
Por que usá-la
Use Active Memory quando:- a sessão for persistente e voltada ao usuário
- o agente tiver memória de longo prazo significativa para pesquisar
- continuidade e personalização importarem mais do que determinismo bruto do prompt
- preferências estáveis
- hábitos recorrentes
- contexto de usuário de longo prazo que deve aparecer naturalmente
- automação
- workers internos
- tarefas de API de uma única tentativa
- lugares em que personalização oculta seria surpreendente
Como funciona
O formato de runtime é: O subagente de memória bloqueante pode usar apenas as ferramentas de recuperação de memória disponíveis:memory_recallmemory_searchmemory_get
NONE.
Modos de consulta
config.queryMode controla quanto da conversa o subagente de memória bloqueante
vê. Escolha o menor modo que ainda responda bem a perguntas de acompanhamento;
os orçamentos de timeout devem crescer com o tamanho do contexto (message < recent < full).
- message
- recent
- full
Apenas a mensagem mais recente do usuário é enviada.Use isso quando:
- você quiser o comportamento mais rápido
- você quiser o viés mais forte em favor da recuperação de preferências estáveis
- rodadas de acompanhamento não precisarem de contexto conversacional
3000 a 5000 ms para config.timeoutMs.Estilos de prompt
config.promptStyle controla o quão ávido ou rigoroso o subagente de memória bloqueante é
ao decidir se deve retornar memória.
Estilos disponíveis:
balanced: padrão de uso geral para o modorecentstrict: menos propenso a incluir contexto; melhor quando você quer pouquíssima contaminação de contexto próximocontextual: mais favorável à continuidade; melhor quando o histórico da conversa deve importar maisrecall-heavy: mais disposto a trazer memória em correspondências mais suaves, mas ainda plausíveisprecision-heavy: prefere agressivamenteNONE, a menos que a correspondência seja óbviapreference-only: otimizado para favoritos, hábitos, rotinas, gostos e fatos pessoais recorrentes
config.promptStyle não está definido:
config.promptStyle explicitamente, essa substituição prevalece.
Exemplo:
Política de modelo alternativo
Seconfig.model não estiver definido, o Active Memory tenta resolver um modelo nesta ordem:
config.modelFallback controla a etapa de modelo alternativo configurado.
Modelo alternativo personalizado opcional:
config.modelFallbackPolicy é mantido apenas como um campo de compatibilidade
obsoleto para configurações antigas. Ele não altera mais o comportamento em tempo de execução.
Válvulas de escape avançadas
Estas opções intencionalmente não fazem parte da configuração recomendada.config.thinking pode substituir o nível de raciocínio do subagente de memória bloqueante:
config.promptAppend adiciona instruções extras de operador após o prompt padrão do Active
Memory e antes do contexto da conversa:
config.promptOverride substitui o prompt padrão do Active Memory. O OpenClaw
ainda acrescenta o contexto da conversa depois:
NONE
ou um contexto compacto de fatos do usuário para o modelo principal.
Persistência de transcrições
Execuções do subagente de memória bloqueante do Active Memory criam uma transcriçãosession.jsonl real durante a chamada do subagente de memória bloqueante.
Por padrão, essa transcrição é temporária:
- ela é gravada em um diretório temporário
- ela é usada apenas para a execução do subagente de memória bloqueante
- ela é excluída imediatamente após a execução terminar
config.transcriptDir.
Use isto com cuidado:
- transcrições do subagente de memória bloqueante podem se acumular rapidamente em sessões movimentadas
- o modo de consulta
fullpode duplicar muito contexto de conversa - essas transcrições contêm contexto de prompt oculto e memórias recuperadas
Configuração
Toda a configuração do Active Memory fica em:| Chave | Tipo | Significado |
|---|---|---|
enabled | boolean | Habilita o próprio Plugin |
config.agents | string[] | IDs de agentes que podem usar Active Memory |
config.model | string | Referência opcional de modelo do subagente de memória bloqueante; quando não definida, o Active Memory usa o modelo da sessão atual |
config.allowedChatTypes | ("direct" | "group" | "channel")[] | Tipos de sessão que podem executar o Active Memory; o padrão são sessões no estilo mensagem direta |
config.allowedChatIds | string[] | Lista de permissão opcional por conversa aplicada após allowedChatTypes; listas não vazias falham de forma fechada |
config.deniedChatIds | string[] | Lista de bloqueio opcional por conversa que substitui tipos de sessão permitidos e IDs permitidos |
config.queryMode | "message" | "recent" | "full" | Controla quanto da conversa o subagente de memória bloqueante vê |
config.promptStyle | "balanced" | "strict" | "contextual" | "recall-heavy" | "precision-heavy" | "preference-only" | Controla quão propenso ou estrito o subagente de memória bloqueante é ao decidir se deve retornar memória |
config.thinking | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive" | "max" | Substituição avançada de raciocínio para o subagente de memória bloqueante; padrão off para velocidade |
config.promptOverride | string | Substituição avançada completa do prompt; não recomendada para uso normal |
config.promptAppend | string | Instruções extras avançadas acrescentadas ao prompt padrão ou substituído |
config.timeoutMs | number | Tempo limite rígido para o subagente de memória bloqueante, limitado a 120000 ms |
config.setupGraceTimeoutMs | number | Orçamento avançado extra de configuração antes que o tempo limite de recuperação expire; o padrão é 0 e é limitado a 30000 ms. Consulte Tolerância de inicialização fria para orientações de atualização da v2026.4.x |
config.maxSummaryChars | number | Máximo de caracteres totais permitidos no resumo de active-memory |
config.logging | boolean | Emite logs do Active Memory durante ajustes |
config.persistTranscripts | boolean | Mantém transcrições do subagente de memória bloqueante em disco em vez de excluir arquivos temporários |
config.transcriptDir | string | Diretório relativo de transcrições do subagente de memória bloqueante sob a pasta de sessões do agente |
| Chave | Tipo | Significado |
|---|---|---|
config.maxSummaryChars | number | Total máximo de caracteres permitido no resumo de memória ativa |
config.recentUserTurns | number | Turnos anteriores do usuário a incluir quando queryMode for recent |
config.recentAssistantTurns | number | Turnos anteriores do assistente a incluir quando queryMode for recent |
config.recentUserChars | number | Máximo de caracteres por turno recente do usuário |
config.recentAssistantChars | number | Máximo de caracteres por turno recente do assistente |
config.cacheTtlMs | number | Reutilização de cache para consultas idênticas repetidas (intervalo: 1000-120000 ms; padrão: 15000) |
config.circuitBreakerMaxTimeouts | number | Ignora a recuperação após esse número de timeouts consecutivos para o mesmo agente/modelo. Redefine após uma recuperação bem-sucedida ou após o cooldown expirar (intervalo: 1-20; padrão: 3). |
config.circuitBreakerCooldownMs | number | Por quanto tempo ignorar a recuperação após o circuit breaker disparar, em ms (intervalo: 5000-600000; padrão: 60000). |
Configuração recomendada
Comece comrecent.
/verbose on para a
linha de status normal e /trace on para o resumo de depuração da memória ativa, em vez
de procurar um comando de depuração separado para memória ativa. Em canais de chat, essas
linhas de diagnóstico são enviadas após a resposta principal do assistente, não antes dela.
Depois passe para:
messagese você quiser menor latênciafullse decidir que o contexto extra vale o subagente de memória bloqueante mais lento
Tolerância de inicialização a frio
Antes da v2026.5.2, o Plugin estendia silenciosamente seutimeoutMs configurado em
mais 30000 ms durante a inicialização a frio, para que o aquecimento do modelo, o carregamento
do índice de embeddings e a primeira recuperação pudessem compartilhar um orçamento maior. A v2026.5.2 moveu essa tolerância
para trás de uma configuração explícita setupGraceTimeoutMs — seu timeoutMs configurado
agora é o orçamento por padrão, a menos que você opte por isso.
Se você atualizou da v2026.4.x e definiu timeoutMs para um valor ajustado para o
mundo antigo de tolerância implícita (o timeoutMs: 15000 inicial recomendado é um
exemplo), defina setupGraceTimeoutMs: 30000 para estender os orçamentos do hook de construção de prompt e
do watchdog externo de volta aos valores efetivos anteriores à v5.2:
setupGraceTimeoutMs, para que o Plugin não estenda mais silenciosamente
configurações de 15000 ms para 45000 ms na via principal.”
O executor de recuperação incorporado usa o mesmo orçamento de timeout efetivo, portanto
setupGraceTimeoutMs cobre tanto o watchdog externo de construção de prompt quanto a execução interna
de recuperação bloqueante.
Para gateways com recursos restritos em que a latência de inicialização a frio é uma compensação conhecida,
valores menores (5000–15000 ms) também funcionam — a compensação é uma chance maior de
a primeira recuperação logo após uma reinicialização do Gateway retornar vazia enquanto o aquecimento
termina.
Depuração
Se a memória ativa não estiver aparecendo onde você espera:- Confirme que o Plugin está habilitado em
plugins.entries.active-memory.enabled. - Confirme que o id do agente atual está listado em
config.agents. - Confirme que você está testando por meio de uma sessão de chat interativa persistente.
- Ative
config.logging: truee observe os logs do Gateway. - Verifique se a busca de memória em si funciona com
openclaw memory status --deep.
maxSummaryChars
- reduza
queryMode - reduza
timeoutMs - reduza as contagens de turnos recentes
- reduza os limites de caracteres por turno
Problemas comuns
Active Memory depende do pipeline de recuperação do Plugin de memória configurado, portanto a maioria das surpresas de recuperação são problemas do provedor de embeddings, não bugs do Active Memory. O caminho padrãomemory-core usa memory_search; memory-lancedb usa
memory_recall.
Provedor de embeddings trocado ou parou de funcionar
Provedor de embeddings trocado ou parou de funcionar
Se
memorySearch.provider não estiver definido, o OpenClaw detecta automaticamente o primeiro
provedor de embeddings disponível. Uma nova chave de API, esgotamento de cota ou um
provedor hospedado com limite de taxa pode alterar qual provedor é resolvido entre
execuções. Se nenhum provedor for resolvido, memory_search pode degradar para recuperação
apenas lexical; falhas em tempo de execução depois que um provedor já foi selecionado não
fazem fallback automaticamente.Fixe o provedor (e um fallback opcional) explicitamente para tornar a seleção
determinística. Consulte Busca de memória para a lista completa
de provedores e exemplos de fixação.A recuperação parece lenta, vazia ou inconsistente
A recuperação parece lenta, vazia ou inconsistente
- Ative
/trace onpara expor o resumo de depuração do Active Memory pertencente ao Plugin na sessão. - Ative
/verbose onpara também ver a linha de status🧩 Active Memory: ...após cada resposta. - Observe os logs do Gateway por
active-memory: ... start|done,memory sync failed (search-bootstrap)ou erros de embeddings do provedor. - Execute
openclaw memory status --deeppara inspecionar o backend de busca de memória e a integridade do índice. - Se você usa
ollama, confirme que o modelo de embeddings está instalado (ollama list).
Primeira recuperação após reiniciar o Gateway retorna `status=timeout`
Primeira recuperação após reiniciar o Gateway retorna `status=timeout`
Na v2026.5.2 e posteriores, se a configuração de inicialização a frio (aquecimento do modelo + carregamento do
índice de embeddings) não tiver terminado quando a primeira recuperação disparar, a execução
pode atingir o orçamento
timeoutMs configurado e retornar status=timeout
com saída vazia. Os logs do Gateway mostram active-memory timeout after Nms
perto da primeira resposta elegível após uma reinicialização.Consulte Tolerância de inicialização a frio em Configuração recomendada para o
valor recomendado de setupGraceTimeoutMs.