convez.ai
MCP ServerProdutividadeAvançado
Arelion999

Memory Compiler

Arelion999/memory-compiler

Memória persistente com busca híbrida para Claude e assistentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que implementa memória persistente para assistentes de IA através de base de conhecimento em markdown com busca híbrida (BM25F + semântica). Armazena decisões arquiteturais, runbooks, lições aprendidas e tracking de estado temporal, com sincronização automática entre sessões e interface web integrada.

Instalação

$npx convez-ai Arelion999/memory-compiler

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 5 dias
Versão
—
Issues abertas
2
Contribuidores
1

Casos de uso

  • Manter contexto de projetos entre sessões do Claude
  • Registrar e recuperar soluções de bugs e erros conhecidos
  • Documentar decisões arquiteturais com rastreamento de versões
  • Armazenar runbooks e procedimentos operacionais com checkpoints
  • Gerenciar estado temporal de infraestrutura e configurações

Veredito

Solução robusta e bem-arquitetada para o problema real de memória em sessões de IA. Implementação de busca híbrida com decay temporal é sofisticada; requer Python/Docker e setup inicial, mas oferece ROI alto para fluxos de trabalho repetitivos e documentação viva.

README

A tradução para o português deste README ainda está na fila.

memory-compiler

Персональная база знаний для AI-ассистентов. MCP-сервер с гибридным поиском, автокомпиляцией и веб-интерфейсом.

Зачем

AI-ассистенты не помнят контекст между сессиями. memory-compiler решает эту проблему: решения, баги, конфигурации сохраняются в markdown-статьях, индексируются и доступны через MCP или HTTP API. Ассистент ищет похожие кейсы перед задачей и записывает новые решения после.

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

pip install -r requirements.txt
mkdir -p knowledge
PROJECTS=my-project,infra,general python server.py

Сервер запустится на http://localhost:8765. Или через Docker:

docker-compose up -d --build

Подключение к Claude Code

{
  "mcpServers": {
    "memory-compiler": {
      "type": "sse",
      "url": "http://localhost:8765/sse"
    }
  }
}

Подключение к Claude Code Desktop

Полная инструкция: docs/claude-desktop-setup.md — MCP, скил memory-autopilot, hooks, настройка зависимостей.

Возможности

44 MCP-инструмента

Поиск и чтение:

ИнструментОписание
search(query, project)Гибридный поиск BM25F + semantic с temporal decay
ask(question, project)Q&A — ответ с цитатами из статей
search_by_tag(tag, project)Все статьи с указанным тегом
search_snippets(query, lang, project)Поиск по кодовым блокам
search_error(error_text, project)Поиск по трейсбекам и кодам ошибок
search_decisions(query, project)Поиск по журналу решений
read_article(project, filename)Полный текст статьи
get_context(project, query)Топ релевантных статей перед задачей
get_summary(project)Сжатая сводка проекта (~200 токенов)

Запись и редактирование:

ИнструментОписание
save_lesson(topic, content, project, tags)Сохранить с diff-отчётом, автомержем, автотегами, детекцией противоречий
save_decision(title, decision, alternatives, reasoning, project)Записать архитектурное решение
save_runbook(topic, steps, project)Создать пошаговую инструкцию с чекбоксами
save_from_template(template, fields, project)Создать статью по шаблону (bug, setup, 1c, deploy, integration)
save_secret(topic, content, project)Сохранить зашифрованную статью (пароли, ключи)
edit_article(project, filename, content, append)Заменить или дописать
delete_article(project, filename)Удалить статью
get_runbook(project, filename)Получить runbook с прогрессом
list_templates()Список доступных шаблонов

Сессии:

ИнструментОписание
save_session(project, summary, ...)Сохранить контекст для следующей сессии
load_session(project)Загрузить контекст + уведомления об устаревших статьях
get_active_context(project)Лента последних 10 действий

Temporal state:

ИнструментОписание
save_tracking(project, entity, facts)Bi-temporal снимок: текущее состояние + история (версии, деплои, конфиги)
get_current(project, entity)Получить текущий статус из tracking-статьи

Комбинированные:

ИнструментОписание
start_task(topic, project)Начать задачу: поиск + сессия + контекст + решения + runbooks
finish_task(topic, content, project)Завершить задачу: сохранить урок + сессию

Управление проектами:

ИнструментОписание
add_project(name)Создать новый проект
remove_project(name)Удалить проект со всеми статьями
list_projects()Список проектов с количеством статей
set_project_deps(project, depends_on)Установить зависимости между проектами
get_project_deps(project)Получить зависимости проекта

Обслуживание:

ИнструментОписание
ingest(url, project, ...)Загрузка знаний из URL (HTML→markdown) или raw_text (PDF/документы)
import_obsidian(vault_path, project, folder_mapping, dry_run)Импорт заметок из Obsidian vault (frontmatter, теги, wiki-ссылки)
git_capture(repo_path, project, ...)Автосбор знаний из git-коммитов (repo_path или git_log_raw)
knowledge_gap(repo_path, project, days)Найти темы в git-коммитах, которых нет в базе знаний
compile(dry_run, project, since)Компиляция дневных логов в wiki-статьи
lint(project, fix)Проверка: дубли, устаревшее, теги
reindex()Переиндексация
article_history(project, filename)Git-история статьи

Гибридный поиск + reranking

