Configuración con Agentes de IA

El puente entre agentes y memoria

Engram se comunica con los agentes de IA a través del Model Context Protocol (MCP), el estándar abierto de Anthropic para conectar herramientas externas con modelos de lenguaje. Cada agente tiene su propia forma de configurar servidores MCP, pero el resultado es el mismo: el agente puede llamar a los 17 herramientas de Engram como si fueran funciones nativas.

El servidor MCP de Engram se ejecuta como proceso stdio:

engram mcp  # modo estándar con 17 herramientas
engram mcp --tools=agent  # modo agente con 12 herramientas esenciales

Detección automática de proyectos

Antes de configurar cualquier agente, es importante entender cómo Engram identifica a qué proyecto pertenece una memoria.

Engram detecta el proyecto automáticamente a partir del directorio de trabajo del proceso, usando este algoritmo de 5 pasos en orden de prioridad:

1. Variable de entorno ENGRAM_PROJECT si está definida
2. URL del remote de Git (origin) — ideal para proyectos con remoto
3. Nombre del directorio raíz del repositorio Git
4. Nombre del directorio de trabajo actual
5. Fallback a "unknown"

Por esto, nunca debes pasar el parámetro project a las herramientas de escritura. Si lo haces, Engram lo descartará silenciosamente. El proyecto siempre se auto-detecta desde el servidor.

La primera llamada recomendada en cualquier sesión es mem_current_project para confirmar qué proyecto detectó Engram antes de empezar a escribir memorias.

Claude Code

Claude Code es el agente con mejor integración de Engram gracias al sistema de plugins oficial.

Opción A: Plugin via marketplace (recomendada)

claude plugin marketplace add Gentleman-Programming/engram
claude plugin install engram

Esto instala automáticamente:

• Servidor MCP registrado en la configuración de Claude Code
• Hooks de inicio/fin de sesión
• Skill “memory” para recuperar contexto activamente
• Manejo de compactación (cuando Claude Code comprime el contexto)

Opción B: Plugin via engram setup

engram setup claude-code

Durante el setup, te preguntará si deseas agregar las herramientas MCP al allowlist de ~/.claude/settings.json. Acepta para evitar que Claude Code te pida confirmación cada vez que llama a una herramienta de memoria.

El comando también registra las entradas de permiso tanto para el ID de servidor MCP duradero (mcp__engram__...) como para el ID del plugin, por lo que re-ejecutar el setup repara configuraciones incompletas sin agregar duplicados.

Opción C: MCP manual (mínimo)

Agrega esto a tu ~/.claude/settings.json (global) o .claude/settings.json (proyecto):

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Con esta opción mínima, agrega un prompt de instrucciones a tu CLAUDE.md para que Claude sepa cómo usar Engram después de una compactación de contexto:

## Memoria persistente con Engram
Al iniciar cada sesión, llama a `mem_current_project` para verificar el proyecto
detectado y `mem_context` para recuperar el contexto de sesiones anteriores.
Al finalizar, llama a `mem_session_summary` con un resumen de lo que lograste.

Surviving compaction en Claude Code

Claude Code compacta el contexto automáticamente cuando se acerca al límite de tokens. Esto es el equivalente a “borrar la memoria RAM” del agente mid-sesión. El plugin de Engram maneja esto con un hook post-compaction que instruye al agente a recuperar el contexto de Engram inmediatamente después de la compactación.

Si usas la opción C (MCP manual), agrega a tu CLAUDE.md:

## Post-compactación
Si el contexto fue compactado, ejecuta inmediatamente:
1. `mem_current_project` — confirmar proyecto
2. `mem_context` — recuperar contexto de sesiones previas
3. `mem_search "tarea actual"` — buscar memorias relevantes al trabajo en curso

OpenCode

OpenCode tiene soporte de primera clase para Engram con un setup de un solo comando:

engram setup opencode

Esto hace tres cosas simultáneamente:

1. Copia el plugin a ~/.config/opencode/plugins/engram.ts — gestiona sesiones, protocolo de memoria y recuperación post-compactación
2. Agrega el servidor MCP engram a tu opencode.json con perfil --tools=agent (12 herramientas orientadas al agente)
3. Agrega opencode-subagent-statusline a tu tui.json para mostrar actividad de sub-agentes en la barra de estado

El plugin inicia el servidor HTTP de Engram automáticamente cuando es necesario para el tracking de sesiones. Si tu entorno bloquea procesos en segundo plano:

engram serve &  # inicia el servidor HTTP manualmente

