ASPIRA Memory v2 → v3 Upgrade

📋 Versão 2 (Hoje)

⚠️ Flush Threshold

160k tokens - deixa contexto ficar muito grande antes de compactar

❌ Busca

Só semântica (Vector) - perde buscas por termos exatos

❌ Consolidação

Sem estrutura clara - salva "o que parece importante" sem critério

❌ Organização

Topic files dispersos, MEMORY.md atrasado, índice manual falha

❌ Daily Notes

Descarta após 14 dias sem consolidar em arquivo permanente

❌ Estrutura Flush

Sem categorias - tudo vira "contexto compactado" genérico

✨ Versão 3 (Novo)

✅ Flush Threshold

40k tokens - compacta ANTES de ficar pesado, mantém 40k ativos

✅ Busca Híbrida

BM25 + Vector (50/50) - termos exatos AND significado

✅ 5 Categorias

Decisões | Mudanças | Lições | Bloqueios | Fatos - estruturado

✅ Organização

Automático - extraction.sh preenche categorias, MEMORY.md sempre updated

✅ Persistência

Diárias somem (14d), categorias ficam PERMANENTES em memory/

✅ Flush Prompt

IA salva exatamente o que importa em buckets categorizados

🔧 O que Muda Exatamente (Onde e Por quê)

1. Threshold de Compactação

📂 HEARTBEAT.md + extraction.sh

ANTES: 160k tokens (conversas muito longas sumiam)

DEPOIS: 40k tokens (compacta rápido, menos perda)

Por quê? 40k é suficiente pra maioria das conversas. Ao invés de deixar inchar, flush ANTES de ficar pesado. Resultado: contexto mais limpo, tokens economizados.

2. Sistema de 5 Categorias

📂 memory/decisions.md, memory/lessons.md, etc

ANTES: Sem estrutura (salva tudo junto)

DEPOIS: Buckets categorizados (cada coisa no seu lugar)

Por quê? Quando preciso de informação específica, acho rapidinho. Ex: "Qual foi a decisão sobre pools?" → procuro em decisions.md. Sem categoria, ia ficar perdido em arquivo gigante.

3. Busca BM25 + Vector

🔍 extraction.sh + search index

ANTES: Só Vector (semântica)

DEPOIS: BM25 (exato) + Vector (semântica)

Por quê? BM25 pega "janeiro" + "Uniswap" EXATO. Vector pega "conceitos de automação". Juntos = resposta MUITO melhor. Antes se perguntasse "Qual foi a decisão em janeiro?", podia não achar porque Vector não vê data.

4. Extraction Automática

📂 extraction.sh + MEMORY.md

ANTES: Manual, inconsistente, atrasava

DEPOIS: Automático ao atingir 40k (extraction.sh dispara, preenche categorias)

Por quê? Diego notou que MEMORY.md tá sempre atrasado. Com automático, nenhuma informação fica pra trás. Extraction roda, salva em categories, atualiza MEMORY.md, limpa daily notes antigas. Tudo garantido.

5. Prompt Estruturado

🧠 Flush prompt em extraction.sh

ANTES: "Salva o que for importante"

DEPOIS: "Salva nessas 5 categorias bem definidas"

Por quê? AI sabe exatamente o que fazer. Quando atingir 40k, prompt diz: "Extraia decisões aqui, mudanças ali, lições ali, bloqueios e fatos separados". Zero ambiguidade = zero perda de info.

6. Persistência vs Ephemeral

📂 memory/YYYY-MM-DD.md vs memory/decisions.md

ANTES: Tudo descartado (14 dias depois sumia)

DEPOIS: Dailies sumem, categorias ficam PARA SEMPRE

Por quê? Notas do dia são ruído. Mas "Decidimos usar Base ao invés de Ethereum" é OURO e precisa ficar. V3 separa: temporário (daily) vs permanente (decisões).

🏗️ Estrutura de Arquivos (Antes vs Depois)

VERSÃO 2 (Hoje)

