mcp-light-memory

Что это такое?

MCP Light Memory — это лёгкая, локальная, персистентная система памяти для кодинг-агентов и MCP-клиентов (Warp, OpenCode, JetBrains AI Assistant / PyCharm, Claude Code, Cursor). Она работает как слой чекпойнтов + поиска — хранит минимальное долговременное состояние, необходимое для возобновления сложной работы между сессиями, не удерживая весь разговор в контекстном окне модели.

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

Related MCP server: M3 Memory

Зачем это нужно?

Как это работает (механизмы)

• Markdown — источник истины. Каждое воспоминание — это .md-файл с YAML-frontmatter (id, type, status, tags, sources, links, valid_from, valid_to, supersedes). Читаемый человеком, диффабельный, долговечный.

• SQLite — пересобираемый кэш. Индекс BM25/FTS5 + опциональные векторы эмбеддингов + учёт использования. Удалите его — и всё пересоберётся из Markdown.

• Поиск: чистый Python BM25 + опциональные плотные эмбеддинги → слияние RRF → диверсификация MMR → усиление политиками (type/status/temporal) → отсечение по токен-бюджету. Адаптивный режим: сначала sparse, dense — только если слабый результат.

• Жизненный цикл: remember → update → supersede (связи в обе стороны, история никогда не удаляется) → forget (архивация, удаления нет) → timeline (временное представление). search --at YYYY-MM-DD для исторических запросов.

• Граница доверия: извлечённый контент оборачивается в === BEGIN/END INTERNAL_RAG MEMORY === с заголовком SECURITY NOTICE. Структурированный JSON/MCP несёт trust: untrusted + опциональный security_flags: ["instruction_like_content"].

• Свежесть свидетельств: каждый результат включает evidence_state (present/missing/unverifiable) для локального path-like свидетельства — вычисляется во время поиска, никогда не сохраняется.

• Мультипроектный роутер: один MCP stdio-сервер перед множеством проектов через JSON-registry. write:false блокирует изменяющие инструменты до запуска дочернего процесса. Изоляция через подпроцесс на каждый вызов (без общего состояния).

Установка

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

• Python 3.8+ (использует py launcher, python или python3 — установщик автоматически определяет настоящий интерпретатор и отклоняет заглушку WindowsApps)

• Git (целевой проект должен быть git-репозиторием)

• Опционально: pip install sentence-transformers numpy для лучшего семантического поиска

Текущая версия определяется файлом VERSION — проверяйте его (или запускайте mlm.py --version) вместо того, чтобы жёстко прописывать ожидаемый номер.

Быстрый старт

Клонируйте этот репозиторий один раз, затем установите в любой проект:

# Windows (PowerShell)
git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory
python ~/mcp-light-memory/install.py . --client warp

# Linux/macOS
git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory
python3 ~/mcp-light-memory/install.py . --client warp

Установщик:

• копирует файлы навыков и создаёт INTERNAL_RAG/ + AGENTS.md

• запускает init + checkpoint + validate (так что guard сразу в состоянии OK)

• автоматически регистрирует MCP-сервер в конфиге клиента, когда это можно сделать безопасно (или сообщает MANUAL_REQUIRED / выводит инструкции для JetBrains)

• записывает абсолютный путь к проверенному интерпретатору Python (переживает проблемы с PATH в Windows)

python .agents\skills\internal-rag\mlm.py --version   # reports the installed version
python .agents\skills\internal-rag\mlm.py status       # expect: INTERNAL_RAG ready
python .agents\skills\internal-rag\mlm.py guard        # expect: GUARD OK

Матрица установки

Один установщик, четыре клиента, две области конфигурации. Полное руководство: docs/INSTALLATION.md.

• --global изменяет область КЛИЕНТСКОГО КОНФИГА (~/.warp/.mcp.json vs {repo}/.warp/.mcp.json, ~/.config/opencode/opencode.json vs opencode.json проекта). Сервер по-прежнему указывает на целевой проект, в который вы устанавливали.

• Нужен один глобальный MCP-эндпоинт для многих репозиториев? Используйте мультипроектный роутер — docs/MCP-MULTI-PROJECT.md.

• JetBrains/PyCharm — частично автоматический: установщик подготовит JSON + Working Directory; сервер добавляете вы сами в Settings → Tools → AI Assistant → MCP и выбираете Server level = Project или Global.

• Ручная настройка (без установщика) для каждого клиента: docs/INSTALLATION.md + страницы клиентов (Warp · OpenCode).

