mcp-brain-tools

Un servidor MCP que proporciona a los agentes de IA memoria persistente con seguimiento de frescura integrado y repetición espaciada. Respaldado por Elasticsearch.

A diferencia de los almacenes de memoria simples de clave-valor, mcp-brain-tools realiza un seguimiento de la antigüedad de cada pieza de conocimiento, marca lo que necesita revisión y permite a los agentes verificar la información para mantenerla actualizada, inspirado en cómo la repetición espaciada ayuda a los humanos a retener el conocimiento.

Características

• Frescura por repetición espaciada — cada entidad tiene un intervalo de revisión que se duplica tras la verificación (limitado a 365 días). Las etiquetas de confianza (fresco/normal/envejeciendo/obsoleto/archivo) indican a los agentes en qué confiar.

• Búsqueda progresiva — las consultas devuelven primero los resultados frescos, ampliándose automáticamente para incluir datos más antiguos solo cuando es necesario.

• Observaciones como entidades — cada observación obtiene su propio ciclo de vida de frescura, por lo que "la compilación está rota" (revisión de 1 día) y "fundado en 2015" (revisión de 365 días) envejecen de forma independiente.

• Zonas de memoria — aísla el conocimiento por proyecto, equipo o dominio.

• Filtrado potenciado por IA — la integración opcional con Groq califica los resultados de búsqueda por relevancia.

• DRY por diseño — las descripciones de las herramientas guían a los agentes para no almacenar lo que ya está en el código, git o la documentación.

Related MCP server: Logseq MCP Tools

Configuración

Requisitos previos

• Node.js >= 18

• Docker (para Elasticsearch) o una instancia remota de Elasticsearch

Instalación y compilación

npm install
npm run build

Iniciar Elasticsearch

npm run es:start

O apunte a su propia instancia mediante la variable de entorno ES_NODE.

Configurar su cliente MCP

Añada esto a su configuración de Claude Code, Claude Desktop u otro cliente MCP:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-brain-tools/dist/index.js"],
      "env": {
        "ES_NODE": "http://localhost:9200",
        "GROQ_API_KEY": "your-key-here"
      }
    }
  }
}

GROQ_API_KEY es opcional: permite el filtrado de búsqueda potenciado por IA y la puntuación de relevancia de zona.

Instalar el hook de memoria automática (solo para Claude Code)

El hook de memoria se ejecuta en cada mensaje del usuario e inyecta automáticamente el contexto relevante; no se requiere cooperación del agente.

Añada esto a ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /path/to/mcp-brain-tools/dist/memory-hook.js"
          }
        ]
      }
    ]
  }
}

El hook utiliza las mismas variables de entorno ES_NODE, AI_API_KEY/GROQ_API_KEY, AI_API_BASE y AI_MODEL (establézcalas en el bloque env de su configuración o expórtelas en su perfil de shell).

AI_API_BASE utiliza por defecto el endpoint de Groq, pero acepta cualquier URL de API compatible con OpenAI.

Cómo funciona

Entidades y observaciones

Las entidades representan cualquier cosa que valga la pena recordar: personas, proyectos, decisiones, hechos. Cada entidad tiene:

• Un nombre y un tipo

• Campos de repetición espaciada: verifiedAt, reviewInterval, nextReviewAt

• Una etiqueta de confianza calculada a partir de la frescura: 1 - (díasDesdeVerificación / intervaloDeRevisión)

Las observaciones se almacenan como entidades separadas vinculadas mediante relaciones is_observation_of. Cada observación tiene su propia cadencia de revisión:

Entity: "iaptic-server" (type: Project, reviewInterval: 30 days)
  <- "iaptic-server: uses TypeScript" (reviewInterval: 180 days)
  <- "iaptic-server: migration in progress" (reviewInterval: 7 days)

Ciclo de vida de frescura

1. Entidad creada — confidence: "fresh", revisión predeterminada en 7 días

2. Pasa la fecha de revisión — confidence: "aging", needsReview: true

3. El agente verifica (mediante verify_entity) — el intervalo se duplica, la confianza se restablece a "fresh"

4. Mucho tiempo vencido — confidence: "stale" luego "archival", excluido de la búsqueda predeterminada

Búsqueda progresiva

Al buscar, el servidor utiliza tres pasadas:

1. freshness >= 0 — entidades frescas y normales

2. freshness >= -2 — añade envejecidas y obsoletas

3. Sin filtro — añade archivos

Esto mantiene los resultados limpios mientras asegura que nada se pierda permanentemente.

Herramientas MCP

Variables de entorno

Instrucciones recomendadas para el agente

Para que los agentes utilicen activamente el servidor de memoria, añada algo como esto a su CLAUDE.md (o archivo de instrucciones equivalente):

## Memory

Use MCP Memory (`mcp__memory__*` tools) — a shared knowledge graph across all agents, projects, and computers.

**When to SAVE (immediately, before moving on):**
- Something you tried didn't work (non-transient) → save what failed and why, so no agent repeats it
- A decision was made (architectural, design, workflow) → save the decision and the reason
- The user corrects you or gives explicit instructions → save the rule
- You learn something non-obvious that took effort to discover → save it

**When to SEARCH (before starting, not after failing):**
- **At the start of every non-trivial task** — search before thinking, not after hitting a wall
- About to try an approach that might have been attempted before → search first
- User references something from a past session → search before asking

**Rules:**
- Skip anything easy to find in code, git log, or docs
- Use the project name as the zone for project-specific knowledge; `default` for general knowledge
- Keep entries short — the AI filters server-side, so be generous rather than selective
- Short `reviewInterval` (e.g. 3–7 days) for volatile facts; longer (30–180) for stable ones

La idea clave: los agentes necesitan instrucciones explícitas basadas en disparadores ("cuando X, haz Y"), no solo descripciones de lo que hace la herramienta.

Desarrollo

npm run build          # Compile TypeScript
npm run dev            # Watch mode
npm run test:jest      # Run Jest tests
npm run es:start       # Start Elasticsearch
npm run es:stop        # Stop Elasticsearch
npm run es:reset       # Wipe data and restart
npm run import         # Import from JSON
npm run export         # Export to JSON

Licencia

MIT