🧠 Memória Incremental para Agentes de IA — Shared Memory com MCP

Código extraído da Blu Platform — um sistema multiagente real rodando em produção.

---

📋 TL;DR

• O que é: Sistema de memória compartilhada e incremental para múltiplos agentes de IA. Agentes escrevem fatos, decisões, descobertas e snapshots em um banco central e leem o contexto uns dos outros — sem precisar de conversas diretas.
• Arquitetura: MCP Server (Model Context Protocol) + SQLite (via adapters que substituem o Supabase original).
• Tamanho real: memory_module.py com 3.467 linhas, 13 tools MCP, pre/post-flight hooks, backup e prune automáticos.
• Para quem é: Curiosos, recrutadores e quem queira experimentar um pouco mais dos conceitos de IA.
• Licença: MIT — use, estude, adapte, critique.

---

🎯 O que este repositório contém

Este código extraído do monorepo da Blu Platform, uma plataforma multiagente B2B para empresas.

• ✅ Esteve em produção — cada linha foi escrita para resolver problemas reais de escalabilidade, concorrência e isolamento de tenants.
• ✅ Tem 3.467 linhas só no módulo de memória — validação de entidades, controle de permissão de escrita (Single Writer principle), TTL tiers, snapshots com frontmatter, grafos semânticos, soft-delete, export.
• ✅ É framework-agnostic — usa o protocolo MCP padrão, não um framework proprietário.
• ✅ Funciona offline — graças aos adapters SQLite que substituem o Supabase sem modificar código original.

Estrutura de diretórios

agent-shared-memory/
├── run.py                              # Entrypoint: monkey-patch + init + MCP server
├── pyproject.toml                      # Dependências mínimas (fastmcp, httpx, mcp)
│
├── libs/
│   └── blu_agent_framework/            # 🔵 CÓDIGO ORIGINAL
│       └── src/blu_agent_framework/
│           ├── handoff/
│           │   ├── handoff_hook.py              # Hook: escreve learning notes na handoff
│           │   └── shared_memory_context.py     # Loader: carrega contexto da shared memory
│           ├── onboarding/
│           │   └── onboarding_shared_memory_hook.py  # Hook pós-ETL onboarding
│           └── utils/
│               ├── llm_parse.py                 # Parsing de respostas LLM
│               └── observability.py             # Tracing e observabilidade
│
├── services/
│   ├── tool_pool_api/                  # 🔵 CÓDIGO ORIGINAL
│   │   └── src/tool_pool_api/server/tool_modules/
│   │       ├── memory_module.py        # ★ 3.467 linhas — 13 tools MCP
│   │       ├── memory_pre_flight.py    # Hook pré-execução (lê contexto)
│   │       ├── memory_post_flight.py   # Hook pós-execução (persiste resultados)
│   │       └── utils/entity.py         # Validação e normalização de entidades
│   │
│   └── routine_engine/                 # 🔵 CÓDIGO ORIGINAL
│       └── src/routines/
│           ├── backup_shared_memory.py # Backup diário (dump + gzip + storage)
│           └── prune_shared_memory.py  # Limpeza automática (soft/hard delete)
│
└── adapters/                           # 🟢 ADAPTADOS (SQLite no lugar de Supabase)
    ├── blu_supabase_client/            # ★ SQLite fake do Supabase client
    ├── blu_auth/                       # Stub de autenticação
    ├── blu_context_service/            # Stub de schemas de contexto
    └── tool_pool_api/                  # Stub do módulo tool_pool_api

---

📁 Estrutura

Diretório	O que é	Tipo
libs/blu_agent_framework/	Handoff hooks, shared memory context loader, onboarding hook pós-ETL	🔵 Original
services/tool_pool_api/	MCP Server de memória com 13 tools, pre-flight hook, post-flight hook	🔵 Original
services/routine_engine/	Backup diário com compressão gzip + prune automático com soft/hard delete	🔵 Original
adapters/	Stubs SQLite que substituem Supabase (Auth, Context Service, Storage)	🟢 Adaptado

---

🏗 Como funciona

┌──────────────────────────────────────────────────────────────────┐
│                    SHARED BUSINESS MEMORY                        │
│                                                                  │
│  ┌──────────┐     ┌──────────────────────┐     ┌──────────┐     │
│  │ Agente A │ ──→ │   MCP Server (FastMCP)│ ←── │ Agente B │     │
│  │ (Escrita)│     │  memory_module.py     │     │ (Leitura)│     │
│  └──────────┘     └──────────┬───────────┘     └──────────┘     │
│                              │                                   │
│                              ▼                                   │
│               ┌──────────────────────────┐                      │
│               │    SQLite / Supabase      │                      │
│               │  shared_business_memory   │                      │
│               │  shared_memory_links      │                      │
│               │  shared_business_memory_meta                     │
│               └──────────────────────────┘                      │
│                                                                  │
│  Fluxo típico:                                                   │
│    Agent A → shared_memory_write → SQLite → shared_memory_read → Agent B │
│                                                                  │
│  Ciclo de vida:                                                  │
│    shared_memory_upsert → backup (02:00) → prune (03:00)         │
└──────────────────────────────────────────────────────────────────┘

Conceitos-chave

Entidades: 9 tipos validados — skill, client, contact, supplier, user, snapshot, routine, agent_result, agent_metadata.

Single Writer Principle: Cada source só pode escrever em entity_types específicos. Exemplo: source='manual' não pode escrever snapshot ou routine.

TTL Tiers: 5 níveis de retenção — curated (nunca expira), migration (90d), specialist (30d), memory_agent_hi (14d), memory_agent_lo (7d). Após soft-delete, +90 dias para hard-delete definitivo.