Zero-shot: промпты для копирования в Warp и OpenCode

Вы можете вставить один из них прямо в агента клиента. Замените C:\Projects\App на реальный путь к целевому репозиторию.

Warp — установка для одного проекта:

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in Warp, using project scope. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, update it with git pull --ff-only. Apply the canonical installation contract from the repository and run install.py with TARGET_PROJECT=C:\Projects\App and --client warp without --global. Do not force-overwrite an existing configuration. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification. If Warp requires an additional project activation/toggle/approval, state the exact client-side step and do not claim the server is active before it is completed.

Warp — глобальный клиентский конфиг для одного проекта:

Install and configure MCP Light Memory (mcp-light-memory) in Warp globally for project C:\Projects\App. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Apply the canonical installation contract and run install.py with TARGET_PROJECT=C:\Projects\App, --client warp, and --global. Remember: --global means the global Warp client configuration, while the server must still be bound to C:\Projects\App; do not use the multi-project router. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification.

OpenCode — установка для одного проекта (stable/V1):

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in OpenCode. By "OpenCode" I mean stable/V1, so use --client opencode, not opencode2. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App and --client opencode without --global. Do not force-overwrite an existing configuration. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED (for example because opencode.jsonc exists), do not report success: safely edit the JSONC while preserving comments and unrelated settings if you have appropriate file-editing tools; otherwise report the exact manual action required. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the OpenCode configuration contains mcp-light-memory and C:\Projects\App.

OpenCode — глобальный клиентский конфиг для одного проекта (stable/V1):

Install and configure MCP Light Memory (mcp-light-memory) globally in OpenCode for project C:\Projects\App. By "OpenCode" I mean stable/V1, so use --client opencode. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App, --client opencode, and --global. --global means the global OpenCode client configuration, while the server must still be bound only to C:\Projects\App; do not use the multi-project router. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED, do not report success and follow the safe JSONC instructions. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global OpenCode configuration contains mcp-light-memory and the C:\Projects\App path.

Для OpenCode 2 / V2 используйте те же промпты, но явно укажите OpenCode 2 / V2 и требуйте --client opencode2. Больше вариантов: docs/ZERO-SHOT-SETUP-PROMPTS.md.

Детали конфигурации

Warp

Warp читает конфиги MCP-серверов из ~/.warp/.mcp.json (глобальный, автозапуск) или {repo}/.warp/.mcp.json (проектный, требует ручного переключения согласно документации Warp). Форма: mcpServers.<name> с command, args, working_directory (всегда указывайте его — хранилище памяти определяется относительно него). См. examples/warp.example.json и docs/WARP-SETUP.md.

OpenCode stable (V1)

OpenCode читает opencode.json/.jsonc в корне проекта или глобально ~/.config/opencode/opencode.json. Серверы V1 — плоские, в mcp.<name> (без подключа servers), с enabled: true и command в виде массива — см. examples/opencode-legacy.example.json и docs/OPENCODE.md.

OpenCode 2 (V2, beta)

Те же файлы конфигурации, другая форма: mcp.servers.<name>, command в виде массива и без поля enabled (в V2 отключение через disabled: true) — см. examples/opencode-v2.example.jsonc и docs/OPENCODE.md.

JetBrains AI Assistant / PyCharm

PyCharm НЕ читает автоматически никакие файлы конфигурации MCP. Установщик выводит готовый к вставке JSON + Working Directory; сервер добавляется в Settings → Tools → AI Assistant → MCP (STDIO), и выбирается Server level = Project или Global. См. examples/jetbrains.example.json.

Мультипроектный роутер

Одно MCP-подключение перед множеством проектов — registry allowlist, жёсткая граница write:false, изоляция через подпроцесс на каждый вызов.

Registry file (projects.json)

{
  "projects": {
    "backend": { "root": "/abs/path/backend", "write": true },
    "shared-lib": { "root": "/abs/path/shared-lib", "write": false }
  }
}

Warp config for the router

{
  "mcpServers": {
    "mcp-light-memory-router": {
      "command": "python3",
      "args": ["/abs/path/mcp-light-memory/.agents/skills/internal-rag/irag_mcp_router.py", "--registry", "/abs/path/projects.json"],
      "working_directory": "/abs/path/mcp-light-memory"
    }
  }
}

Подробности: docs/MCP-MULTI-PROJECT.md.

Рабочий процесс

context --task "current task"
  ↓
recovery, if required (RECOVERY REQUIRED)
  ↓
checkpoint before first change
  ↓
