Sistema de Gerenciamento de Memória

Este artigo apresenta o mecanismo de gerenciamento de memória Managed Auto-Memory (Memória Automática Gerenciada) no Qwen Code, incluindo seus gatilhos e detalhes de implementação.

Índice

1. Visão Geral
2. Estrutura de Armazenamento
3. Tipos de Memória
4. Formato das Entradas de Memória
5. Ciclo de Vida Principal
6. Extract — Extração
7. Dream — Consolidação
8. Recall — Recuperação
9. Forget — Esquecimento
10. Reconstrução do Índice
11. Telemetria e Eventos

Visão Geral

O Managed Auto-Memory é um sistema de memória persistente que automaticamente acumula, consolida e recupera conhecimento relevante do usuário durante sessões de IA. Ele mantém o ciclo de vida da memória através de quatro operações principais:

Estrutura de Armazenamento

Layout de Diretórios

~/.qwen/                                      ← Diretório base global (padrão)
└── projects/
    └── <sanitized-git-root>/                 ← Identificador do projeto (baseado na raiz Git)
        ├── meta.json                         ← Metadados (timestamps de extração/consolidação, status)
        ├── extract-cursor.json               ← Cursor de extração (offset do diálogo já processado)
        ├── consolidation.lock                ← Lock de exclusão mútua do processo Dream
        └── memory/                           ← Diretório principal de memória
            ├── MEMORY.md                     ← Arquivo de índice (gerado automaticamente, resume todas as entradas)
            ├── user.md                       ← Memória de preferências do usuário (exemplo)
            ├── feedback.md                   ← Memória de regras de feedback (exemplo)
            ├── project/
            │   └── milestone.md              ← Memória de projeto (suporta subdiretórios)
            └── reference/
                └── grafana.md                ← Memória de recurso externo

Sobrescrita por variável de ambiente:

• QWEN_CODE_MEMORY_BASE_DIR: Substitui o diretório base global
• QWEN_CODE_MEMORY_LOCAL=1: Usa o caminho .qwen/memory/ dentro do projeto

Descrição dos Arquivos Chave

Tipos de Memória

O sistema suporta quatro tipos de memória embutidos, cada um correspondendo a uma dimensão diferente de informação:

Conteúdo que NÃO deve ser armazenado em memória: Padrões/convenções de código, histórico Git, soluções de debug, status de tasks temporárias, conteúdo já presente em QWEN.md/AGENTS.md.

Formato das Entradas de Memória

Cada arquivo de tópico usa o formato YAML frontmatter + Markdown body:

---
name: Nome da memória
description: Descrição em uma frase (para julgar relevância na recuperação; seja específico)
type: user|feedback|project|reference
---
 
Conteúdo principal da memória (linha de sumário)
 
Why: Razão subjacente (para que a IA entenda casos de contorno em vez de seguir regras cegamente)
How to apply: Cenários de aplicação e modo de uso

Para os tipos feedback e project, é fortemente recomendado preencher Why e How to apply para que a memória ainda seja aplicada corretamente em casos de contorno.

Ciclo de Vida Principal

Extract — Extração

Momento do Gatilho

Após cada rodada de resposta da IA, é automaticamente acionado por scheduleAutoMemoryExtract (segundo plano, não bloqueante).

Lógica de Agendamento (extractScheduler.ts)

Explicação dos motivos de skip:

Fluxo Principal de Extração (extract.ts)

Nota: O gate isUnderMemoryPressure fica em MemoryManager.runExtract(), não neste fluxo. Quando o monitor reporta pressão hard/critical, o MemoryManager pula a chamada de extract e não avança o cursor.

Cursor de Extração (Cursor):

• Campos: { sessionId, processedOffset, updatedAt }
• Antes de extrair, lê o progresso atual com readExtractCursor e processa apenas a parte não lida com history.slice(processedOffset)
• Após cada extração, atualiza processedOffset para o tamanho atual do histórico (params.history.length)
• Quando a sessão muda (sessionId muda), recomeça do offset 0
• Nota: Não constrói mais transcrição via buildTranscriptMessages / loadUnprocessedTranscriptSlice — hasNewUserMessages é verificado com history.slice(startOffset).some(m => m.role === 'user' && partToString(m.parts).trim().length > 0), fazendo uma stringificação leve apenas na fatia não lida. O histórico completo não é mais processado.

