Skip to main content
Glama
CidLucas

agent-shared-memory

by CidLucas
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🧠 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.

Related MCP server: server-memory

🎯 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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • tartarus-mcp

    saluca-labs
    A
    license
    Not graded
    quality
    C
    maintenance
    A local-first MCP memory server providing persistent, searchable memory for AI agents, powered by SQLite.
    1 npm
    1
    Apache 2.0

  • server-memory

    MK-986123
    A
    license
    A
    quality
    C
    maintenance
    A local-first MCP server for durable agent memory using SQLite and FTS5, enabling knowledge graph storage, search, and recall for AI agents.
    20
    1
    MIT

  • heropen

    Koradji77
    A
    license
    Not graded
    quality
    A
    maintenance
    A local memory server for AI agents that stores and retrieves information via MCP, keeping all data in SQLite on your machine.
    1
    Apache 2.0

  • supermem

    lamenting-hawthorn
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server providing persistent AI memory with four-tier retrieval (SQLite FTS5, graph, vector, LLM agent) to give AI assistants structured, long-term memory without RAG.
    1
    Apache 2.0