Como Adicionar Memória Persistente ao Seu Agente de IA (Para Lembrar de Ontem)

TL;DR

Adicione memória persistente a agentes de IA em 4 etapas práticas:

1. Configure um servidor de memória MCP com as ferramentas remember, recall, search e rollback
2. Adicione instruções de memória nos prompts do agente
3. Configure ~/.claude/settings.json para Claude Code ou .cursor/mcp.json para Cursor
4. Use padrões de memória para registrar decisões, transferências de agente e checkpoints de sessão

Com isso, agentes retêm contexto entre sessões — nunca mais perca tempo copiando e colando conversas antigas.

Resolva o problema “Não lembro de ontem”. Implante memória persistente com o protocolo MCP para que agentes de IA lembrem decisões, entregáveis e contexto de sessões anteriores.

Experimente o Apidog hoje

Você conhece a rotina:

Day 1: "Build the user authentication system"
Agent: [Builds JWT auth, creates users table, implements refresh tokens]

Day 2: "Continue from yesterday"
Agent: "I don't have context from previous sessions. Can you paste what we did?"

Você copia e cola a conversa anterior. O agente lê 2000 linhas. Ambos perdem 15 minutos só para se atualizar.

Com memória MCP, os agentes armazenam decisões automaticamente e recuperam quando necessário. Nada de copiar e colar, nada de re-explicar contexto.

Neste tutorial, você vai configurar MCP em agentes de IA para backend, banco de dados, frontend e integrações (incluindo Apidog). Use os mesmos padrões de memória para APIs, automações e sprints de vários dias.

O Que É Memória MCP?

Memória MCP permite que agentes de IA armazenem e recuperem informações entre sessões, como um caderno compartilhado.

Quatro ferramentas principais:

Ferramenta	Propósito	Exemplo
remember	Armazenar informações com tags	Salvar “tabela de usuários com UUID, bcrypt”
recall	Pesquisar por palavra-chave/tag	Encontrar “decisões de auth”
rollback	Restaurar estado anterior	Desfazer alterações de esquema ruins
search	Encontrar entre sessões	“O que o Arquiteto de Backend decidiu?”

┌─────────────────┐         ┌──────────────────┐         ┌─────────────┐
│  Agente de IA   │         │  Servidor        │         │  Armazenamento│
│  (Claude Code)  │◄───────►│  de Memória MCP  │◄───────►│  (SQLite)   │
└─────────────────┘   JSON  └──────────────────┘  I/O    └─────────────┘

Passo 1: Configure um Servidor de Memória MCP

Você precisa de um servidor MCP que forneça as ferramentas de memória. Existem opções open-source.

Opção A: Instale um servidor de memória hospedado

npm install -g @example/mcp-memory-server

Opção B: Execute um servidor local simples

Crie um arquivo memory-server.js:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import fs from "fs/promises";
import path from "path";

const MEMORY_FILE = path.join(process.env.HOME, ".mcp-memory", "memories.json");

const server = new McpServer({
  name: "memory",
  version: "1.0.0"
});

// Garante que o arquivo de memória existe
async function initMemory() {
  await fs.mkdir(path.dirname(MEMORY_FILE), { recursive: true });
  try {
    await fs.access(MEMORY_FILE);
  } catch {
    await fs.writeFile(MEMORY_FILE, JSON.stringify([]));
  }
}

// Tool: remember
server.tool(
  "remember",
  {
    content: z.string().describe("Information to store"),
    tags: z.array(z.string()).describe("Tags for retrieval (e.g., ['backend', 'auth'])"),
    agent: z.string().optional().describe("Agent name for tagging")
  },
  async ({ content, tags, agent }) => {
    await initMemory();
    const memories = JSON.parse(await fs.readFile(MEMORY_FILE, "utf-8"));
    const memory = {
      id: Date.now().toString(),
      content,
      tags,
      agent,
      timestamp: new Date().toISOString()
    };
    memories.push(memory);
    await fs.writeFile(MEMORY_FILE, JSON.stringify(memories, null, 2));
    return { content: [{ type: "text", text: `Stored memory with tags: ${tags.join(", ")}` }] };
  }
);