Regras de Filtragem de Patch:

• Resumo com menos de 12 caracteres → descartado
• Resumo terminando em ? → descartado (frase interrogativa)
• Contém palavras-chave temporárias (today/now/currently/temporary etc.) → descartado
• Combinação topic:summary duplicada → deduplicado

Dream — Consolidação

Momento do Gatilho

Após cada rodada de resposta da IA, é automaticamente acionado por scheduleManagedAutoMemoryDream (segundo plano, não bloqueante). No entanto, é protegido por múltiplos gates e, na maioria dos casos, é ignorado.

Gates de Agendamento (dreamScheduler.ts)

Parâmetros dos Gates:

Mecanismo de Lock:

• Arquivo de lock localizado em <project-state-dir>/consolidation.lock
• Conteúdo é o PID do processo detentor
• Durante a verificação: se o processo PID não existe mais (kill(pid, 0) falha) ou o lock tem mais de 1 hora → considerado expirado e removido automaticamente

Fluxo de Execução da Consolidação (dream.ts)

Lógica de Dedup Mecânico:

1. Dentro de cada arquivo de tópico: deduplica por summary.toLowerCase(), mescla campos why/howToApply
2. Reordena entradas em ordem alfabética pelo sumário
3. Entre arquivos: entradas com o mesmo type:summary são mescladas no arquivo descoberto primeiro; arquivos duplicados são removidos

Recall — Recuperação

Momento do Gatilho

Antes de cada rodada da IA processar uma requisição do usuário, é automaticamente acionado por resolveRelevantAutoMemoryPromptForQuery, injetando memórias relevantes no prompt do sistema.

Fluxo de Recuperação (recall.ts)

Regras de Pontuação (Heurística):

Keywords Características de Cada Tipo:

• user: user, preference, background, role, terse
• feedback: feedback, rule, avoid, style, summary
• project: project, goal, incident, deadline, release
• reference: reference, dashboard, ticket, docs, link

Regras de Construção do Prompt:

• Máximo de 5 documentos injetados (MAX_RELEVANT_DOCS)
• Body de cada documento truncado em 1200 caracteres (MAX_DOC_BODY_CHARS)
• Quando truncado, adiciona aviso: “NOTE: Relevant memory truncated for prompt budget.”
• Inclui informação de frescor do documento (baseada no mtime do arquivo)

Forget — Esquecimento

Momento do Gatilho

Acionado manualmente pelo usuário através do comando /forget <query>.

Fluxo de Esquecimento (forget.ts)

Design do Entry ID:

• Arquivo de entrada única (caso comum): relativePath (ex: feedback/no-summary.md)
• Arquivo de múltiplas entradas: relativePath:index (ex: feedback/style.md:2)
• IDs estáveis permitem que o modelo localize precisamente a entrada sem afetar outras entradas no mesmo arquivo

Reconstrução do Índice

MEMORY.md é o índice de navegação de todos os arquivos de tópico. Ele é reconstruído com rebuildManagedAutoMemoryIndex após cada Extract ou Dream:

- [Preferências do Usuário](user/preferences.md) — Usuário é engenheiro Go sênior, primeiro contato com React
- [Regras de Feedback](feedback/style.md) — Mantenha respostas concisas, sem resumo no final
- [Marcos do Projeto](project/milestone.md) — Janela de congelamento de merge antes do branch de corte para release mobile

Limitações do Índice:

• Máximo de 150 caracteres por linha (truncado com … se exceder)
• Máximo de 200 linhas
• Tamanho total não excede 25.000 bytes

Telemetria e Eventos

O sistema possui três tipos de eventos de telemetria para monitorar o desempenho e a eficácia das operações de memória:

Telemetria do Extract

Telemetria do Dream

Telemetria do Recall

Índice de Arquivos Fonte Relacionados