sinapse-ai 9.3.0 → 9.4.0

package/squads/squad-cloning/knowledge-base/memory-architecture-for-clones.md

@@ -0,0 +1,229 @@
+# Memory Architecture for Clones — Infraestrutura Cognitiva
+
+> Como estruturar a memoria operacional de um clone cognitivo para que ele
+> recupere o conhecimento certo, no momento certo, ao custo minimo.
+> Baseado em: MS-009 Agentic Second Brain (A-Mem, Mem0, Letta, ContextForge, Graphiti).
+
+---
+
+## Por Que Memoria Importa Para Clones
+
+Um clone sem arquitetura de memoria adequada recai em dois problemas:
+
+1. **Context flooding:** Joga tudo no context window — degrada qualidade, aumenta custo
+2. **Context starvation:** Deixa conhecimento critico fora do contexto — produz respostas genéricas
+
+A solucao e um sistema de tres tiers que simula como humanos realmente recuperam conhecimento.
+
+---
+
+## Os Tres Tiers de Memoria
+
+```
+HOT  ← Context Window Ativo (~20K tokens)
+  |
+  | promocao semantica automatica
+  |
+WARM ← Vector DB + Knowledge Graph (<300ms retrieval)
+  |
+  | recuperacao sob demanda
+  |
+COLD ← Filesystem + Archive (segundos)
+```
+
+### HOT Memory — O Que Fica Sempre Presente
+
+Conteudo que deve estar SEMPRE no system prompt do clone:
+
+```
+[Identity Block]        ~1.500 tokens
+  - Core axiom (L5)
+  - 5-6 core principles (L1 top)
+  - Communication tone + greeting (L4)
+  - Failure modes e boundaries (L6)
+
+[Active Heuristics]     ~3.000 tokens
+  - Top 8-10 heuristics mais invocadas (L2)
+  - Gatilhos de ativacao explícitos
+
+[Task Context]          ~15.000 tokens (dinamico)
+  - Tarefa atual
+  - Historico recente da conversa
+  - Resultados de retrieval WARM relevantes
+```
+
+**Budget total HOT:** ~20K tokens (10% de uma janela de 200K)
+
+### WARM Memory — Conhecimento Recuperavel Rapidamente
+
+Indexado em vector DB (semantico) + knowledge graph (estrutural):
+
+| Conteudo | Storage | Latencia |
+|---------|---------|---------|
+| Heuristics completas (L2) | Vector + Graph | <100ms |
+| Workflows detalhados (L3) | Vector + Graph | <150ms |
+| KBs do clone (todos os tipos) | Vector | <200ms |
+| Exemplos concretos e casos | Vector | <200ms |
+| Meta-patterns (L5) | Graph traversal | <300ms |
+
+**Trigger de promocao para HOT:** Relevancia semantica com a tarefa atual.
+Uma heuristic de pricing fica COLD quando o assunto e copywriting — mas e
+promovida para HOT imediatamente quando o assunto muda para estrategia de preco.
+
+### COLD Memory — Arquivo Historico
+
+Fontes brutas e material de referencia:
+
+- Transcricoes completas das fontes originais
+- KBs nao-relevantes para tarefa atual
+- Historico de versoes do perfil cognitivo
+- Material de suporte (livros, artigos completos)
+
+**Acesso:** Apenas quando o agente precisa citar fonte original ou aprofundar
+alem do que o WARM contem.
+
+---
+
+## Implementacao no agent.md
+
+### Secao de Memory Configuration
+
+```yaml
+memory_architecture:
+  hot:
+    always_loaded:
+      - identity_block          # identity + core principles
+      - communication_style     # L4 completo
+      - failure_modes           # L6 completo
+      - top_heuristics          # Top 8 heuristics (L2)
+    token_budget: 20000
+
+  warm:
+    retrieval_triggers:
+      - task_semantic_match     # Query semantica contra KBs
+      - entity_mention          # Nome de topico mencionado na conversa
+      - domain_switch           # Mudanca de dominio na conversa
+    index_sources:
+      - heuristics_complete     # Todas as heuristics (L2)
+      - workflows               # Todos os workflows (L3)
+      - knowledge_bases         # Todos os KBs gerados
+      - examples                # Casos e exemplos concretos
+
+  cold:
+    on_demand:
+      - source_transcriptions
+      - full_kb_archive
+      - version_history
+```
+
+---
+
+## Tipos de Memoria por Analogia Humana
+
+| Tipo Humano | Analogia Cognitiva | Layer | Como Implementar |
+|-------------|-------------------|-------|-----------------|
+| **Working Memory** | O que esta "na ponta da lingua" agora | Contexto ativo da tarefa | HOT — Slot dinamico |
+| **Semantic Memory** | Conhecimento geral sobre o mundo | L1 Mental Models | WARM/COLD — Knowledge Graph |
+| **Procedural Memory** | Saber fazer sem pensar | L3 Workflows | WARM — Recuperado por dominio de tarefa |
+| **Episodic Memory** | Lembrar de eventos especificos | Casos e exemplos | WARM — Vector search |
+| **Autobiographic Memory** | Quem sou eu, minha historia | Identity + Meta-patterns | HOT — Identity Block |
+
+---
+
+## Estrategia de Context Engineering por Tier de Clone
+
+### Tier 1 (KB-only)
+Sem agente — KBs sao consultados diretamente.
+Nao ha memory architecture formal.
+
+### Tier 2 (Consultant Clone)
+```
+System Prompt:
+  HOT: Identity + Top 5 heuristics + Communication style
+  
+Per-turn:
+  WARM: Recuperar 2-3 heuristics relevantes + 1-2 KBs relevantes
+  Budget: ~30K tokens total
+```
+
+### Tier 3 (Full Clone)
+```
+System Prompt:
+  HOT: Identity completo + Top 10 heuristics + Workflows key + Failure modes
+  
+Per-turn:
+  WARM: Hybrid retrieval (BM25 + embeddings) contra KBs completos
+  Budget: ~80K tokens (40% de janela de 200K)
+  
+On-demand:
+  COLD: Fontes originais para citacao ou verificacao
+```
+
+---
+
+## Token Budget por Layer do DNA
+
+Guia para alocar o context window do clone:
+
+| Conteudo | Tier 2 | Tier 3 | Notas |
+|---------|--------|--------|-------|
+| Identity + Core Axiom | 800 | 1.500 | Sempre HOT |
+| Core Principles (L1) | 1.200 | 2.000 | Sempre HOT |
+| Top Heuristics (L2) | 2.000 | 4.000 | Sempre HOT |
+| Communication Style (L4) | 800 | 1.200 | Sempre HOT |
+| Failure Modes (L6) | 500 | 1.000 | Sempre HOT |
+| Task-retrieved KBs | 5.000 | 15.000 | WARM → HOT |
+| Conversation history | 3.000 | 10.000 | HOT dinamico |
+| **TOTAL** | **~13K** | **~35K** | Dentro do budget |
+
+---
+
+## Content Decay para Memorias de Clone
+
+Assim como vaults de Second Brain degradam, a memoria do clone pode ficar desatualizada.
+
+### Tipos de Decay
+
+| Tipo | Exemplo | Deteccao |
+|------|---------|---------|
+| **Factual Decay** | Preco que o original praticava mudou | Comparar com fontes recentes |
+| **Opiniao Evoluida** | Mudou de posicao sobre topico | Comparar fontes temporais |
+| **Contexto Obsoleto** | Heuristic baseada em mercado que mudou | Checar timestamp da fonte |
+| **Terminologia** | Usava X, agora usa Y para o mesmo conceito | Analise de vocabulario temporal |
+
+### Protocolo de Review
+
+- **Heuristics taticas (L2):** Review anual — mudam com mercado
+- **Mental Models (L1):** Review bienal — mais estaveis
+- **Communication Patterns (L4):** Review anual — evolucao do estilo
+- **Meta-patterns (L5):** Review a cada 3-5 anos — muito estaveis
+- **Workflows (L3):** Review semestral — praticas evoluem rapido
+
+---
+
+## Hybrid Retrieval para Clones
+
+Para WARM memory, usar hybrid search (BM25 + embeddings) ao inves de apenas vector:
+
+```
+[Query da conversa]
+  |
+  +-- BM25 (keyword) ---------> KBs com termos exatos
+  |
+  +-- Embeddings (semantic) --> KBs semanticamente proximos
+  |
+  +-- Graph traversal ---------> KBs conectados por entidade
+  |
+  +-- RRF (fusion) ------------> Top-5 KBs mais relevantes
+  |
+  +-- Injeta no HOT ------------> Context window enriquecido
+```
+
+**Por que BM25 ainda importa:** Para nomes proprios, frameworks nomeados
+("Hormozi Offer Framework"), e termos tecnicos — BM25 supera embeddings.
+
+**Resultado esperado:** ~35% reducao em respostas genericas comparado com
+retrieval apenas semantico (baseado em resultados do benchmark LongMemEval).
+
+Ver tambem: `confidence-scoring.md` para pesos por tipo de extracao.
+Ver tambem: `extraction-patterns.md` para como popular a WARM memory.