// Tool: recall
server.tool(
  "recall",
  {
    query: z.string().describe("Search query or tag to find"),
    agent: z.string().optional().describe("Filter by agent name")
  },
  async ({ query, agent }) => {
    await initMemory();
    const memories = JSON.parse(await fs.readFile(MEMORY_FILE, "utf-8"));
    const results = memories.filter(m =>
      (m.content.toLowerCase().includes(query.toLowerCase()) ||
        m.tags.some(t => t.toLowerCase().includes(query.toLowerCase()))) &&
      (!agent || m.agent === agent)
    );
    return {
      content: [{
        type: "text",
        text: results.length === 0
          ? "No memories found"
          : results.map(m => `[${m.timestamp}] ${m.content}`).join("\n\n")
      }]
    };
  }
);

// Tool: search
server.tool(
  "search",
  {
    tags: z.array(z.string()).describe("Tags to search for"),
    limit: z.number().optional().default(10)
  },
  async ({ tags, limit }) => {
    await initMemory();
    const memories = JSON.parse(await fs.readFile(MEMORY_FILE, "utf-8"));
    const results = memories
      .filter(m => tags.some(t => m.tags.includes(t)))
      .slice(0, limit);
    return {
      content: [{
        type: "text",
        text: results.map(m => `[${m.agent || "unknown"}] ${m.content}`).join("\n\n")
      }]
    };
  }
);

// Tool: rollback
server.tool(
  "rollback",
  {
    agent: z.string().describe("Agent name to rollback"),
    timestamp: z.string().describe("Rollback to this timestamp")
  },
  async ({ agent, timestamp }) => {
    await initMemory();
    const memories = JSON.parse(await fs.readFile(MEMORY_FILE, "utf-8"));
    const rolledBack = memories.filter(m =>
      m.agent !== agent || new Date(m.timestamp) <= new Date(timestamp)
    );
    await fs.writeFile(MEMORY_FILE, JSON.stringify(rolledBack, null, 2));
    return {
      content: [{
        type: "text",
        text: `Rolled back ${agent} to ${timestamp}`
      }]
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Execute o servidor:

node memory-server.js

Passo 2: Adicione Instruções de Memória a Qualquer Agente

Não é necessário modificar o código do agente. Basta instruir pelo prompt:

Você tem acesso às ferramentas de memória MCP: remember, recall, search, rollback.

Siga estes protocolos:

**Ao iniciar uma sessão:**
1. Recupere contexto: recall(query="ecommerce-api", agent="Backend Architect")
2. Revise itens pendentes da última sessão

**Ao concluir o trabalho:**
1. Lembre-se dos entregáveis com tags:
   - remember(content="Criada tabela de usuários com chave primária UUID, hash de senha bcrypt, autenticação JWT com tokens de atualização", tags=["ecommerce-api", "database", "auth"], agent="Backend Architect")
2. Inclua decisões e pendências

**Ao transferir para outro agente:**
1. Deixe contexto para o agente receptor:
   - remember(content="Endpoints da API: /auth/login, /auth/register, /products, /orders. Fluxo de autenticação: token de acesso JWT (15min) + token de atualização (7 dias). Problema conhecido: limitação de taxa ainda não implementada", tags=["ecommerce-api", "handoff"], agent="Backend Architect", for="Frontend Developer")

**Falhas:**
1. Procure último estado funcional
2. Use rollback para restaurar

Exemplo prático:

Você: "Ative o modo Arquiteto de Backend. Projete o sistema de usuário para nossa API de e-commerce."

[Agente projeta o sistema, cria o esquema e autenticação]

Agente: "Sistema de usuário completo. Armazenando memória..."
→ Chama: remember("tabela de usuários com UUID, bcrypt, JWT + tokens de atualização", tags: ["ecommerce-api", "auth", "database"])

[Sessão termina]

[Dia seguinte]

Você: "Continue de ontem"

Agente: "Recuperando contexto..."
→ Chama: recall(query="ecommerce-api")
→ Retorna: "tabela de usuários com UUID, bcrypt, JWT + tokens de atualização"

Agente: "Ontem eu projetei a tabela de usuários com chaves primárias UUID, implementei hash de senha bcrypt e configurei autenticação JWT com tokens de atualização. Próximo passo: esquema do catálogo de produtos. Pronto para continuar."

Passo 3: Configurar para Claude Code

Adicione o servidor de memória na configuração MCP:

Edite ~/.claude/settings.json:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/memory-server.js"],
      "env": {
        "HOME": "/Users/seu-usuario"
      }
    }
  }
}

