agent-shared-memory
Provides integration with LangGraph for handoff patterns, allowing agents to share context via shared memory.
🧠 Agente com Memória Incremental (Shared Memory)
Dê memória persistente aos seus agentes de IA — sem banco vetorial.
TL;DR
O maior problema dos agentes de IA hoje não é alucinação — é amnésia.
Seu agente faz uma tarefa brilhante, mas na próxima interação, não lembra de nada. Cada conversa começa do zero. Você pergunta algo ao agente CRM, e 5 minutos depois o agente Financeiro não sabe nem o nome do cliente.
Este repositório resolve isso com um MCP Server de memória compartilhada que usa SQLite como backend. Múltiplos agentes podem ler e escrever conhecimento compartilhado entre si, com categorias, TTL, links semânticos e isolamento multi-tenant.
Related MCP server: tartarus-mcp
Sumário
🔥 O Problema
Imagine que você tem dois agentes de IA trabalhando para o seu negócio:
Agente CRM — descobre informações sobre um cliente
Agente Financeiro — analisa a saúde financeira desse cliente
O fluxo ideal seria:
Agente CRM descobre → passa contexto → Agente Financeiro analisaNa prática, sem memória compartilhada:
Agente CRM: "Cliente: Acme Corp, faturamento R$ 50M/ano" ✅
Agente Financeiro: "Quem é Acme Corp? 🤷" ❌Cada agente começa do zero. O contexto não flui. É como ter dois especialistas que trabalham em salas diferentes sem nunca se falarem.
A solução: uma Shared Memory — um "caderninho" onde qualquer agente pode anotar fatos e onde qualquer agente pode consultar.
🏗 A Arquitetura
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ AGENTE CRM │ │ AGENTE FIN │ │ AGENTE EXEC │
│ (escrita) │ │ (leitura) │ │ (consolida) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ HTTP/MCP │ HTTP/MCP │ HTTP/MCP
▼ ▼ ▼
┌──────────────────────────────────────────────────────┐
│ MCP SHARED MEMORY SERVER │
│ tools: write / read / search / upsert / flush │
│ + links + export │
└───────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────┐
│ SQLite │
│ shared_memory │
│ shared_memory_ │
│ links │
└─────────────────┘Componentes:
Componente | O que faz |
| Servidor MCP com FastMCP. Expõe tools via HTTP. |
| Cliente Python. Agentes chamam |
| Função |
| Schema SQLite + dataclasses + constantes (TTL, categorias, etc.). |
✨ Features
Feature | Descrição |
Write/Read | Agentes escrevem e leem fatos sobre entidades (clientes, contatos, fornecedores...) |
Upsert | Atualiza fato existente sem duplicar |
Links Semânticos | Relacione entidades: |
Categorias |
|
TTL Tiers |
|
Soft-Delete | Marque entradas como flushed — continuam no banco mas não são retornadas |
Busca Textual | LIKE search em todas as entradas |
Export | Exporte todos os dados de um tenant |
Multi-Tenant |
|
MCP Protocol | Funciona com qualquer framework MCP-compatível (LangGraph, Agno, etc.) |
🚀 Quick Start
# 1. Clone
git clone https://github.com/CidLucas/agent-shared-memory.git
cd agent-shared-memory
# 2. Instale dependências
pip install .
# 3. Inicialize o banco
python -m src.main --init
# 4. Inicie o servidor (Terminal 1)
python -m src.main
# 5. Rode o exemplo básico (Terminal 2)
python examples/basic_usage.pyPré-requisitos
Python 3.11+
pip install .instalafastmcp,httpx,mcp
🔄 Exemplo: Handoff Multi-Agente
O exemplo mais poderoso: 3 agentes que compartilham memória sem se comunicarem diretamente.
# === AGENTE CRM: descobre e salva ===
await memory.write(
entity_type="client",
entity_name="tech_solutions",
key="company_profile",
value={
"nome": "Tech Solutions Ltda",
"faturamento_mensal": 850000,
"funcionarios": 45,
"segmento": "B2B",
},
source="memory_agent",
ttl_tier="memory_agent_hi", # 14 dias
)
# === AGENTE FINANCEIRO: lê e adiciona análise ===
context = await memory.read(entity_name="tech_solutions")
# → {"tech_solutions": {"company_profile": {...}}}
await memory.write(
entity_type="client",
entity_name="tech_solutions",
key="analise_financeira",
value={
"receita_anual": 10200000,
"margem_liquida": 0.24,
"score_credito": "AA",
},
source="memory_agent",
category="decision",
)
# === AGENTE EXECUTIVO: consolida tudo ===
from src.agent_integration import load_shared_memory_context
contexto = await load_shared_memory_context(
agent_type="executivo",
entity_names=["tech_solutions", "carlos_silva"],
memory_client=memory,
)
# contexto → {"tech_solutions": {"company_profile": {...}, "analise_financeira": {...}}}👉 Veja o exemplo completo em: examples/agent_handoff.py
📋 API das Tools (MCP)
Tool | Descrição | Parâmetros principais |
| Escrever um fato |
|
| Ler fato(s) de uma entidade |
|
| Atalho: write com supersede=True | (mesmo do write) |
| Busca textual |
|
| Listar entidades com memória |
|
| Soft-delete de entradas |
|
| Exportar todos os dados |
|
| Criar link semântico |
|
| Remover link | (mesmo do link) |
| Consultar links de entidade |
|
📖 Conceitos-Chave
Entity Types
Tipo | Uso |
| Empresas clientes |
| Pessoas de contato |
| Fornecedores |
| Usuários do sistema |
| Resultados de execuções de agentes |
| Metadados de execuções |
| Snapshots de contexto |
| Checkpoints de rotinas |
Categorias
Categoria | Quando usar |
| Fatos objetivos sobre entidades |
| Decisões tomadas por agentes |
| Preferências do cliente/usuário |
| Contexto de sessão |
| Dados gerados por agentes de memória |
| Documentos para RAG |
| Documentos avulsos |
TTL Tiers
Tier | Expira em | Uso típico |
| ❌ Nunca | Dados críticos, perfis de cliente |
| 90 dias | Dados de migração |
| 30 dias | Análises de especialistas |
| 14 dias | Fatos de agentes de memória (prioridade alta) |
| 7 dias | Fatos de agentes de memória (prioridade baixa) |
Write Permissions (Single Writer Principle)
Source | Pode escrever em |
| Tudo |
| Tudo |
|
|
|
|
🔗 Integração com LangGraph (Handoff)
Esta foi a inspiração original do projeto. Na Blu Platform, usamos este padrão com LangGraph handoffs:
from langgraph.graph import StateGraph
from your_memory_client import SharedMemoryClient
memory = SharedMemoryClient()
class AgentState(TypedDict):
messages: list
shared_context: dict
async def crm_node(state: AgentState, config):
# Salva resultados na shared memory
await memory.write("client", "acme", "profile", {...})
return state
async def financeiro_node(state: AgentState, config):
# Carrega o que o CRM salvou
context = await load_shared_memory_context(
"financeiro", ["acme"], memory
)
state["shared_context"] = context
return state
# Graph: CRM → Shared Memory → Financeiro
graph = StateGraph(AgentState)
graph.add_node("crm", crm_node)
graph.add_node("financeiro", financeiro_node)
graph.add_edge("crm", "financeiro")O load_shared_memory_context() é a ponte: ela carrega automaticamente o contexto que outro agente escreveu, permitindo que agentes colaborem sem acoplamento direto.
🏛 Inspiração
Este projeto é uma versão standalone e didática da arquitetura de shared business memory usada na Blu Platform — um escritório virtual com IA para PMEs.
Na versão original, o backend é Supabase (PostgreSQL + pgvector) com integração profunda no ecossistema LangGraph. Este repositório simplifica para SQLite, mantendo a mesma API de tools MCP e o mesmo fluxo de handoff entre agentes.
Técnicas originais incluídas aqui:
Pre-flight context loading (agente carrega memória antes de executar)
Post-flight persistence (agente salva resultados depois de executar)
TTL tiers com soft-delete e hard-delete
Single Writer Principle (cada fonte só escreve em tipos que lhe competem)
Semantic links entre entidades
📄 Licença
MIT © 2026 Lucas Cid
⭐ Se este projeto te ajudou, dá uma estrela no GitHub e compartilha no LinkedIn!
Palavras-chave: AI agents, shared memory, MCP, LangGraph, machine learning, agent framework, Python, LLM, memória incremental, multi-agent
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/CidLucas/agent-shared-memory'
If you have feedback or need assistance with the MCP directory API, please join our Discord server