package/squads/squad-cloning/knowledge-base/multi-agent-deployment-patterns.md

@@ -0,0 +1,320 @@
+# Multi-Agent Deployment Patterns — Clones em Sistemas Multi-Agente
+
+> Como integrar clones cognitivos em sistemas multi-agente (CrewAI, LangGraph,
+> AutoGen/AG2, OpenAI Agents SDK, Claude Agent SDK).
+> Como clones funcionam como nodes em orquestrações maiores.
+> Baseado em: MS-009 Sistema 5 — Agent, Subagent & Skills Modeling.
+
+---
+
+## Contexto: O Mercado de Frameworks (Abril 2026)
+
+| Framework | Status | Ideal Para |
+|-----------|--------|-----------|
+| **LangGraph** | Producao — High maturity | Fluxos complexos, state machines, producao enterprise |
+| **CrewAI** | Producao — High maturity | Prototipagem rapida, equipes conceituais de agentes |
+| **Claude Agent SDK** | Producao — High maturity | Ecossistema Claude nativo, tool use, file checkpointing |
+| **OpenAI Agents SDK** | Producao — High maturity | Ecossistema OpenAI, handoffs, guardrails |
+| **Google ADK** | Producao — High maturity | Ecossistema Gemini, lancado Cloud NEXT 2025 |
+| **Microsoft Agent Framework** | Novo (2026) | Substitui AutoGen + Semantic Kernel unificados |
+| **AutoGen/AG2** | Maintenance mode | Fork comunitario (ag2ai/ag2) — nao recomendado para novos projetos |
+
+**Nota importante (Abril 2026):** Microsoft aposentou AutoGen em favor do
+Microsoft Agent Framework. AutoGen recebe apenas bug fixes e security patches.
+A comunidade mantém o fork AG2 independente.
+
+---
+
+## Padrao 1: Clone como Especialista no CrewAI
+
+O padrao mais simples — o clone e um "agent" dentro de uma crew:
+
+```python
+from crewai import Agent, Task, Crew
+
+clone_hormozi = Agent(
+    role="Alex Hormozi Clone — Offer Creation Expert",
+    goal="Analyze and create high-value offers using Hormozi's documented methodology",
+    backstory="""
+    You are a cognitive clone of Alex Hormozi, with 88% confidence score (Tier 3).
+    Your expertise is in offer creation, business acquisition, and scaling.
+    Core principle: 'The value equation determines everything about an offer.'
+    You speak directly, use simple language, and always quantify.
+    You decline to advise on: accounting, legal matters, technical implementation.
+    Based on documented sources: DotCom Secrets, Expert Secrets, $100M Offers, podcasts.
+    """,
+    verbose=True,
+    allow_delegation=False  # Clone nao delega — ele e o especialista
+)
+
+task_offer_review = Task(
+    description="Review this offer and improve it using Alex Hormozi's documented methodology",
+    agent=clone_hormozi,
+    expected_output="Revised offer with rationale based on documented Hormozi principles"
+)
+```
+
+### Regras para Clone em CrewAI
+
+1. **allow_delegation=False:** Clone e especialista terminal, nao orquestrador
+2. **backstory inclui confidence score:** Transparencia sobre qualidade
+3. **backstory inclui failure modes:** "You decline to advise on X"
+4. **backstory inclui fonte:** "Based on documented sources: ..."
+5. **Nome do role menciona "Clone":** Deixa claro que e representacao
+
+---
+
+## Padrao 2: Clone como Node no LangGraph
+
+Para fluxos mais complexos com state management:
+
+```python
+from langgraph.graph import StateGraph, State
+from typing import TypedDict
+
+class CloningState(TypedDict):
+    query: str
+    clone_response: str
+    confidence_used: float
+    sources_activated: list[str]
+
+def hormozi_clone_node(state: CloningState) -> CloningState:
+    """
+    Node que implementa o clone Hormozi.
+    Carrega memory WARM sob demanda baseado na query.
+    """
+    # Retrieval WARM para a query especifica
+    relevant_kbs = retrieve_warm_memory(
+        query=state["query"],
+        clone_id="alex-hormozi",
+        top_k=3
+    )
+    
+    # Montar contexto: HOT (always) + WARM (retrieved)
+    system_prompt = build_clone_context(
+        hot_memory=HORMOZI_HOT_MEMORY,  # Sempre carregado
+        warm_memory=relevant_kbs
+    )
+    
+    response = claude_invoke(
+        system=system_prompt,
+        message=state["query"]
+    )
+    
+    return {
+        **state,
+        "clone_response": response,
+        "confidence_used": 0.88,
+        "sources_activated": [kb.name for kb in relevant_kbs]
+    }
+
+# Construir o grafo
+workflow = StateGraph(CloningState)
+workflow.add_node("hormozi_clone", hormozi_clone_node)
+workflow.add_node("quality_validator", validate_clone_output)
+workflow.add_edge("hormozi_clone", "quality_validator")
+```
+
+### Vantagens do LangGraph para Clones
+
+- **Traceable:** Cada decisao do clone e rastreavel no grafo
+- **Interruptible:** Pode pausar para revisao humana em pontos criticos
+- **State management:** Mantém contexto entre multiplos turnos
+- **Conditional routing:** Pode rotear para clone diferente baseado no topico
+
+---
+
+## Padrao 3: Clone como Subagente no Claude Agent SDK
+
+Para integracao nativa com Claude Code e ecossistema Anthropic:
+
+```markdown
+# Agent Definition: clone-{source-mind}
+
+---
+name: clone-alex-hormozi
+description: >
+  Cognitive clone of Alex Hormozi (88% confidence, Tier 3).
+  Specialist in offer creation, business acquisition, and scaling.
+  Use when: offer analysis, pricing strategy, business growth.
+model: claude-sonnet-4-6
+tools:
+  - Read  # Para acessar KBs
+allowed_tools: Read
+---
+
+You are a cognitive clone of Alex Hormozi...
+{system prompt completo do agent.md}
+```
+
+```python
+# Invocacao via Claude Agent SDK
+import anthropic
+
+client = anthropic.Anthropic()
+
+# Carregar o clone como subagente
+result = client.agents.run(
+    agent_id="clone-alex-hormozi",
+    messages=[{"role": "user", "content": "Analise esta oferta..."}]
+)
+```
+
+---
+
+## Padrao 4: Multi-Clone Panel (Debate de Perspectivas)
+
+Padrao avancado: multiplos clones debatem um problema:
+
+```python
+from crewai import Agent, Task, Crew, Process
+
+# Definir 3 clones com perspectivas diferentes
+hormozi_clone = Agent(
+    role="Alex Hormozi Clone — Offer & Scale Expert",
+    backstory="...",
+    allow_delegation=False
+)
+
+brunson_clone = Agent(
+    role="Russell Brunson Clone — Funnel & Persuasion Expert",
+    backstory="...",
+    allow_delegation=False
+)
+
+halbert_clone = Agent(
+    role="Gary Halbert Clone — Direct Response Copywriting Expert",
+    backstory="...",
+    allow_delegation=False
+)
+
+synthesizer = Agent(
+    role="Synthesis Agent",
+    goal="Identify common ground and unique insights from multiple perspectives",
+    backstory="You synthesize diverse expert perspectives without bias",
+    allow_delegation=False
+)
+
+tasks = [
+    Task(
+        description="Analyze this marketing campaign from your documented perspective",
+        agent=hormozi_clone
+    ),
+    Task(
+        description="Analyze this marketing campaign from your documented perspective",
+        agent=brunson_clone
+    ),
+    Task(
+        description="Analyze this marketing campaign from your documented perspective",
+        agent=halbert_clone
+    ),
+    Task(
+        description="Synthesize the three perspectives into actionable recommendations",
+        agent=synthesizer,
+        context=[task1, task2, task3]  # Recebe outputs dos outros
+    )
+]
+
+panel = Crew(
+    agents=[hormozi_clone, brunson_clone, halbert_clone, synthesizer],
+    tasks=tasks,
+    process=Process.sequential
+)
+```
+
+### Quando Usar Multi-Clone Panel
+
+- Decisoes estratégicas onde perspectivas diferentes agregam valor
+- Criacao de conteudo que precisa de "best of all worlds"
+- Auditoria de estratégias (cada clone testa sua lente)
+- Treinamento/educacao (ver como diferentes experts abordam o mesmo problema)
+
+**Limitacao:** O custo aumenta linearmente com o numero de clones. Para
+producao, usar apenas quando o valor adicional justifica o custo.
+
+---
+
+## Padrao 5: Clone com Memory Persistente (Letta/MemGPT)
+
+Para clones que precisam lembrar de interacoes anteriores:
+
+```python
+from letta import create_client
+
+client = create_client()
+
+# Criar agente com memoria persistente
+clone_agent = client.create_agent(
+    name="clone-alex-hormozi",
+    memory=ChatMemory(
+        human="User building a SaaS product",
+        persona="You are a cognitive clone of Alex Hormozi..."
+    ),
+    system=HORMOZI_SYSTEM_PROMPT,
+    tools=["core_memory_append", "core_memory_replace", "archival_memory_search"]
+)
+
+# Interagir — o clone lembra de conversas anteriores
+response_1 = client.send_message(
+    agent_id=clone_agent.id,
+    message="Meu produto atual e X com preco Y"
+)
+
+# Em sessao futura, o clone lembra do contexto
+response_2 = client.send_message(
+    agent_id=clone_agent.id,
+    message="Devo mudar o preco?"
+    # Clone lembra: "produto X com preco Y" da sessao anterior
+)
+```
+
+### Quando Usar Memory Persistente
+
+- Clone que atua como consultor recorrente para o mesmo usuario/empresa
+- Quando o contexto acumula ao longo de semanas/meses
+- Quando o clone precisa "aprender" sobre o contexto especifico do usuario
+
+**Atencao:** Memory persistente aumenta complexidade e custo. Usar apenas quando
+o beneficio de lembrar o contexto e claro e recorrente.
+
+---
+
+## Governance de Clones em Sistemas Multi-Agente
+
+### Regras de Autoridade
+
+| Operacao | Clone pode fazer? | Notas |
+|---------|-------------------|-------|
+| Responder perguntas no dominio | Sim | Dentro de confidence score |
+| Dar recomendacoes | Sim, com contextualizacao | "Baseado no que [nome] documentou..." |
+| Executar acoes (codigo, escrita) | Sim, se ferramentas permitidas | Depende de `allowed_tools` |
+| Apresentar-se como a pessoa real | NAO | Sempre como "clone cognitivo" |
+| Opinar em areas fora do dominio | Com disclaimer | Marcar como fora do escopo |
+| Criar conteudo "no nome de" sem supervisao | Nao recomendado | Ver ethical-guidelines.md |
+
+### Handoff Protocol para Clones
+
+Quando o clone recebe uma pergunta fora do seu dominio:
+
+```
+Resposta padrao:
+"Isso esta alem do que {Nome} documenta extensivamente.
+Baseado nas suas fontes, o mais proximo que posso chegar e [X].
+Para conselho especializado em [area], recomendo [recurso]."
+```
+
+---
+
+## Metricas de Performance em Producao
+
+| Metrica | Meta | Alertar se |
+|---------|------|-----------|
+| Clone activation rate | > 80% das perguntas no dominio | < 60% |
+| Out-of-domain rate | < 15% das respostas | > 25% |
+| Confidence tag compliance | 100% das extracoes tagadas | < 95% |
+| Fidelity score (por sampling) | >= 70% | < 55% |
+| Boundary violation rate | < 2% | > 5% |
+
+Ver tambem: `memory-architecture-for-clones.md` para como estruturar a memoria.
+Ver tambem: `clone-quality-assurance.md` para validacao de fidelidade.
+Ver tambem: `ethical-guidelines.md` para uso etico em sistemas automatizados.