Memory: Sistema de Gerenciamento de Memória

Este documento descreve o mecanismo de gerenciamento de memória, os gatilhos e os detalhes de implementação do Managed Auto-Memory no Qwen Code.

Índice

1. Visão Geral
2. Estrutura de Armazenamento
3. Tipos de Memória
4. Formato dos Itens 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 de Índice
11. Telemetria

Visão Geral

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

Estrutura de Armazenamento

Layout de Diretórios

~/.qwen/                                      ← 全局基础目录（默认）
└── projects/
    └── <sanitized-git-root>/                 ← 项目标识（基于 Git 根路径）
        ├── meta.json                         ← 元数据（提取/整合时间戳、状态）
        ├── extract-cursor.json               ← 提取游标（已处理的对话偏移量）
        ├── consolidation.lock                ← Dream 进程互斥锁
        └── memory/                           ← 记忆主目录
            ├── MEMORY.md                     ← 索引文件（自动生成，汇总所有条目）
            ├── user.md                       ← 用户偏好记忆（示例）
            ├── feedback.md                   ← 反馈规范记忆（示例）
            ├── project/
            │   └── milestone.md              ← 项目记忆（支持子目录）
            └── reference/
                └── grafana.md                ← 外部资源记忆

Substituição por Variáveis de Ambiente:

• QWEN_CODE_MEMORY_BASE_DIR: substitui o diretório base global
• QWEN_CODE_MEMORY_LOCAL=1: usa o caminho relativo ao projeto .qwen/memory/

Descrição dos Arquivos Principais

Tipos de Memória

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

Conteúdo que NÃO deve ser armazenado na memória: padrões/convenções de código, histórico do Git, soluções de debug, estados de tarefas temporárias ou conteúdo já registrado em QWEN.md/AGENTS.md.

Formato dos Itens de Memória

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

---
name: 记忆名称
description: 一句话描述（用于判断召回相关性，要具体）
type: user|feedback|project|reference
---
 
记忆主体内容（summary 行）
 
Why: 背后原因（让 AI 能理解边界情况而不是盲目遵守规则）
How to apply: 适用场景和使用方式

Para os tipos feedback e project, é altamente recomendável preencher Why e How to apply para garantir que a memória seja aplicada corretamente mesmo em casos de borda.

Ciclo de Vida Principal

Extract — Extração

Gatilho

Acionado automaticamente (em segundo plano, sem bloqueio) por scheduleAutoMemoryExtract sempre que a IA conclui uma resposta.

Lógica de Agendamento (extractScheduler.ts)

Explicação dos motivos de pulo:

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

Cursor de Extração:

• Campos: { sessionId, processedOffset, updatedAt }
• Após cada extração, atualiza processedOffset para o comprimento atual do histórico
• Na próxima extração, processa apenas mensagens com offset >= processedOffset
• Em mudanças de sessão (sessionId alterado), reinicia do offset 0

Regras de Filtragem de Patch:

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

Dream — Consolidação

Gatilho

Acionado automaticamente (em segundo plano, sem bloqueio) por scheduleManagedAutoMemoryDream após cada resposta da IA. No entanto, é protegido por várias condições de gate, sendo ignorado na maioria dos casos.

Gate de Agendamento (dreamScheduler.ts)

Parâmetros do Gate:

Mecanismo de Lock:

• O arquivo de lock fica em <project-state-dir>/consolidation.lock
• Contém o PID do processo detentor
• Na verificação: se o processo do PID não existir mais (falha em kill(pid, 0)) ou o lock tiver mais de 1 hora → considerado expirado e removido automaticamente

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

Lógica de Deduplicação Mecânica:

1. Dentro de cada arquivo de tópico: remove duplicatas por summary.toLowerCase(), mesclando os campos why/howToApply
2. Reordena os resumos em ordem alfabética
3. Entre arquivos: entradas com o mesmo type:summary são mescladas no primeiro arquivo encontrado, e os arquivos duplicados são excluídos

Recall — Recuperação

Gatilho

Acionado automaticamente por resolveRelevantAutoMemoryPromptForQuery antes de a IA processar cada solicitação do usuário, injetando memórias relevantes no prompt do sistema.

Fluxo de Recuperação (recall.ts)

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

Palavras-chave características por 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:

• Injeta no máximo 5 documentos (MAX_RELEVANT_DOCS)
• Trunca o corpo de cada documento para 1200 caracteres (MAX_DOC_BODY_CHARS)
• Adiciona o aviso "NOTE: Relevant memory truncated for prompt budget." quando há truncamento
• Inclui informações de atualidade do documento (baseado no mtime do arquivo)

Forget — Esquecimento

Gatilho

Acionado manualmente pelo usuário ao executar o comando /forget <query>.

Fluxo de Esquecimento (forget.ts)

Design do ID de Entry:

• Arquivos de entrada única (caso comum): relativePath (ex: feedback/no-summary.md)
• Arquivos de múltiplas entradas: relativePath:index (ex: feedback/style.md:2)
• O uso de IDs estáveis permite que o modelo localize entradas com precisão sem afetar outras entradas no mesmo arquivo

Reconstrução de Índice

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

- [用户偏好](user/preferences.md) — 用户是资深 Go 工程师，第一次接触 React
- [反馈规范](feedback/style.md) — 保持回复简洁，不要尾部总结
- [项目里程碑](project/milestone.md) — 移动端发布切分支前的合并冻结窗口

Limitações do Índice:

• Máximo de 150 caracteres por linha (excedentes são truncados com …)
• Máximo de 200 linhas
• Tamanho total não pode exceder 25.000 bytes

Telemetria

O sistema inclui 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 de Origem Relacionados