mcp-brain-tools

MCP-сервер, который предоставляет ИИ-агентам постоянную память со встроенным отслеживанием актуальности и интервальными повторениями. Работает на базе Elasticsearch.

В отличие от простых хранилищ памяти типа «ключ-значение», mcp-brain-tools отслеживает возраст каждой единицы знаний, помечает то, что требует проверки, и позволяет агентам подтверждать информацию для поддержания её актуальности — по аналогии с тем, как интервальные повторения помогают людям запоминать информацию.

Возможности

• Актуальность через интервальные повторения — каждая сущность имеет интервал проверки, который удваивается при подтверждении (максимум 365 дней). Метки достоверности (свежая/нормальная/устаревающая/устаревшая/архивная) подсказывают агентам, чему можно доверять.

• Прогрессивный поиск — запросы сначала возвращают свежие результаты, автоматически расширяясь для включения старых данных только при необходимости.

• Наблюдения как сущности — каждое наблюдение имеет свой жизненный цикл актуальности, поэтому «сборка сломана» (проверка через 1 день) и «основано в 2015 году» (проверка через 365 дней) стареют независимо.

• Зоны памяти — изоляция знаний по проектам, командам или доменам.

• Фильтрация на базе ИИ — опциональная интеграция с Groq оценивает результаты поиска по релевантности.

• Принцип DRY (Don't Repeat Yourself) — описания инструментов направляют агентов не хранить то, что уже есть в коде, git или документации.

Related MCP server: Logseq MCP Tools

Настройка

Предварительные требования

• Node.js >= 18

• Docker (для Elasticsearch) или удаленный экземпляр Elasticsearch

Установка и сборка

npm install
npm run build

Запуск Elasticsearch

npm run es:start

Или укажите свой собственный экземпляр через переменную окружения ES_NODE.

Настройка MCP-клиента

Добавьте в конфигурацию Claude Code, Claude Desktop или другого 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 является опциональным — он включает фильтрацию поиска на базе ИИ и оценку релевантности зон.

Установка хука автоматической памяти (только для Claude Code)

Хук памяти запускается при каждом сообщении пользователя и автоматически внедряет соответствующий контекст — участие агента не требуется.

Добавьте в ~/.claude/settings.json:

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

Хук использует те же переменные окружения ES_NODE, AI_API_KEY/GROQ_API_KEY, AI_API_BASE и AI_MODEL (установите их в блоке env ваших настроек или экспортируйте в профиле оболочки).

AI_API_BASE по умолчанию указывает на эндпоинт Groq, но принимает любой URL API, совместимый с OpenAI.

Как это работает

Сущности и наблюдения

Сущности представляют всё, что стоит запомнить — людей, проекты, решения, факты. Каждая сущность имеет:

• Имя и тип

• Поля интервальных повторений: verifiedAt, reviewInterval, nextReviewAt

• Метку достоверности, вычисляемую на основе актуальности: 1 - (daysSinceVerified / reviewInterval)

Наблюдения хранятся как отдельные сущности, связанные через отношения is_observation_of. Каждое наблюдение имеет свой цикл проверки:

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

Жизненный цикл актуальности

1. Создание сущности — confidence: "fresh", проверка по умолчанию через 7 дней

2. Истечение даты проверки — confidence: "aging", needsReview: true

3. Подтверждение агентом (через verify_entity) — интервал удваивается, достоверность сбрасывается до «свежей»

4. Длительная просрочка — confidence: "stale", затем "archival", исключается из поиска по умолчанию

Прогрессивный поиск

При поиске сервер использует три прохода:

1. freshness >= 0 — свежие и нормальные сущности

2. freshness >= -2 — добавляются устаревающие и устаревшие

3. Без фильтра — добавляются архивные

Это позволяет поддерживать чистоту результатов, гарантируя, что ничего не будет потеряно безвозвратно.

Инструменты MCP

Переменные окружения

Рекомендуемые инструкции для агентов

Чтобы агенты активно использовали сервер памяти, добавьте что-то подобное в ваш CLAUDE.md (или эквивалентный файл инструкций):

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

Ключевая мысль: агентам нужны явные инструкции, основанные на триггерах («когда X, сделай Y»), а не просто описания того, что делает инструмент.

Разработка

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

Лицензия

MIT