Potencializando Agentes de Codificação de IA com Memória Persistente: Um Manual Detalhado

Seja você um usuário de ferramentas de codificação AI pré-construídas como Claude Code, OpenAI Codex, OpenCode e Cursor, ou esteja construindo runtimes de agentes autônomos personalizados em TypeScript, todo ambiente de agente sofre da mesma limitação:

• Cada novo chat ou trajetória de execução começa com zero conhecimento de decisões passadas.
• Mudar branches do git ou gerar subagentes confunde o agente sobre dependências ativas.
• Quando um agente compacta sua janela de contexto para gerenciar limites de tokens, ele apaga as regras estabelecidas anteriormente.

Este guia é um livro de receitas prático para conectar MemoFS—o runtime de memória open-source e baseado em arquivos— a qualquer agente de codificação AI ou runtime de agente personalizado em menos de dois minutos.

Visão Geral do Livro de Receitas: Como o MemoFS se Conecta aos Agentes

O MemoFS suporta três padrões de integração dependendo da sua ferramenta ou framework:

┌───────────────────────────────────────────────────────────────────────────┐
│                          Ecossistema de Agentes AI                         │
└──────────────┬─────────────────────────────┬──────────────────────────────┘
               │                             │                              │
     (Agentes com Hooks)            (Agentes via MCP)           (Runtimes de Agentes Personalizados)
   Claude Code / Codex / OpenCode  Cursor / Copilot / Windsurf    TypeScript / LangChain / SDKs
               │                             │                              │
               ▼                             ▼                              ▼
     Scripts de Hook de Ciclo de Vida           @memofs/mcp-server             @memofs/core SDK
   (SessionStart / Compaction)        (memofs.context / remember)    (memo.context() / writeMemory())
               │                             │                              │
               └─────────────────────────────┼──────────────────────────────┘
                                             │
                                             ▼
                                  .memofs/ Armazenamento de Memória
                            (core.md, notes.md, índice de recuperação)

1. Modo de Hooks Zero-Touch (Claude Code, OpenAI Codex, OpenCode): Injeta automaticamente o contexto do projeto na inicialização da sessão, propaga a memória para subagentes e reinjeta a memória após a compactação do contexto.
2. Modo Servidor MCP (Cursor, GitHub Copilot, Windsurf, Gemini CLI): Conecta via o Protocolo de Contexto do Modelo, expondo ferramentas de memória padrão (memofs.context, memofs.remember, memofs.recall).
3. Modo SDK Core Programático (Frameworks e Runtimes de Agentes Personalizados): SDK direto em TypeScript (@memofs/core) para engenheiros de agentes que incorporam memória nativamente em loops de agentes autônomos.

Passo 1: Inicialize o MemoFS em Seu Repositório

Do diretório raiz do seu projeto, execute:

# Instale o CLI globalmente ou como uma dependência de desenvolvimento
npm install -g @memofs/cli

# Inicialize o diretório de runtime de memória .memofs/
npx memofs init

Isso cria o diretório .memofs/ contendo seu arquivo de briefing principal (.memofs/memory/core.md), notas de longo prazo (.memofs/memory/notes.md), índices de busca derivados e arquivos de gráfico de entidades.

Passo 2: Configure Seu Agente ou Runtime Específico

Opção A: Claude Code & OpenAI Codex (Hooks Zero-Touch Automáticos)

Gere a configuração do agente e scripts de hook com um único comando:

# Código Claude
npx memofs generate agent claude --project-name "Meu Aplicativo"

# Codex
npx memofs generate agent codex --project-name "Meu Aplicativo" --scope local

O que isso configura automaticamente:

• Hook de Início de Sessão: Quando você inicia claude ou codex, o MemoFS consulta seu armazenamento de memória local e injeta um briefing compacto (~6 KB) diretamente no prompt inicial do agente.
• Hook de Subagente: Quando seu agente principal gera subagentes, os subagentes herdam automaticamente o contexto de memória da sessão pai.
• Hook de Sobrevivência de Compactação: Quando o agente compacta sua janela de contexto, o MemoFS intercepta o evento e reinjeta as regras principais do projeto—prevenindo a perda de memória durante longas sessões.
• Resumo de Fim de Sessão: Produz um resumo rápido de conformidade das memórias acessadas e persistidas durante a sessão.

Opção B: Cursor IDE (via MCP)

Para conectar as regras do MemoFS e a configuração do MCP no Cursor:

npx memofs generate agent cursor

Isso gera .cursor/rules/memofs.mdc e registra o servidor MemoFS MCP em .cursor/mcp.json:

{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}

Agora o Cursor pode invocar nativamente memofs.context no início das tarefas do compositor e chamar memofs.remember sempre que você instruí-lo a salvar uma decisão.

Opção C: GitHub Copilot / VS Code

Para configurar o VS Code e as instruções do Copilot e o servidor MCP:

npx memofs generate agent copilot

Isso cria .vscode/mcp.json e adiciona instruções de gerenciamento de memória em .github/copilot-instructions.md.

Opção D: Qualquer outro agente de codificação que fale MCP

Confira nossos livros de receitas

Opção E: Runtimes e Frameworks de Agentes Personalizados (via @memofs/core SDK)

Se você está construindo agentes AI personalizados em Node.js ou TypeScript, instale @memofs/core diretamente:

npm install @memofs/core

Instancie o mecanismo MemoFS dentro do seu loop de agente para buscar briefings de contexto cientes da tarefa e persistir fatos aprendidos:

import <