Memoria e Handoff entre Agentes

-- Tabela de memorias com tipos e relevancia
CREATE TABLE memories (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  tenant_id TEXT NOT NULL,
  content TEXT NOT NULL,
  memory_type TEXT NOT NULL,  -- 'preference', 'episodic', 'semantic'
  salience REAL DEFAULT 1.0,  -- 0.0 a 5.0 (maior = mais relevante)
  created_at INTEGER NOT NULL,
  accessed_at INTEGER NOT NULL,
  access_count INTEGER DEFAULT 0
);

-- Indice para busca rapida por tenant + tipo
CREATE INDEX idx_memories_tenant_type
  ON memories(tenant_id, memory_type);

-- Inserir uma memoria
INSERT INTO memories (tenant_id, content, memory_type, salience,
  created_at, accessed_at)
VALUES ('user_123', 'Prefere respostas em portugues',
  'preference', 4.0, unixepoch(), unixepoch());

-- Buscar memorias mais relevantes do usuario
SELECT content, memory_type, salience FROM memories
WHERE tenant_id = 'user_123'
ORDER BY salience DESC, accessed_at DESC
LIMIT 20;

// Exemplo com pgvector (via Supabase)
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(url, key)

// Gerar embedding do texto
const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Usuario prefere formato JSON para relatorios'
})

// Salvar memoria com embedding
await supabase.from('memories').insert({
  tenant_id: 'user_123',
  content: 'Usuario prefere formato JSON para relatorios',
  embedding: embedding.data[0].embedding,
  memory_type: 'preference'
})

// Buscar memorias semanticamente similares
const { data } = await supabase.rpc('match_memories', {
  query_embedding: queryEmbedding,
  match_threshold: 0.7,
  match_count: 10,
  filter_tenant: 'user_123'
})

# MEMORY.md - Memoria do Agente

## Preferencias do Usuario
- Idioma: portugues (Brasil)
- Tom: tecnico mas acessivel
- Formato preferido: exemplos de codigo antes de teoria

## Projetos Ativos
- SaaS de analytics: Next.js + Supabase, em producao
- Bot Telegram: TypeScript, multi-agente, em dev

## Decisoes Tomadas
- 2026-03-05: Escolheu SQLite para memoria (simplicidade)
- 2026-03-07: Migrou router de regras para LLM classifier
- 2026-03-09: Adicionou Codex como agente de codigo

interface HandoffMessage {
  from: string           // ID do agente remetente
  to: string             // ID do agente destinatario
  task: string           // Descricao da tarefa delegada
  context: {
    original_request: string    // O que o usuario pediu
    work_done: string           // O que ja foi feito
    results: any                // Dados produzidos
    constraints: string[]       // Restricoes a respeitar
  }
  conversation_summary: string  // Resumo da conversa ate aqui
  metadata: {
    timestamp: number
    turn_count: number
    tokens_used: number
  }
}

// Exemplo real
const handoff: HandoffMessage = {
  from: 'research-agent',
  to: 'writer-agent',
  task: 'Escrever artigo sobre MCP baseado na pesquisa',
  context: {
    original_request: 'Artigo tecnico sobre MCP para devs',
    work_done: 'Pesquisa completa: 5 fontes, 3 code samples',
    results: { sources: [...], code_samples: [...] },
    constraints: ['max 2000 palavras', 'tom tecnico', 'incluir exemplos']
  },
  conversation_summary: 'Usuario pediu artigo sobre MCP. ' +
    'Pesquisa concluida com 5 fontes oficiais.',
  metadata: { timestamp: Date.now(), turn_count: 4, tokens_used: 3200 }
}

// Estado compartilhado entre agentes (in-memory ou Redis)
interface SharedState {
  task_id: string
  user_id: string
  original_request: string
  agents: {
    [agentId: string]: {
      status: 'pending' | 'running' | 'done' | 'error'
      output: any
      updated_at: number
    }
  }
  conversation_history: Message[]
}

// Research agent atualiza seu output
state.agents['research'] = {
  status: 'done',
  output: { sources: [...], summary: '...' },
  updated_at: Date.now()
}

// Writer agent le o output do research
const researchResults = state.agents['research'].output
if (state.agents['research'].status === 'done') {
  // Pode comecar a escrever com os dados da pesquisa
}

-- Toda query DEVE incluir tenant_id
-- CORRETO:
SELECT * FROM memories
WHERE tenant_id = $1 AND memory_type = 'preference'
ORDER BY salience DESC;

-- ERRADO (data breach!):
SELECT * FROM memories
WHERE memory_type = 'preference'
ORDER BY salience DESC;