implementation
  ↓
checkpoint after each milestone
  ↓
guard before finishing

Основные команды (CLI-алиас: mlm.py или устаревший irag.py):

mlm.py context --task "..."
mlm.py checkpoint --reason "..."
mlm.py search --query "..." --limit 8
mlm.py remember --type decision --title "..." --body "..."
mlm.py show <ref>
mlm.py update <ref> --status superseded
mlm.py status
mlm.py guard
mlm.py validate
mlm.py doctor

Сопоставление путей (ребрендинг: internal-rag → MCP Light Memory)

Папка на диске INTERNAL_RAG/ и каталог навыков .agents/skills/internal-rag/ намеренно сохранены под прежними именами для обратной совместимости без миграции. См. docs/MIGRATION-TO-MCP-LIGHT-MEMORY.md.

Долговременная память (CRUD)

remember --type decision --title "..." --body "..." --tags "a,b" --evidence "src/x.py:42" --links "decisions/other.md"
show <path-or-id>
show <ref> --section Knowledge
update <ref> --add-tags "new" --append "New evidence: ..."
supersede <ref> --by <new> --reason "..."
forget <ref>              # archives, does not delete
link --from <ref> --to <ref>
timeline --limit 20
status
history

Типы: decision, knowledge, constraint, gotcha, failure, hypothesis, session.

Стек задач (прерывания)

mlm.py push --task "interrupted work" --reason "user-priority"
mlm.py tasks
mlm.py resume
mlm.py forget-task <id>   # drop a specific task
mlm.py forget-task         # clear the whole stack

Конфигурация (.irag.yml, опционально)

retrieval:
  limit: 10
  mmr_lambda: 0.4
  min_score: 0.3
  embeddings: auto        # auto | on | off
  profile: english-fast   # english-fast (default) | multilingual (PL/EN projects)
  embeddings_model: null  # explicit model overrides the profile
tokens:
  context_budget: 5000
checkpoints:
  auto_archive_sessions: true
  max_task_stack: 24

mlm.py config показывает действующую конфигурацию. mlm.py config --init создаёт шаблон.

Опциональные эмбеддинги (более качественный поиск)

pip install -r requirements-optional.txt

Когда пакет доступен и в .irag.yml указано embeddings: auto (по умолчанию), поиск использует эмбеддинги с откатом к BM25. Переопределить во время выполнения можно с помощью --embeddings on|off|auto.

Два профиля поиска (см. docs/EMBEDDINGS.md):

• english-fast (по умолчанию, all-MiniLM-L6-v2)

• multilingual (intfloat/multilingual-e5-small) — для польско-английских проектов

Офлайн / изолированная среда

python pack.py --with-embeddings --profile english-fast
# -> internal-rag-offline-1.8.1.zip   (name from pack.py; 1.8.1 = VERSION file)
# On the air-gapped machine:
unzip internal-rag-offline-*.zip -d internal-rag-offline
pip install --no-index --find-links wheels/ -r requirements-optional.txt
python install.py "/path/to/project" --client <warp|opencode|opencode2|jetbrains>

Подробности: docs/OFFLINE.md.

Конфиденциальность и Git

Режим установки по умолчанию — только локально. Установщик использует .git/info/exclude, а не .gitignore проекта, поэтому локальная память и интеграционные файлы не попадают в коммиты случайно.

Перед публикацией проекта:

python .\privacy_check.py "D:\path\to\project"

Ожидается: RESULT: PASS

Полное удаление из проекта

python .\uninstall.py "D:\path\to\project"

Деинсталлятор создаёт резервную копию за пределами репозитория, затем удаляет INTERNAL_RAG и его интеграции. Используйте --keep-memory, чтобы сохранить данные памяти.

Документация

• Установка · Ежедневное использование · Справочник CLI

• Архитектура · Жизненный цикл памяти · Восстановление

• MCP · Многопроектный MCP

• Архитектурные решения (ADR) · Конфигурация

• Эмбеддинги · Офлайн · Git-хуки

• Конфиденциальность и Git · Удаление · Устранение неполадок

• Промпты настройки zero-shot · Миграция · Брендинг

Структура в целевом проекте

