Skip to main content
Glama
CidLucas

agent-shared-memory

by CidLucas

🧠 Agente com Memória Incremental (Shared Memory)

Dê memória persistente aos seus agentes de IA — sem banco vetorial.

Python 3.11+ License: MIT MCP Tests


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:

  1. Agente CRM — descobre informações sobre um cliente

  2. Agente Financeiro — analisa a saúde financeira desse cliente

O fluxo ideal seria:

Agente CRM descobre → passa contexto → Agente Financeiro analisa

Na 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

memory_server.py

Servidor MCP com FastMCP. Expõe tools via HTTP.

memory_client.py

Cliente Python. Agentes chamam client.write(), client.read(), etc.

agent_integration.py

Função load_shared_memory_context() para carregar contexto em handoffs.

models.py

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: "Acme Corp ↔ Fornecedor X (contracts_with)"

Categorias

knowledge, decision, preference, context, memory-agent...

TTL Tiers

curated (nunca expira), memory_agent_lo (7 dias), specialist (30 dias)...

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

client_id isola dados de diferentes clientes/ambientes

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

Pré-requisitos

  • Python 3.11+

  • pip install . instala fastmcp, 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

shared_memory_write

Escrever um fato

entity_type, entity_name, key, value, category, ttl_tier, supersede

shared_memory_read

Ler fato(s) de uma entidade

entity_name, entity_type (opc), key (opc)

shared_memory_upsert

Atalho: write com supersede=True

(mesmo do write)

shared_memory_search

Busca textual

query, entity_type (opc), limit

shared_memory_list

Listar entidades com memória

entity_type (opc)

shared_memory_flush

Soft-delete de entradas

entity_type, entity_name

shared_memory_export

Exportar todos os dados

client_id, entity_type (opc)

shared_memory_link

Criar link semântico

source_*, target_*, link_type

shared_memory_unlink

Remover link

(mesmo do link)

shared_memory_get_links

Consultar links de entidade

entity_type, entity_name


📖 Conceitos-Chave

Entity Types

Tipo

Uso

client

Empresas clientes

contact

Pessoas de contato

supplier

Fornecedores

user

Usuários do sistema

agent_result

Resultados de execuções de agentes

agent_metadata

Metadados de execuções

snapshot

Snapshots de contexto

routine

Checkpoints de rotinas

Categorias

Categoria

Quando usar

knowledge

Fatos objetivos sobre entidades

decision

Decisões tomadas por agentes

preference

Preferências do cliente/usuário

context

Contexto de sessão

memory-agent

Dados gerados por agentes de memória

rag

Documentos para RAG

documents

Documentos avulsos

TTL Tiers

Tier

Expira em

Uso típico

curated

❌ Nunca

Dados críticos, perfis de cliente

migration

90 dias

Dados de migração

specialist

30 dias

Análises de especialistas

memory_agent_hi

14 dias

Fatos de agentes de memória (prioridade alta)

memory_agent_lo

7 dias

Fatos de agentes de memória (prioridade baixa)

Write Permissions (Single Writer Principle)

Source

Pode escrever em

system

Tudo

memory_agent

Tudo

specialist

client, contact, supplier, user, snapshot, agent_result

manual

client, contact, supplier, user


🔗 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

F
license - not found
-
quality - not tested
C
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

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