-- Funcao helper que forca o filtro
function getMemories(tenantId: string, type?: string) {
  if (!tenantId) throw new Error('tenant_id required')
  let query = db.prepare(
    'SELECT * FROM memories WHERE tenant_id = ?'
  )
  // Nunca permita query sem tenant_id
}

-- Habilitar RLS na tabela
ALTER TABLE memories ENABLE ROW LEVEL SECURITY;

-- Politica: usuario so ve suas proprias memorias
CREATE POLICY tenant_isolation ON memories
  FOR ALL
  USING (tenant_id = current_setting('app.current_tenant'));

-- Antes de cada request, setar o tenant
SET app.current_tenant = 'user_123';

-- Agora qualquer SELECT retorna apenas dados do user_123
-- Mesmo sem WHERE tenant_id =, o RLS filtra automaticamente
SELECT * FROM memories; -- so retorna dados do user_123

-- Supabase faz isso nativamente com auth.uid()
CREATE POLICY tenant_isolation ON memories
  FOR ALL
  USING (tenant_id = auth.uid());

// Pinecone: usar namespace por tenant
const index = pinecone.index('memories')

// Salvar no namespace do tenant
await index.namespace('tenant_user_123').upsert([{
  id: 'mem_001',
  values: embedding,
  metadata: { content: '...', type: 'preference' }
}])

// Buscar APENAS no namespace do tenant
const results = await index.namespace('tenant_user_123').query({
  vector: queryEmbedding,
  topK: 10,
  includeMetadata: true
})
// Impossivel acessar dados de outro namespace

async function compactConversation(messages: Message[], maxTokens: number) {
  const tokenCount = estimateTokens(messages)

  if (tokenCount < maxTokens * 0.8) return messages // Ainda tem espaco

  // Dividir: mensagens antigas (para sumarizar) e recentes (manter)
  const splitIndex = Math.floor(messages.length * 0.6)
  const oldMessages = messages.slice(0, splitIndex)
  const recentMessages = messages.slice(splitIndex)

  // Pedir ao LLM para sumarizar as mensagens antigas
  const summary = await llm.chat([
    { role: 'system', content: 'Resuma esta conversa em bullet points. ' +
      'Mantenha: decisoes tomadas, fatos importantes, tarefas pendentes. ' +
      'Descarte: saudacoes, perguntas ja respondidas, tentativas falhas.' },
    { role: 'user', content: JSON.stringify(oldMessages) }
  ])

  // Retornar: system prompt + resumo + mensagens recentes
  return [
    { role: 'system', content: `Resumo da conversa anterior:\n${summary}` },
    ...recentMessages
  ]
}

const extractionPrompt = `Analise esta conversa e extraia APENAS fatos
que o agente deve lembrar em sessoes futuras. Categorize cada fato:

- preference: Algo que o usuario prefere ou nao gosta
- decision: Uma decisao tomada sobre o projeto
- fact: Um fato objetivo sobre o usuario ou seu contexto
- task: Uma tarefa mencionada para o futuro

Formato JSON:
[{"content": "...", "type": "...", "salience": 1-5}]

Nao inclua:
- Saudacoes ou smalltalk
- Perguntas que ja foram respondidas
- Detalhes tecnicos transitorios (erros debugados, etc)
- Informacoes que o agente ja tem no system prompt`

// Resultado:
[
  {"content": "Usuario prefere TypeScript sobre JavaScript",
   "type": "preference", "salience": 4},
  {"content": "Decidiu usar Supabase em vez de Firebase",
   "type": "decision", "salience": 5},
  {"content": "Deadline do MVP e 15 de abril",
   "type": "fact", "salience": 5}
]

memory/
  index.ts             // Exporta MemoryManager unificado
  conversation.ts      // CRUD de historico de conversas
  preferences.ts       // CRUD de preferencias do usuario
  knowledge.ts         // CRUD de knowledge base + busca
  compaction.ts        // Sumarizacao e limpeza
  schema.sql           // DDL das tabelas

// Interface unificada
class MemoryManager {
  constructor(private db: Database, private tenantId: string) {}

  // Conversation history
  async saveMessages(messages: Message[]): Promise<void>
  async getRecentMessages(limit: number): Promise<Message[]>
  async compactIfNeeded(): Promise<boolean>

  // Preferences
  async setPreference(key: string, value: string): Promise<void>
  async getPreferences(): Promise<Record<string, string>>

  // Knowledge
  async addKnowledge(content: string, type: string): Promise<void>
  async search(query: string, limit: number): Promise<Knowledge[]>
  async extractFacts(conversation: Message[]): Promise<Fact[]>

  // Lifecycle
  async loadForPrompt(): Promise<string>  // Monta contexto pro system prompt
  async cleanup(): Promise<void>           // Decay, dedup, archive
}