Setup manual (solo MCP, sin plugin):

Agrega a ~/.config/opencode/opencode.json:

{
  "mcp": {
    "engram": {
      "type": "local",
      "command": ["engram", "mcp"],
      "enabled": true
    }
  }
}

Gemini CLI

engram setup gemini-cli

El comando hace tres cosas:

1. Registra mcpServers.engram en ~/.gemini/settings.json
2. Escribe el protocolo de memoria completo en ~/.gemini/system.md
3. Agrega GEMINI_SYSTEM_MD=1 a ~/.gemini/.env para que Gemini cargue ese system prompt

Esta es la parte más importante: el protocolo de memoria en system.md le dice explícitamente a Gemini cuándo guardar, cuándo buscar, y cómo gestionar sesiones. Sin esto, Gemini no sabrá que debe usar Engram proactivamente.

Setup manual:

Agrega a ~/.gemini/settings.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

O via CLI de Gemini:

gemini mcp add engram engram mcp

Codex (OpenAI)

engram setup codex

El comando:

1. Registra [mcp_servers.engram] en ~/.codex/config.toml
2. Escribe el protocolo de memoria en ~/.codex/engram-instructions.md
3. Escribe el prompt de compactación en ~/.codex/engram-compact-prompt.md y configura experimental_compact_prompt_file

Setup manual en ~/.codex/config.toml:

model_instructions_file = "~/.codex/engram-instructions.md"
experimental_compact_prompt_file = "~/.codex/engram-compact-prompt.md"

[mcp_servers.engram]
command = "engram"
args = ["mcp"]

VS Code (Copilot / Claude Code Extension)

VS Code tiene soporte nativo de MCP en su panel de chat (Copilot agent mode). Funciona con cualquier proveedor de IA dentro de VS Code.

Opción A: Configuración de workspace (recomendada para equipos)

Crea .vscode/mcp.json en tu proyecto:

{
  "servers": {
    "engram": {
      "type": "stdio",
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Commitea este archivo para que todo el equipo use Engram automáticamente.

Opción B: Configuración global de usuario

code --add-mcp '{"name":"engram","command":"engram","args":["mcp"]}'

O agrega a tu settings.json de VS Code:

{
  "mcp": {
    "servers": {
      "engram": {
        "type": "stdio",
        "command": "engram",
        "args": ["mcp"]
      }
    }
  }
}

Cursor y Windsurf

Ambos editores usan configuración JSON manual. Cursor busca en .cursor/mcp.json o en la configuración global del usuario, y Windsurf en .windsurf/mcp.json.

Cursor — crea .cursor/mcp.json en tu proyecto:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Windsurf — crea .windsurf/mcp.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Cualquier agente MCP compatible

Para cualquier agente que soporte MCP via stdio, la configuración genérica es siempre la misma:

• Comando: engram
• Argumentos: ["mcp"]
• Transport: stdio

Si el agente soporta perfiles de herramientas, puedes usar ["mcp", "--tools=agent"] para exponer solo las 12 herramientas esenciales del perfil agente (omite las herramientas administrativas como mem_merge_projects).

Verificar que la integración funciona

Después de configurar tu agente, verifica que puede ver las herramientas de Engram. En Claude Code:

/mcp

Deberías ver engram listado como servidor MCP activo con sus herramientas. Si no aparece, revisa:

1. Que el binario engram está en el PATH del agente
2. Que la configuración JSON es válida (sin comas finales en el último elemento)
3. Que reiniciaste el agente después de modificar la configuración

Para confirmar que el proyecto se detecta correctamente, pide al agente que llame:

mem_current_project

Debería devolver el nombre de tu proyecto actual y el método de detección (git_remote, git_root, directory_basename, etc.).

El perfil de herramientas: agente vs completo

Por defecto engram mcp expone las 17 herramientas. El perfil --tools=agent expone 12, omitiendo las herramientas administrativas:

Perfil	Herramientas excluidas	Caso de uso
mcp (default)	Ninguna	Acceso completo, dev avanzado
mcp --tools=agent	mem_merge_projects, y otras admin	Uso diario de agentes

El plugin de OpenCode usa --tools=agent por defecto. Para Claude Code con setup manual, puedes especificar:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp", "--tools=agent"]
    }
  }
}

En el próximo capítulo veremos en detalle cómo funciona el protocolo de memoria: cuándo guardar, qué tipos existen, y cómo los topic keys evitan duplicados al evolucionar el conocimiento.