Reinicie o Claude Code e as ferramentas de memória estarão ativas.

Teste:

Use a ferramenta remember para armazenar: "Memória de teste para projeto de e-commerce"
Tags: ["test", "ecommerce-api"]

Use a ferramenta recall para encontrar memórias sobre "test"

Passo 4: Configurar para Cursor

Crie .cursor/mcp.json no projeto:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/memory-server.js"]
    }
  }
}

Teste:

@memory remember "Iniciando projeto de API de e-commerce com PostgreSQL"
Tags: ["ecommerce-api", "setup"]

@memory recall query="ecommerce"

Padrões de Memória para Fluxos de Trabalho Reais

Padrão 1: Registro de Decisões

Registre cada decisão técnica:

remember({
  content: "Escolheu PostgreSQL em vez de MySQL para: (1) suporte JSONB para atributos de produto flexíveis, (2) melhor busca de texto completo, (3) suporte nativo a UUID",
  tags: ["ecommerce-api", "database", "decision"],
  agent: "Backend Architect"
})

Para buscar depois:

recall(query="decisão PostgreSQL MySQL")

Padrão 2: Transferências de Agente

Ao trocar de agente, registre a transferência:

remember({
  content: "Backend completo. Endpoints: POST /auth/login, POST /auth/register, GET /products, POST /orders. Autenticação: JWT 15min acesso + 7 dias refresh. Pendente: limitação de taxa, verificação de e-mail. Frontend precisa: formulário de login, lista de produtos, carrinho, checkout.",
  tags: ["ecommerce-api", "handoff", "backend-complete"],
  agent: "Backend Architect",
  for: "Frontend Developer"
})

O Frontend começa com:

recall(query="transferência", agent="Backend Architect")

Padrão 3: Pontos de Verificação de Sessão

Ao fim de cada sessão:

remember({
  content: "Sessão completa. Concluído: tabela de usuários, endpoints de autenticação, esquema de produto. Próxima sessão: sistema de pedidos, webhook de pagamento. Bloqueadores: aguardando chaves da API Stripe.",
  tags: ["ecommerce-api", "checkpoint", "session-1"],
  agent: "Backend Architect"
})

Retome depois:

recall(query="checkpoint sessão-1")

Padrão 4: Rastreamento de Bugs

Quando encontrar um bug:

remember({
  content: "BUG: Token de atualização não expira após logout. Token armazenado em memória, não persistido. Correção: mover para Redis com TTL.",
  tags: ["ecommerce-api", "bug", "auth"],
  agent: "Revisor de Código",
  severity: "high"
})

Busque bugs:

search(tags=["bug", "ecommerce-api"])

Solução de Problemas

Memória não persistindo:

• Verifique o caminho do arquivo (~/.mcp-memory/memories.json)
• Certifique-se que o servidor MCP está em execução
• Cheque a configuração MCP do Claude Code/Cursor

Recuperação retorna muitos resultados:

• Use tags mais específicas
• Filtre por agente
• Use frases entre aspas

Arquivo grande demais:

• Arquive memórias antigas periodicamente
• Use rollback para limpar projetos finalizados
• Adicione datas de expiração

O Que Você Construiu

Componente	Propósito
Servidor de Memória MCP	Armazena/recupera informações entre sessões
Ferramenta remember	Registra decisões, entregáveis, transferências
Ferramenta recall	Recupera contexto de sessões anteriores
Ferramenta search	Consulta por tags
Ferramenta rollback	Restaura para estados anteriores
Padrões de memória	Registro de decisões, transferências, checkpoints, bugs

Próximos Passos

Estenda o servidor de memória:

• Adicione busca semântica (embeddings)
• Implemente expiração automática (30 dias)
• Adicione sumarização de sessões longas

Construa memória de equipe:

• Compartilhe servidor de memória central
• Marque memórias por projeto e desenvolvedor
• Crie onboarding automático para novos membros

Integre com ferramentas:

• Registre commits git como memórias
• Sincronize com Jira/Linear
• Exporte memórias para documentação

Solução de Problemas Comuns

Memória não persiste entre sessões:

• Inicie o servidor MCP antes do Claude Code
• Veja se o arquivo existe: ls -la ~/.mcp-memory/memories.json
• Permissões: chmod 644 ~/.mcp-memory/memories.json
• Caminho correto na configuração

Recall retorna vazio:

• Confira se a consulta bate com as tags (case sensitive)
• Use termos mais amplos ou search com tags
• Confirme se as memórias estão salvas: cat ~/.mcp-memory/memories.json
• Cheque o filtro de agente

Arquivo grande demais:

• Implemente arquivamento automático (30+ dias)
• Crie uma ferramenta prune para excluir por data
• Separe memórias por projeto/data
• Use SQLite em larga escala

Servidor não inicia:

• Node.js v18+ (node --version)
• Instale dependências: npm install @modelcontextprotocol/sdk zod
• Procure erros de sintaxe
• Execute direto: node memory-server.js

Múltiplos agentes sobrescrevendo memórias:

• Sempre use agent em remember
• Use tags únicas por projeto
• Filtre por agente ao recuperar contexto
• Considere arquivos separados por projeto

Considerações de Segurança do Servidor de Memória

Armazenando chaves de API/dados sensíveis: Use criptografia. Exemplo:

import crypto from 'crypto';

const ENCRYPTION_KEY = process.env.MEMORY_ENCRYPTION_KEY;
const ALGORITHM = 'aes-256-gcm';

function encrypt(text) {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv(ALGORITHM, Buffer.from(ENCRYPTION_KEY), iv);
  const encrypted = cipher.update(text, 'utf8', 'hex');
  return {
    encryptedData: encrypted + cipher.final('hex'),
    iv: iv.toString('hex'),
    authTag: cipher.getAuthTag().toString('hex')
  };
}

function decrypt(encrypted) {
  const decipher = crypto.createDecipheriv(
    ALGORITHM,
    Buffer.from(ENCRYPTION_KEY),
    Buffer.from(encrypted.iv, 'hex')
  );
  decipher.setAuthTag(Buffer.from(encrypted.authTag, 'hex'));
  return decipher.update(encrypted.encryptedData, 'hex', 'utf8') + decipher.final('utf8');
}

Controle de acesso:

• Exija chave de API nas ferramentas de memória
• Implemente namespaces por usuário
• Registre todas as operações (audit trail)
• Limite a taxa de requisições por usuário

Seus agentes de IA agora têm memória persistente. Eles lembram de ontem, recuperam decisões e transferem contexto sem copiar e colar.

Chega de “Não tenho contexto de sessões anteriores.” Chega de re-explicar. Chega de tempo desperdiçado.

Esse é o poder da memória MCP: dê aos seus agentes um caderno compartilhado e veja-os realmente úteis em projetos longos.

Perguntas Frequentes

O que é memória MCP?

Memória MCP é um protocolo para agentes de IA armazenarem e recuperarem informações entre sessões. É como um caderno compartilhado, persistindo contexto além de uma conversa.

Como configuro memória persistente para Claude Code?

Instale um servidor MCP, adicione em ~/.claude/settings.json o comando/caminho do servidor. Reinicie o Claude Code e as ferramentas de memória (remember, recall, search, rollback) estarão disponíveis.

Quais agentes suportam memória MCP?

Qualquer agente rodando em clientes compatíveis com MCP (Claude Code, Cursor, Windsurf). Só precisa adicionar instruções de memória no prompt — sem modificar o código do agente.

Melhores padrões para transferências de agente?

Use remember com tags como ["transferência", "nome-do-projeto"] para deixar contexto. Inclua trabalho feito, pendências e problemas. O próximo agente usa recall(query="transferência").

Quanto armazenam os servidores MCP?

Depende da implementação. O servidor de referência usa um JSON que cresce ilimitadamente. Em produção, adicione expiração, arquivamento ou backend de banco de dados.

Equipes podem compartilhar um servidor de memória?

Sim. Execute o servidor em máquina compartilhada ou nuvem, configure clientes para conectar e use tags por projeto/desenvolvedor.

E se recall/search retorna muitos resultados?

Use tags específicas, filtre por agente, use frases entre aspas. Considere embeddings para busca semântica.

---

Implemente, automatize e nunca mais perca contexto em projetos de IA.