Semantic Links: Relacionamentos nomeados entre entidades (works_for, prefers, depends_on, etc.) com grafo navegável via BFS.

Auto-linking: Ao escrever um fato, o sistema detecta automaticamente referências a outras entidades no formato [label](entity_type:entity_name) e cria links.

---

🔧 MCP Tools

Todas as 13 tools expostas pelo servidor MCP:

Tool	Descrição	Operação
shared_memory_list	Lista entidades com entradas de memória	Leitura
shared_memory_read	Lê um fato específico (chave composta)	Leitura
shared_memory_upsert	Insere ou atualiza um fato (versionado)	Escrita
shared_memory_meta_upsert	Insere/atualiza meta entry (pipeline data)	Escrita
shared_memory_write	Escreve novo fato (strict INSERT ou upsert)	Escrita
shared_memory_search	Busca semântica via embeddings (Cohere)	Leitura
shared_memory_flush	Soft-delete (marca flushed_at no metadata)	Deleção
shared_memory_link	Cria link semântico entre entidades	Escrita
shared_memory_unlink	Remove link por ID	Deleção
shared_memory_get_links	Consulta links por entidade e/ou tipo	Leitura
shared_memory_meta_read	Lê meta entry da shared_business_memory_meta	Leitura
shared_memory_meta_list	Lista meta entries (opcional: filtro por tipo)	Leitura
shared_memory_export	Exporta todos os fatos do cliente (backup/analytics)	Leitura
shared_memory_graph	Navega o grafo semântico (BFS, shortest path, cluster)	Leitura
shared_memory_pre_flight	Lê contexto de execuções recentes do agente (internal)	Leitura

---

🚀 Quick Start

# 1. Clone e instale
git clone https://github.com/seu-usuario/agent-shared-memory.git
cd agent-shared-memory
pip install .

# 2. Inicialize o banco SQLite
python run.py --init

# 3. Inicie o servidor MCP
python run.py

# Opcional: porta e host customizados
python run.py --host 0.0.0.0 --port 8000

# Banco customizado
python run.py --db /path/to/memory.db

O servidor inicia em http://0.0.0.0:8000 e expõe as tools MCP via transporte HTTP padrão.

---

🔧 Adapters — Por que existem

O código original depende do Supabase (banco PostgreSQL gerenciado, autenticação, storage). Para tornar o repositório executável localmente sem modificar uma linha do código original, criamos adapters que implementam a mesma interface do Supabase usando SQLite puro.

Código original (memory_module.py)
         │
         ▼  import blu_supabase_client
         │
    ┌────┴────┐
    │ Adapter │  ← SQLite puro, mesma API do Supabase
    └─────────┘
         │
         ▼  SQLite local (shared_memory.db)

O que os adapters fazem:

Adapter	Original	Substituído por
blu_supabase_client/	Supabase REST client + PostgreSQL	SQLite com query builder compatível
blu_auth/	Auth0 / JWT validation	Stub que sempre retorna autenticado
blu_context_service/	Context schemas remotos	Constantes locais
tool_pool_api/	Módulo de registro de tools	Stub de módulo

O resultado: o memory_module.py de 3.467 linhas roda sem alterações — o adapter faz ponte entre a interface que o código espera (Supabase) e a implementação local (SQLite).

---

🧠 Conceitos de Design

Memória Incremental, não Conversacional

Agentes não conversam entre si. Eles escrevem fatos em uma memória compartilhada indexada por (client_id, entity_type, entity_name, key) e leem os fatos que outros agentes escreveram. Isso elimina:

• 🔴 Acoplamento temporal (agentes precisariam estar online ao mesmo tempo)
• 🔴 Perda de contexto em handoffs
• 🔴 Duplicação de informações entre agentes

Ciclo de Vida Completo

1. Escrita → shared_memory_write / shared_memory_upsert
2. Leitura → shared_memory_read / shared_memory_list
3. Backup → backup_shared_memory.py (diário 02:00 UTC)
4. Soft-delete → prune_shared_memory.py (diário 03:00 UTC)
5. Hard-delete → prune_shared_memory.py (após 90 dias do soft-delete)

Pre-flight / Post-flight Hooks

• Pre-flight: Antes de um agente executar, carrega seu contexto recente (agent_metadata + agent_results) da shared memory. Fail-open: se falhar, retorna contexto vazio.
• Post-flight: Após a execução, persiste resultados, decisões, descobertas e metadados da execução na shared memory. Fire-and-forget: nunca bloqueia o usuário.

Onboarding Hook

Quando uma nova empresa é cadastrada, o hook onboarding_shared_memory_hook.py escreve o snapshot inicial (company profile, brand voice, goals) na shared memory — pronto para qualquer agente consumir.

---

🏗 Arquitetura dos Adapters

O adapter blu_supabase_client implementa:

get_supabase_client() → _SupabaseClient
    ├── .table("shared_business_memory") → _QueryBuilder
    │       .select("*")
    │       .eq("client_id", "...")
    │       .eq("entity_type", "skill")
    │       .order("updated_at", desc=True)
    │       .limit(10)
    │       .execute() → _SupabaseResponse(data=[...], count=N)
    │
    ├── .storage.from_("bucket").upload(path, file)
    └── .rpc("function_name", {...}).execute()

Tabelas SQLite criadas automaticamente:

• shared_business_memory — fatos principais (UNIQUE em client_id, entity_type, entity_name, key)
• shared_memory_links — links semânticos entre entidades
• shared_business_memory_meta — metadados operacionais (synthesis, dedup, kg)

---

📜 Licença

MIT. Use, estude, modifique, critique, distribua.
Código original da Blu Platform, extraído e adaptado para a comunidade.

---

Feito com ☕ e 🧠 por engenheiros que acreditam que agentes de IA precisam de memória compartilhada, não de chatrooms.