mcp-brain-tools

Ein MCP-Server, der KI-Agenten ein persistentes Gedächtnis mit integrierter Aktualitätsverfolgung und räumlicher Wiederholung (Spaced Repetition) verleiht. Basiert auf Elasticsearch.

Im Gegensatz zu einfachen Key-Value-Speichern verfolgt mcp-brain-tools, wie alt jedes Wissen ist, markiert Inhalte, die überprüft werden müssen, und ermöglicht es Agenten, Informationen zu verifizieren, um sie aktuell zu halten – inspiriert davon, wie räumliche Wiederholung Menschen hilft, Wissen zu behalten.

Funktionen

• Aktualität durch räumliche Wiederholung — Jede Entität hat ein Überprüfungsintervall, das sich bei Verifizierung verdoppelt (begrenzt auf 365 Tage). Vertrauens-Labels (frisch/normal/alternd/veraltet/archiviert) zeigen Agenten, was vertrauenswürdig ist.

• Progressive Suche — Abfragen liefern zuerst aktuelle Ergebnisse und erweitern sich automatisch auf ältere Daten, nur wenn dies erforderlich ist.

• Beobachtungen als Entitäten — Jede Beobachtung erhält ihren eigenen Aktualitätslebenszyklus, sodass "Build ist defekt" (1-Tages-Überprüfung) und "Gegründet 2015" (365-Tage-Überprüfung) unabhängig voneinander altern.

• Gedächtniszonen — Isolieren Sie Wissen nach Projekt, Team oder Domäne.

• KI-gestützte Filterung — Optionale Groq-Integration bewertet Suchergebnisse nach Relevanz.

• DRY-Design — Tool-Beschreibungen leiten Agenten dazu an, nichts zu speichern, was bereits in Code, Git oder Dokumentationen vorhanden ist.

Related MCP server: Logseq MCP Tools

Einrichtung

Voraussetzungen

• Node.js >= 18

• Docker (für Elasticsearch) oder eine Remote-Elasticsearch-Instanz

Installation und Build

npm install
npm run build

Elasticsearch starten

npm run es:start

Oder verweisen Sie über die Umgebungsvariable ES_NODE auf Ihre eigene Instanz.

Konfigurieren Sie Ihren MCP-Client

Fügen Sie dies zu Ihrer Claude Code, Claude Desktop oder einer anderen MCP-Client-Konfiguration hinzu:

{
  "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 ist optional — ermöglicht KI-gestützte Suchfilterung und Zonen-Relevanzbewertung.

Installieren Sie den Auto-Memory-Hook (nur Claude Code)

Der Memory-Hook läuft bei jeder Benutzernachricht und fügt automatisch relevanten Kontext ein – keine Kooperation des Agenten erforderlich.

Fügen Sie dies zu ~/.claude/settings.json hinzu:

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

Der Hook verwendet dieselben Umgebungsvariablen ES_NODE, AI_API_KEY/GROQ_API_KEY, AI_API_BASE und AI_MODEL (setzen Sie diese im env-Block Ihrer Einstellungen oder exportieren Sie sie in Ihrem Shell-Profil).

AI_API_BASE verwendet standardmäßig den Endpunkt von Groq, akzeptiert aber jede OpenAI-kompatible API-URL.

Funktionsweise

Entitäten und Beobachtungen

Entitäten repräsentieren alles, was es wert ist, sich daran zu erinnern – Personen, Projekte, Entscheidungen, Fakten. Jede Entität hat:

• Einen Namen und einen Typ

• Felder für räumliche Wiederholung: verifiedAt, reviewInterval, nextReviewAt

• Ein Vertrauens-Label, das aus der Aktualität berechnet wird: 1 - (TageSeitVerifizierung / Überprüfungsintervall)

Beobachtungen werden als separate Entitäten gespeichert, die über is_observation_of-Beziehungen verknüpft sind. Jede Beobachtung hat ihren eigenen Überprüfungsrhythmus:

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

Aktualitätslebenszyklus

1. Entität erstellt — confidence: "fresh", Standardüberprüfung in 7 Tagen

2. Überprüfungsdatum verstrichen — confidence: "aging", needsReview: true

3. Agent verifiziert (via verify_entity) — Intervall verdoppelt sich, Vertrauen wird auf "frisch" zurückgesetzt

4. Lange überfällig — confidence: "stale" dann "archival", von der Standardsuche ausgeschlossen

Progressive Suche

Bei der Suche verwendet der Server drei Durchläufe:

1. freshness >= 0 — frische und normale Entitäten

2. freshness >= -2 — fügt alternde und veraltete hinzu

3. Kein Filter — fügt archivierte hinzu

Dies hält die Ergebnisse sauber und stellt gleichzeitig sicher, dass nichts dauerhaft verloren geht.

MCP-Tools

Umgebungsvariablen

Empfohlene Anweisungen für Agenten

Damit Agenten den Memory-Server aktiv nutzen, fügen Sie etwas Ähnliches zu Ihrer CLAUDE.md (oder einer entsprechenden Anweisungsdatei) hinzu:

## 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

Die wichtigste Erkenntnis: Agenten benötigen explizite, triggerbasierte Anweisungen ("wenn X, tue Y"), nicht nur Beschreibungen dessen, was das Tool tut.

Entwicklung

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

Lizenz

MIT