Три уровня релевантности:

  • BM25F (Whoosh) — полнотекстовый с весами полей (title x5, tags x3, body x1)
  • Semantic — bi-encoder embeddings (дефолт paraphrase-multilingual-MiniLM-L12-v2; через env EMBED_MODEL переключается на BAAI/bge-m3 1024d или Alibaba-NLP/gte-multilingual-base, кэш авто-инвалидируется при смене)
  • Cross-encoder reranking — BAAI/bge-reranker-v2-m3 (multilingual, built on BGE-M3, сильный RU+EN) пересортировывает топ-20 кандидатов для финального выбора (precision@3 +15-20%); опционально SPLADE 3-way через SPLADE_ENABLED=true
hybrid_score = (0.4 × BM25 + 0.6 × semantic) × decay_factor
final = cross_encoder.rerank(hybrid_top_20) → top_3

Temporal decay — свежие и часто используемые статьи выше в результатах.

Умное сохранение

При save_lesson автоматически:

  1. Запись в дневной лог (аудит-трейл)
  2. Автотегирование (14 regex-правил)
  3. Поиск существующей статьи по смыслу — мерж вместо дубля
  4. Обнаружение противоречий (IP, версии, URL, порты) — role-aware: разные роли IP (private vs public) и well-known DNS (8.8.8.8, 1.1.1.1, …) не дают FP; CIDR-нотация не сравнивается как host
  5. Cross-references в связанных статьях
  6. Обновление ленты активного контекста
  7. Извлечение git-ссылок (коммиты, issues, теги)
  8. Git commit

Веб-интерфейс

Встроенный мобильный UI на http://localhost:8765. Тёмная/светлая тема.

  • Поиск — snippets с подсветкой совпадений (жёлтый), фильтр по проекту, кликабельные теги, markdown-рендеринг, breadcrumbs, auto-scroll к первому match
  • Добавить — форма записи
  • Граф — Obsidian-style анимированный граф: drag, zoom, pan, фильтр по проектам, hover-подсветка связей
  • Компиляция — превью и запуск
  • Аналитика — топ по обращениям, неиспользуемые статьи
  • Аудит — лог всех MCP-обращений

REST API

18 endpoints: health, версия, логин/auth, поиск, сохранение, CRUD статей, проекты, граф знаний, аналитика, теги, компиляция (превью/запуск), экспорт, аудит.

Автоматизация

  • Автокомпиляция дневных логов в 02:00
  • Git-версионирование всех изменений
  • Кэш embeddings для быстрого старта
  • Уведомления об устаревших статьях

Безопасность

Три уровня защиты, каждый включается через env переменную:

УровеньПеременнаяЧто делает
АвторизацияMC_API_KEYЛогин-страница + cookie 30 дней, Bearer token, ?key= в URL
ШифрованиеMC_ENCRYPT_KEYAES-256 для секретных статей (save_secret)
АудитавтоматическиЛог всех MCP-вызовов, вкладка "Аудит" в Web UI

Без переменных — открытый доступ (обратная совместимость). Подробнее: docs/security.md

Структура проекта

memory-compiler/
├── server.py                  # Entry point (12 строк)
├── memory_compiler/
│   ├── __init__.py
│   ├── config.py              # Константы, метаданные, shared state
│   ├── search.py              # Whoosh BM25F + semantic search
│   ├── storage.py             # Статьи, git, утилиты, автотегирование
│   ├── handlers.py            # Реализация MCP-инструментов
│   ├── tools.py               # Регистрация MCP tools и диспетчер
│   ├── api.py                 # REST endpoints, Starlette app
│   └── ui.py                  # Web UI HTML шаблон
├── tests/
│   ├── conftest.py            # Фикстуры (tmp knowledge dir)
│   ├── test_config.py
│   ├── test_storage.py
│   ├── test_search.py
│   └── test_handlers.py
├── skills/
│   └── memory-autopilot/
│       └── SKILL.md           # Скил автоуправления памятью для Claude Code
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

Тесты

pip install pytest pytest-asyncio
pytest tests/ -v

Стек

КомпонентТехнология
СерверPython 3.12, MCP SDK, Starlette, Uvicorn
Полнотекстовый поискWhoosh (BM25F)
Семантический поискsentence-transformers
ХранилищеMarkdown + Git

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

С memory-autopilot (рекомендуется)

Скил memory-autopilot автоматизирует весь цикл — ищет контекст, выбирает tool, сохраняет результат. Пользователь просто работает, память управляется невидимо.

Установка: скопируйте skills/memory-autopilot/SKILL.md в ~/.claude/skills/memory-autopilot/SKILL.md.

Ручной режим

1. Начало задачи    → start_task("тема")       ← поиск + сессия + контекст
2. В процессе       → ask("как настроить X?")
3. Решение найдено  → finish_task(...)          ← урок + сессия

Конфигурация

Проекты создаются динамически через add_project() или автоматически при save_lesson(). Каждый проект — отдельная директория в knowledge/ с markdown-статьями.

Опционально можно задать начальные проекты через переменную окружения:

PROJECTS=backend,infra,general python server.py

Git Capture

Два режима автосбора знаний из git:

Режим 1 — repo_path (сервер читает git напрямую):

# .env
GIT_REPOS_PATH=/path/to/your/repos
git_capture(repo_path="/repos/my-project", project="myapp", auto_save=true)

Режим 2 — git_log_raw (клиент передаёт вывод git log):

# Claude запускает локально:
git log --format="%H|%s|%an|%aI" --numstat --since="7 days ago"
# и передаёт вывод в git_log_raw параметр

Повторные вызовы с repo_path автоматически обрабатывают только новые коммиты.

Лицензия

MIT

Ver o original no GitHub

Bom para

Relacionados