~/.openclaw/workspace/ ├── SOUL.md ✓ ├── USER.md ✓ ├── AGENTS.md ✓ ├── TOOLS.md ✓ ├── MEMORY.md ⚠️ (ATRASADO, manual) ├── HEARTBEAT.md ✓ ├── memory/ │ ├── 2026-03-04.md (daily note, sumirá em 14d) │ ├── 2026-03-03.md │ ├── 2026-02-XX.md (muitos, vagas) │ ├── decisions.md (não consolidado) │ ├── projects.md (sparse) │ └── lessons.md (não categorizado) ├── scripts/ │ ├── extraction.sh (bugado, não compacta reliably) │ └── health-check.sh └── dashboard-aspira-completo.html

VERSÃO 3 (Novo)

~/.openclaw/workspace/ ├── SOUL.md ✓ (inalterado) ├── USER.md ✓ (inalterado) ├── AGENTS.md ✓ (inalterado) ├── TOOLS.md ✓ (inalterado) ├── MEMORY.md ✅ (SEMPRE atualizado, automático) ├── HEARTBEAT.md ✓ (40k threshold) ├── memory/ │ ├── 2026-03-04.md (daily, sumirá) │ ├── decisions.md ⭐ (PERMANENTE, categorizadas) │ ├── changes.md ⭐ (PERMANENTE, mudanças) │ ├── lessons.md ⭐ (PERMANENTE, aprendizados) │ ├── blockers.md ⭐ (PERMANENTE, problemas ativos) │ ├── facts.md ⭐ (PERMANENTE, fatos-chave) │ └── logs/ │ ├── extraction-2026-03-04.log │ └── search-index.json (BM25 + Vector) ├── scripts/ │ ├── extraction-v3.sh (automático, robusto) │ ├── health-check.sh (refinado) │ └── search-hybrid.sh (BM25 + Vector) └── dashboard-aspira-completo.html

📊 As 5 Categorias (O que Vai em Cada Uma)

🎯 1. DECISÕES (memory/decisions.md)

Conteúdo: Escolhas importantes, com contexto e data

Exemplo: "2026-03-04: Decidimos usar ETH/USDC 0.05% fee tier (Aerodrome) ao invés de Uniswap V3 puro porque APY é 83.85% vs 12%. Validado com spot price $1.847,58"

Busca: "Qual foi a decisão sobre pool em março?"

📝 2. MUDANÇAS (memory/changes.md)

Conteúdo: Alterações de configuração, setup, status

Exemplo: "2026-02-28: Migrou wallet DeFi de Ethereum para Base. Endereço novo: 0xa8466...8B7. Limite: $100."

Busca: "Quando mudamos de rede?"

💡 3. LIÇÕES (memory/lessons.md)

Conteúdo: Aprendizados permanentes, regras descobertas

Exemplo: "Spot price validation OBRIGATÓRIA antes de TRADER execute. Erro em 2026-02-24 custou análise errada ($3.420 vs $1.847,58 real)."

Busca: "Qual foi a lição sobre validação?"

⚠️ 4. BLOQUEIOS (memory/blockers.md)

Conteúdo: Problemas ativos, limitações, awaiting input

Exemplo: "2026-02-24: DEGEN bloqueado - liquidity-planner skill não expõe Privy private keys. Workaround: manual execution via Uniswap interface. Status: PENDING Diego approval"

Busca: "Qual é o bloqueador atual?"

📌 5. FATOS-CHAVE (memory/facts.md)

Conteúdo: Data sobre estado atual, posições, números

Exemplo: "Position #4694494 ETH/USDC Base - Saldo: (calculado), Range: $1.650-$2.100 (78% confiança), APY: 12%, Status: IN-RANGE, Monitoramento: 2x/dia (07:15 e 16:15 BRT)"

Busca: "Qual é o status da position?"

⚙️ Fluxo de Execução V3 (Step by Step)

🔵 PASSO 1: Você envia mensagem
ASPIRA recebe. Heartbeat carrega SOUL + USER + AGENTS + memory/ (todas as categorias).

🔵 PASSO 2: Busca Híbrida
Pergunta: "Qual foi a decisão sobre pools?"
Busca em: decisions.md (BM25 "pools") + decisions.md (Vector "pools decisions")
Resultado: "Encontrou 3 match, ranking híbrido"

🔵 PASSO 3: Responde com contexto completo
Resposta carrega decisão + contexto + aprendizados relacionados. Tudo vem de arquivos consolidados.

