MEMORY-SYSTEM.md - Sistema de Memória Tripla¶
Memória episódica, semântica e procedural para agentes inteligentes.
Visão Geral¶
O Sistema de Memória permite que os agentes:
1. Lembrem de interações passadas (EPISÓDICA)
2. Acessem conhecimento estruturado (SEMÂNTICA)
3. Apliquem procedimentos aprendidos (PROCEDURAL)
Isso elimina o problema de "agente sem memória" e
permite aprendizado contínuo e consistência.
Arquitetura de Memória¶
┌─────────────────────────────────────────────────────────────────┐
│ MEMORY SYSTEM │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ EPISODIC │ │ SEMANTIC │ │ PROCEDURAL │ │
│ │ MEMORY │ │ MEMORY │ │ MEMORY │ │
│ │ │ │ │ │ │ │
│ │ "O que │ │ "O que │ │ "Como │ │
│ │ aconteceu" │ │ sabemos" │ │ fazer" │ │
│ │ │ │ │ │ │ │
│ │ - Sessões │ │ - Decisões │ │ - Workflows │ │
│ │ - Conversas │ │ - Fatos │ │ - Templates │ │
│ │ - Eventos │ │ - Definições │ │ - Padrões │ │
│ └────────┬─────────┘ └────────┬─────────┘ └───────┬────────┘ │
│ │ │ │ │
│ └─────────────────────┼────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ MEMORY MANAGER │ │
│ │ - Query routing │ │
│ │ - Consolidation │ │
│ │ - Decay/Refresh │ │
│ └──────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
1. Memória Episódica¶
Definição¶
EPISODIC_MEMORY:
Description: >
Memória de eventos e interações específicas.
"O que aconteceu em determinado momento."
Stores:
- Sessões de trabalho
- Decisões tomadas e contexto
- Problemas encontrados e soluções
- Feedback do usuário
Characteristics:
- Temporal (tem timestamp)
- Contextual (tem circunstâncias)
- Específica (não generalizada)
- Decays over time (menos relevante)
Estrutura de Episódio¶
EPISODE_SCHEMA:
id: "ep_2025-12-28_001"
timestamp: "2025-12-28T14:30:00Z"
session_id: "sess_abc123"
type: "decision" | "problem" | "learning" | "feedback"
context:
query: "[O que foi perguntado]"
intent: "DECISION"
squad: ["CRO", "CFO", "Pre-Mortem"]
urgency: 3
scope: "medium"
content:
summary: "[Resumo em 1-2 frases]"
detail: "[Detalhes completos]"
agents_perspectives:
CRO: "[Perspectiva]"
CFO: "[Perspectiva]"
Pre-Mortem: "[Riscos identificados]"
outcome:
recommendation: "[O que foi recomendado]"
user_action: "accepted" | "modified" | "rejected" | null
result: "success" | "partial" | "failure" | null
learned: "[O que aprendemos]"
connections:
related_episodes: ["ep_xxx", "ep_yyy"]
related_decisions: ["dec_001", "dec_002"]
related_hypotheses: ["HYP-001"]
metadata:
importance: 1-5
decay_rate: "fast" | "normal" | "slow" | "never"
last_accessed: "2025-12-28T14:30:00Z"
access_count: 1
Operações Episódicas¶
EPISODIC_OPERATIONS:
STORE:
Trigger: Após cada interação significativa
Process:
1. Extrair informações-chave
2. Classificar tipo e importância
3. Conectar a episódios relacionados
4. Salvar com timestamp
RECALL:
Trigger: Quando contexto similar é detectado
Process:
1. Buscar episódios similares
2. Ordenar por relevância (recência × importância)
3. Retornar top N episódios
4. Atualizar access_count
CONSOLIDATE:
Trigger: Fim de sessão ou periodicamente
Process:
1. Agrupar episódios relacionados
2. Extrair padrões
3. Promover padrões para SEMÂNTICA
4. Decay episódios antigos irrelevantes
FORGET:
Trigger: Episódio muito antigo + baixa importância
Process:
1. Verificar última vez acessado
2. Verificar importância
3. Se decay_rate permite, remover detalhes
4. Manter apenas resumo (se houver)
Arquivo de Armazenamento¶
DOCS/operations/memory/
├── episodes/
│ ├── 2025-12-28.yaml # Episódios do dia
│ ├── 2025-12-27.yaml
│ └── ...
├── episodes-index.yaml # Índice para busca rápida
└── episodes-consolidated.yaml # Episódios importantes consolidados
2. Memória Semântica¶
Definição¶
SEMANTIC_MEMORY:
Description: >
Memória de fatos, conceitos e conhecimento estruturado.
"O que sabemos ser verdade."
Stores:
- Decisões estratégicas (permanentes)
- Fatos sobre o negócio
- Definições e conceitos
- Relações entre entidades
Characteristics:
- Atemporal (não tem "quando")
- Generalizada (abstraída de episódios)
- Estruturada (organizada por categoria)
- Persistente (não decays)
Categorias Semânticas¶
SEMANTIC_CATEGORIES:
DECISIONS:
Description: Decisões estratégicas tomadas
Examples:
- "Usamos Gemini, não OpenAI"
- "Pricing é R$ 297/597/4000"
- "Bootstrap até PMF"
Source: DOCS/strategy/, decisões documentadas
FACTS:
Description: Fatos sobre o negócio
Examples:
- "Target de MRR é R$ 7M"
- "Temos 3 personas prioritárias"
- "Mercado tem 3M de sellers"
Source: DOCS/strategy/, DOCS/finance/
DEFINITIONS:
Description: O que as coisas significam
Examples:
- "Carlos Solo = persona com 200 vendas/mês"
- "Churn = cancelamento em 30 dias"
- "PMF = Product-Market Fit"
Source: Glossário, documentação
RELATIONSHIPS:
Description: Como coisas se relacionam
Examples:
- "CAC < LTV é requisito"
- "CMO depende de CFO para budget"
- "Feature X bloqueia Feature Y"
Source: DEPENDENCY-MAP.md, análises
CONSTRAINTS:
Description: Limites e restrições
Examples:
- "Runway deve ser >12 meses"
- "Churn deve ser <10%"
- "LGPD deve ser seguida"
Source: DOCS/finance/, DOCS/legal/
Estrutura de Conhecimento¶
SEMANTIC_ENTRY:
id: "sem_pricing_001"
category: "DECISIONS"
content:
statement: "Pricing SellSync é tier-based"
details:
- Basic: R$ 297/mês
- Pro: R$ 597/mês
- Arcos: R$ 4.000/mês
metadata:
confidence: "high" | "medium" | "low"
source: "DOCS/strategy/pricing.md"
decided_date: "2025-12-25"
decided_by: "Founder"
last_validated: "2025-12-28"
connections:
related_to: ["sem_revenue_001", "sem_personas_001"]
depends_on: []
enables: ["sem_growth_001"]
constraints:
can_change: true | false
change_requires: "Founder approval + CFO validation"
expiration: null | "2026-03-31"
Operações Semânticas¶
SEMANTIC_OPERATIONS:
QUERY:
Input: Pergunta ou contexto
Process:
1. Classificar categoria provável
2. Buscar por similaridade
3. Verificar connections
4. Retornar conhecimento relevante
ASSERT:
Input: Nova informação a armazenar
Process:
1. Validar contra conhecimento existente
2. Se conflito, resolver ou sinalizar
3. Classificar categoria
4. Criar connections
5. Salvar
VALIDATE:
Input: Statement a verificar
Process:
1. Buscar knowledge relacionado
2. Verificar se consistente
3. Retornar: confirmed | contradicted | unknown
UPDATE:
Input: Atualização de fato existente
Process:
1. Encontrar entry existente
2. Validar que mudança é permitida
3. Atualizar preservando histórico
4. Propagar para connections
Integração com MCP¶
MCP_INTEGRATION:
searchDocs:
Maps To: SEMANTIC.QUERY
Use: Busca semântica em docs
validateConsistency:
Maps To: SEMANTIC.VALIDATE
Use: Verifica conflitos com conhecimento
addLearning:
Feeds: SEMANTIC (via consolidation)
Use: Novas hipóteses que viram fatos
getHypotheses:
Source: SEMANTIC.DECISIONS (pending)
Use: Decisões ainda não validadas
3. Memória Procedural¶
Definição¶
PROCEDURAL_MEMORY:
Description: >
Memória de "como fazer" coisas.
Padrões, workflows, templates e procedimentos.
Stores:
- Workflows (como executar processos)
- Templates (como formatar outputs)
- Padrões (combinações que funcionam)
- Heurísticas (regras de decisão)
Characteristics:
- Acionável (pode ser executada)
- Otimizável (melhora com uso)
- Modular (componíveis)
- Transferível (aplica em contextos similares)
Tipos de Procedimentos¶
PROCEDURE_TYPES:
WORKFLOWS:
Description: Sequências de passos para alcançar objetivo
Examples:
- "Como lançar feature"
- "Como tomar decisão de pricing"
- "Como responder a crise"
Source: WORKFLOWS.md, experiência
TEMPLATES:
Description: Estruturas reutilizáveis para outputs
Examples:
- "Template de PRD"
- "Template de análise multi-agente"
- "Template de pitch"
Source: AGENT-INTERFACES.md, exemplos
PATTERNS:
Description: Combinações que funcionam bem
Examples:
- "Squad de pricing = CRO + CFO + Pre-Mortem"
- "Para burnout, sempre Founder Coach primeiro"
- "Decisões Type 1 precisam de 3+ agentes"
Source: Aprendido de episódios
HEURISTICS:
Description: Regras rápidas de decisão
Examples:
- "Se urgência > 4, reduzir squad"
- "Se risco > 4, adicionar Pre-Mortem"
- "Se scope = broad, máximo 5 agentes"
Source: ORCHESTRATOR.md, tuning
Estrutura de Procedimento¶
PROCEDURE_SCHEMA:
id: "proc_pricing_decision"
type: "WORKFLOW"
name: "Pricing Decision Workflow"
trigger:
keywords: ["pricing", "preço", "quanto cobrar"]
context: "Decisão sobre pricing"
steps:
- step: 1
action: "Ativar CRO como Lead"
input: "[Contexto de pricing]"
output: "[Análise de valor e mercado]"
- step: 2
action: "Consultar CFO"
input: "[Output step 1] + [Custos]"
output: "[Análise financeira]"
- step: 3
action: "Validar com Pre-Mortem"
input: "[Proposta de preço]"
output: "[Riscos identificados]"
- step: 4
action: "Síntese e Recomendação"
input: "[Todos outputs]"
output: "[Recomendação final]"
success_criteria:
- "Preço cobre custos + margem"
- "Preço alinhado com valor percebido"
- "Riscos mitigados ou aceitos"
metadata:
times_used: 12
success_rate: 0.83
avg_duration_ms: 2500
last_optimized: "2025-12-28"
Operações Procedurais¶
PROCEDURAL_OPERATIONS:
MATCH:
Input: Contexto atual
Process:
1. Extrair keywords e intent
2. Buscar procedimentos com trigger similar
3. Ordenar por match score e success_rate
4. Retornar melhor procedimento
EXECUTE:
Input: Procedimento + contexto
Process:
1. Inicializar com contexto
2. Executar steps em ordem
3. Adaptar se necessário
4. Registrar resultado
OPTIMIZE:
Input: Feedback de execução
Process:
1. Analisar o que funcionou/não funcionou
2. Identificar steps problemáticos
3. Sugerir melhorias
4. Testar variação
COMPOSE:
Input: Múltiplos procedimentos
Process:
1. Identificar interfaces compatíveis
2. Conectar outputs → inputs
3. Criar novo procedimento composto
4. Validar fluxo completo
4. Memory Manager¶
Funções Principais¶
MEMORY_MANAGER:
ROUTING:
Description: Direciona queries para memória correta
Logic:
- "O que aconteceu quando..." → EPISODIC
- "Qual é o..." → SEMANTIC
- "Como fazer..." → PROCEDURAL
- "Devo..." → SEMANTIC + EPISODIC
CONSOLIDATION:
Description: Move conhecimento entre memórias
Flows:
- EPISODIC → SEMANTIC (padrões viram fatos)
- EPISODIC → PROCEDURAL (sequências viram workflows)
- SEMANTIC → PROCEDURAL (fatos viram heurísticas)
COHERENCE:
Description: Mantém consistência entre memórias
Checks:
- Fatos semânticos não conflitam
- Procedimentos usam fatos corretos
- Episódios recentes atualizam semântica
MAINTENANCE:
Description: Limpeza e otimização
Tasks:
- Decay de episódios antigos
- Atualização de confidence scores
- Merge de conhecimentos duplicados
- Backup periódico
Consolidation Rules¶
CONSOLIDATION_RULES:
EPISODE_TO_SEMANTIC:
Trigger: Mesmo padrão aparece em 3+ episódios
Process:
1. Identificar padrão comum
2. Abstrair detalhes específicos
3. Formular como fato geral
4. Adicionar a SEMANTIC com source = "learned"
EPISODE_TO_PROCEDURAL:
Trigger: Mesma sequência de ações em 3+ episódios
Process:
1. Extrair sequência comum
2. Identificar trigger pattern
3. Formular como procedimento
4. Adicionar a PROCEDURAL
SEMANTIC_TO_PROCEDURAL:
Trigger: Conjunto de fatos implica regra de ação
Process:
1. Identificar implicação (IF facts THEN action)
2. Formular como heurística
3. Adicionar a PROCEDURAL
5. Query Interface¶
Query Types¶
QUERY_TYPES:
RECALL:
Description: "Lembrar de algo específico"
Example: "O que decidimos sobre pricing no mês passado?"
Route: EPISODIC → SEMANTIC (fallback)
LOOKUP:
Description: "Buscar fato ou definição"
Example: "Qual é o CAC target?"
Route: SEMANTIC
HOW_TO:
Description: "Como fazer algo"
Example: "Como devo analisar um concorrente?"
Route: PROCEDURAL
VALIDATE:
Description: "Verificar se algo é verdade"
Example: "Isso conflita com alguma decisão?"
Route: SEMANTIC.VALIDATE
SIMILAR:
Description: "Encontrar situações similares"
Example: "Já passamos por algo parecido?"
Route: EPISODIC.SEARCH
Query Resolution¶
def resolve_query(query, context):
"""
Resolve a memory query across all memory types.
"""
# 1. Classify query type
query_type = classify_query(query)
# 2. Route to appropriate memory
if query_type == "RECALL":
results = episodic_memory.search(query, context)
if not results:
results = semantic_memory.query(query)
elif query_type == "LOOKUP":
results = semantic_memory.query(query)
elif query_type == "HOW_TO":
results = procedural_memory.match(query, context)
elif query_type == "VALIDATE":
results = semantic_memory.validate(query)
elif query_type == "SIMILAR":
results = episodic_memory.find_similar(context)
# 3. Enrich with connections
enriched = enrich_with_connections(results)
# 4. Format for consumption
return format_results(enriched, query_type)
6. Decay e Refresh¶
Decay Model¶
DECAY_MODEL:
Description: >
Episódios perdem relevância ao longo do tempo,
mas podem ser "refreshed" se acessados.
Formula: >
relevance = base_importance × decay_factor × recency_boost
Decay Factors:
fast: 0.5 per week (operacional trivial)
normal: 0.8 per week (padrão)
slow: 0.95 per week (importante)
never: 1.0 (decisões críticas)
Recency Boost:
accessed_today: 2.0
accessed_this_week: 1.5
accessed_this_month: 1.2
accessed_this_quarter: 1.0
older: 0.8
Refresh Triggers¶
REFRESH_TRIGGERS:
ACCESS:
Trigger: Episódio é consultado
Action: Reset decay, boost importance
REFERENCE:
Trigger: Episódio é citado em novo episódio
Action: Create connection, boost importance
VALIDATION:
Trigger: Episódio é confirmado como ainda válido
Action: Extend expiration, mark as validated
OUTCOME:
Trigger: Resultado de decisão é registrado
Action: Update outcome field, adjust importance based on success
7. Armazenamento Físico¶
Estrutura de Arquivos¶
DOCS/operations/memory/
├── README.md # Documentação
│
├── episodic/
│ ├── 2025-12/
│ │ ├── week-52.yaml # Episódios da semana
│ │ └── week-51.yaml
│ ├── 2025-11/
│ │ └── ...
│ ├── consolidated.yaml # Episódios importantes
│ └── index.yaml # Índice para busca
│
├── semantic/
│ ├── decisions.yaml # Decisões estratégicas
│ ├── facts.yaml # Fatos do negócio
│ ├── definitions.yaml # Glossário
│ ├── relationships.yaml # Relações entre entidades
│ └── constraints.yaml # Limites e restrições
│
├── procedural/
│ ├── workflows.yaml # Workflows documentados
│ ├── templates.yaml # Templates reutilizáveis
│ ├── patterns.yaml # Padrões aprendidos
│ └── heuristics.yaml # Regras de decisão
│
└── manager/
├── consolidation-log.yaml # Log de consolidações
├── decay-schedule.yaml # Schedule de decay
└── metrics.yaml # Métricas do sistema
Formato de Arquivo¶
# Example: episodic/2025-12/week-52.yaml
metadata:
week: 52
year: 2025
episode_count: 15
last_updated: "2025-12-28T16:00:00Z"
episodes:
- id: "ep_2025-12-28_001"
timestamp: "2025-12-28T14:30:00Z"
type: "decision"
summary: "Decisão de pricing para tier Basic"
# ... resto do schema
- id: "ep_2025-12-28_002"
# ...
8. Integração com Agentes¶
Como Agentes Usam Memória¶
AGENT_MEMORY_USAGE:
PRE_EXECUTION:
- Agente recebe contexto
- Memory Manager busca conhecimento relevante
- Agente recebe:
- Episódios similares (últimas 5)
- Fatos relacionados (semântica)
- Procedimentos aplicáveis
DURING_EXECUTION:
- Agente pode fazer RECALL
- Agente pode fazer LOOKUP
- Agente pode VALIDATE statements
POST_EXECUTION:
- Output é registrado como episódio
- Padrões são identificados
- Feedback é armazenado para learning
Memory Injection Template¶
MEMORY_INJECTION:
Format para injetar memória no contexto do agente:
"""
## Memória Relevante
### Episódios Anteriores
- [ep_001]: "[Resumo]" (outcome: [success/failure])
- [ep_002]: "[Resumo]" (outcome: [success/failure])
### Fatos Conhecidos
- [fact_001]: "[Statement]" (confidence: high)
- [fact_002]: "[Statement]" (confidence: medium)
### Procedimentos Aplicáveis
- [proc_001]: "[Nome do workflow]"
- [proc_002]: "[Nome do template]"
### Constraints Ativos
- [const_001]: "[Limitação]"
"""
9. Métricas do Sistema¶
MEMORY_METRICS:
# Volume
total_episodes: [count]
total_semantic_entries: [count]
total_procedures: [count]
storage_size_mb: [number]
# Usage
queries_per_day: [count]
recall_hit_rate: [% de queries com resultado]
avg_query_time_ms: [number]
# Quality
consolidation_rate: [episódios → semântica/procedural]
decay_rate: [% decayed per week]
validation_rate: [% de fatos revalidados]
# Learning
patterns_discovered: [count this month]
procedures_optimized: [count]
accuracy_improvement: [% vs baseline]
10. Comandos de Memória¶
# Recall de episódios
/memory recall "pricing decision"
# Lookup de fatos
/memory fact "CAC target"
# Buscar procedimento
/memory procedure "launch feature"
# Validar statement
/memory validate "Usamos OpenAI"
# Ver estatísticas
/memory stats
# Forçar consolidação
/memory consolidate
# Ver episódios recentes
/memory episodes --last 10
# Debug mode
/memory debug on
11. Integração com Sistema APEX¶
APEX_INTEGRATION:
ORCHESTRATOR.md:
- Orchestrator consulta memória para contexto
- Memória informa squad selection
- Outcomes alimentam episódica
LEARNING-SYSTEM.md:
- Memória é input para learning
- Patterns são detectados na episódica
- Learning atualiza procedural
AGENT-INTERFACES.md:
- Interfaces definem que memória agente acessa
- Inputs podem vir de semântica
- Outputs vão para episódica
WORKFLOWS.md:
- Workflows são procedural memory
- Execução gera episódios
- Outcomes otimizam workflows
MCP Tools:
- searchDocs → SEMANTIC
- getHypotheses → SEMANTIC (pending)
- addLearning → EPISODIC → SEMANTIC
- validateConsistency → SEMANTIC.VALIDATE
- logAgentUsage → EPISODIC (agent interactions)
- getAgentInsights → SEMANTIC (agent knowledge)
MCP Tools para Memória de Agentes (ADR-014)¶
Novas ferramentas MCP para memória de interações com agentes:
Tool: logAgentUsage¶
Registra cada interação com um agente para construir memória episódica:
logAgentUsage({
tenant: 'sellsync',
agentId: 'cfo',
query: 'Qual o impacto de aumentar preço?',
response: '[resposta do agente]',
context?: 'Discussão sobre pricing',
rating?: 'helpful' | 'neutral' | 'not_helpful'
})
Tool: getAgentInsights¶
Recupera conhecimento acumulado de interações passadas:
getAgentInsights({
tenant: 'sellsync',
agentId?: 'cfo', // Opcional: filtrar por agente
topic?: 'pricing', // Opcional: filtrar por tópico
limit?: 10, // Quantidade de insights
startDate?: '2026-01-01',
endDate?: '2026-01-31'
})
Fluxo de Memória¶
Consulta Agente → logAgentUsage → Memória Episódica
↓
Consolidação
↓
Memória Semântica
↓
getAgentInsights ← Próxima Consulta
Benefícios¶
- Consistência: Evita recomendações conflitantes entre sessões
- Aprendizado: Padrões de uso informam melhorias nos agentes
- Contexto: Agentes podem referenciar decisões anteriores
- Métricas: Rating permite identificar agentes mais úteis
Changelog¶
| Data | Mudança |
|---|---|
| 2025-12-28 | Criação inicial como parte do Sistema APEX Fase 4 |
| 2025-12-29 | Estrutura DOCS/operations/memory/ criada com README |
| 2026-01-17 | MCP Tools para memória de agentes (ADR-014) |