project/
├── AGENTS.md
├── .irag.yml                    # optional config
├── INTERNAL_RAG/
│   ├── WORKING_STATE.md
│   ├── INDEX.md
│   ├── .checkpoint.json
│   ├── decisions/  knowledge/  gotchas/  failures/  hypotheses/  sessions/  archive/
│   └── exports/
├── .agents/skills/internal-rag/
│   ├── SKILL.md
│   ├── mlm.py                   # primary CLI (forwards to irag.py)
│   ├── irag.py                  # core (legacy alias, still the canonical module)
│   ├── irag_embeddings.py       # optional plugin
│   └── irag_hooks.py            # optional git hooks
└── .opencode/                   # OpenCode integration (optional)

Источник истины

1. текущие инструкции пользователя, 2. текущий код/тесты/конфигурация, 3. спецификации/ADR, 4. проверенная память, 5. заметки сессий, 6. гипотезы.

Память может быть устаревшей. Код имеет приоритет.

Лицензия

MIT.

Журнал изменений

1.8.0 — Ручная настройка JetBrains

• --client jetbrains больше не записывает фиктивный файл конфигурации (PyCharm игнорирует MCP-файлы конфигурации). Вместо этого выводит готовый к вставке JSON + инструкции по меню IDE.

• --unregister --client jetbrains выводит напоминание об удалении в интерфейсе IDE.

1.7.2 — JetBrains cwd + сообщения для конкретных клиентов

• JetBrains: записывает working_directory в качестве подсказки + выводит WARNING с точным путём для указания в Settings → Tools → AI Assistant → MCP.

• Сообщения о перезапуске для конкретных клиентов (Перезапустите PyCharm / Перезапустите Warp / Перезапустите OpenCode).

• Memory store: <path> выводится в результате установки для немедленной проверки.

1.7.1 — Исправление заглушки Python в Windows

• detect_python() отклоняет 0-байтовую заглушку WindowsApps; предпочитает py -0p; проверяет каждого кандидата с помощью --version.

• Проверка после регистрации: запускает --version сразу после записи конфигурации и сообщает PASS/FAIL.

• --unregister удаляет пустые файлы конфигурации + родительские каталоги (исправляет мёртвый скелет .warp/.mcp.json → GUARD STALE).

1.7.0 — Ребрендинг в MCP Light Memory

• Полный ребрендинг с internal-rag на MCP Light Memory (mcp-light-memory). Новый CLI-алиас mlm (mlm.py). Логотип/иконки. Документ по миграции. Чек-лист ребрендинга на GitHub.

• Обратно совместимо: irag.py, INTERNAL_RAG/, старые имена MCP-серверов сохранены как устаревшие алиасы.

• 18 тестов на согласованность ребрендинга.

1.6.1 — Ужесточение после v1.6

• Бенчмарк мутаций/жизненного цикла (11 сценариев). Граница доверия (ADR-015): trust: untrusted + security_flags. Свежесть свидетельств (ADR-016): evidence_state. Масштабный бенчмарк (100/1k/10k). Регрессии безопасности роутера (+12 тестов). Тест на согласованность документации. 249 тестов проходят.

1.6.0 — Качество поиска + MCP 2026-07-28

• Бенчмарк качества памяти (37 случаев). Двухэпохальный MCP 2026-07-28 (server/discover, _meta, structuredContent, outputSchema). Строгий write в реестре. Источники в префиксе чанка. Адаптивный поиск. Контекст с учётом ссылок. consolidate --prepare. Бенчмарк задержки роутера. ADR-010…016.

1.5.0 — Гейт воздержания + многопроектный роутер

• Гейт релевантности/воздержания (--meta). Предварительная фильтрация кандидатов FTS5. Многопроектный MCP-роутер. Ужесточение MCP-протокола (чистый stdout, проверено SDK). 168 тестов.

1.4.0 — Разбиение на чанки + дедупликация + временной жизненный цикл

• Разбиение на чанки с учётом разделов (схема v3). Дедупликация SimHash. Многоязычный профиль PL/EN. Временной жизненный цикл (valid_from/valid_to/supersedes/--at). consolidate --dry-run.

1.3.0 — Постоянный кэш эмбеддингов

• float32 BLOB-ы уровня чанков в SQLite. Несколько моделей сосуществуют. index --vacuum/--embed-missing.

1.0.2 — Бюджет токенов + конфиденциальность

• Принудительное соблюдение бюджета токенов. Обнаружение устаревшей памяти. Обнаружение дубликатов. Сканирование конфиденциальности при записи. Таймер автоматических контрольных точек. Офлайн/изолированный пакет.

1.0.0 — Первый релиз

• Поиск BM25 + MMR. Полный CRUD памяти. Стек задач. MCP-сервер (JSON-RPC stdio). Git-хуки. Диагностика. Экспорт/импорт. Бюджет токенов.