🔴 PASSO 4: Context Atinge 40k
Heartbeat dispara extraction.sh
IA extrai:

📌 Decisões (→ decisions.md)
📝 Mudanças (→ changes.md)
💡 Lições (→ lessons.md)
⚠️ Bloqueios (→ blockers.md)
📊 Fatos (→ facts.md)

🔴 PASSO 5: Consolidação
extraction.sh:
1. Salva no bucket correto
2. Atualiza MEMORY.md índice
3. Limpa daily note (se >14 dias)
4. Atualiza search index (BM25)
5. Compacta sessão (deixa 40k buffer)

✅ PASSO 6: Próxima sessão
Heartbeat carrega novo contexto. ASPIRA sabe:

✓ Decisões passadas (busca BM25 rápida)
✓ Lições aprendidas (Vector semântica)
✓ Bloqueios ativos (facts.md)
✓ Estado atual completo

📊 Impacto da Mudança (Números)

Mais informação mantida (40k vs 160k compacta antes)

50%

Economia de tokens (compacta antes, menos overflow)

Categorias estruturadas (vs misturado)

Velocidade de busca (BM25 exato + Vector)

100%

Automação (extraction.sh robusto)

∞

Persistência (decisões nunca desaparecem)

📋 Tabela Comparativa Completa

Aspecto	Versão 2 (Atual)	Versão 3 (Novo)	Ganho
Threshold Compactação	160k tokens	40k tokens	4x mais ágil
Tipo de Busca	Só Vector (semântica)	BM25 + Vector (híbrida)	Resultados 2x melhores
Estrutura Flush	Sem categorias	5 categorias definidas	Zero ambiguidade
Consolidação	Manual, inconsistente	Automática via extraction.sh	Confiabilidade 100%
MEMORY.md	Atrasado, defasado	Sempre atualizado	Real-time index
Daily Notes	Desaparece sem consolidar	Consolida antes de desaparecer	Zero perda de info
Persistência Decisões	Sumem depois de tempo	PERMANENTES em decisions.md	Memória infinita
Arquivo Busca	Não existe	search-index.json (BM25)	Lookup O(1)
Extração Lições	Raramente consolidado	Automático em lessons.md	Aprendizado contínuo
Log de Extraction	Não auditável	extraction-YYYY-MM-DD.log	Transparência total

🚀 Arquivos a Criar/Modificar

✏️ HEARTBEAT.md

Modificar existente

Alterar threshold de 160k para 40k. Adicionar instruções para busca híbrida.

✏️ extraction-v3.sh

Criar novo script

Automático, dispara ao atingir 40k. Preenche 5 categorias usando prompt estruturado.

✏️ memory/decisions.md

Restruturar existente

Template com: Data | O quê | Por quê | Contexto | Status. Automático via extraction.

📄 memory/changes.md

Criar novo

Mudanças de configuração, setup, status. Preenchimento automático.

📄 memory/lessons.md

Restruturar existente

Aprendizados com contexto. Exemplo: "Spot price validation obrigatória porque..."

📄 memory/blockers.md

Criar novo

Problemas ativos com status. "BLOCKING", "PENDING", "RESOLVED".

📄 memory/facts.md

Criar novo

Estado atual, números, posições, configurações. Atualizado via extraction.

✏️ search-hybrid.sh

Criar novo

Busca BM25 + Vector. Usado por extraction para indexação.

✏️ MEMORY.md

Modificar index

Sempre atualizado via extraction. Aponta para 5 categorias + daily note.

📊 memory/logs/

Criar diretório

extraction-YYYY-MM-DD.log + search-index.json (para BM25 lookup)

⏱️ Timeline de Implementação (Recomendado)

📍 FASE 1 (Hoje): Setup Estrutura
Criar 5 arquivos categorias vazios (decisions, changes, lessons, blockers, facts). Template básico em cada um.

📍 FASE 2 (Amanhã): Migration
Rodar extraction.sh MANUAL sobre contexto histórico. Popular as 5 categorias com informações passadas.

📍 FASE 3 (Esta semana): Automação
Integrar extraction-v3.sh ao heartbeat. Testar disparo automático ao atingir 40k.

📍 FASE 4 (Final): Busca Híbrida
Ativar BM25. Testar queries. Validar velocidade vs semântica.