Полная документация -- руководства, справочник инструментов, архитектура и обслуживание на cachorro.space

mcp-memory

Прямая замена для сервера MCP Memory от Anthropic — с поддержкой постоянного хранения в SQLite, векторными эмбеддингами, семантическим поиском и Limbic Scoring для динамического ранжирования.

Зачем? Оригинальный сервер записывает весь граф знаний в файл JSONL при каждой операции, без блокировок или атомарных записей. При параллельном доступе (несколько MCP-клиентов) это приводит к повреждению данных. Этот сервер заменяет такой подход полноценной базой данных SQLite.

Возможности

• Полная совместимость с 8 инструментами MCP от Anthropic (тот же API, то же поведение)

• SQLite + WAL — безопасный параллельный доступ, больше никаких поврежденных JSONL

• Семантический поиск через sqlite-vec + ONNX-эмбеддинги (94+ языка)

• Гибридный поиск (FTS5 + KNN) — объединяет полнотекстовый поиск BM25 и семантический векторный поиск через Reciprocal Rank Fusion. Находит сущности по точным терминам, семантическому сходству или и по тому, и по другому одновременно.

• Limbic Scoring — динамическое переранжирование с учетом значимости, временного затухания, сигналов совместного появления и оценок гибридного поиска. Прозрачно для API.

• Семантическая дедупликация — автоматический флаг similarity_flag для новых наблюдений при косинусном сходстве >= 0.85 (с учетом оценки вложенности для текстов разной длины)

• Отчеты о консолидации — отчеты «только для чтения» для поиска кандидатов на разделение, помеченных наблюдений, устаревших сущностей и крупных сущностей

• Улучшенное затухание по давности — отслеживание entity_access_log с сигналом консолидации ALPHA_CONS=0.2 за несколько дней

• Исправление вложенности — корректная обработка текстов разной длины (соотношение >= 2.0) при оценке дедупликации

• Типы наблюдений — семантическая классификация наблюдений (hallazgo, decision, estado, spec, metrica, metadata, generic)

• Замещение наблюдений — явная цепочка замены: новые наблюдения могут замещать старые, которые помечаются меткой времени как замещенные

• Статус сущности — отслеживание жизненного цикла: activo, pausado, completado, archivado (с понижением приоритета при поиске в зависимости от статуса)

• Контекст отношений + срок действия — отношения содержат необязательный контекст, поля active/ended_at для временной валидности

• Автоматические обратные отношения — пары contains/parte_de создаются автоматически

• Размышления (Reflections) — независимый повествовательный слой: свободный текст, привязанный к сущностям/сессиям/отношениям/глобальному уровню, с метаданными автора и настроения, доступный для поиска через гибрид семантического поиска + FTS5

• Легковесность — ~500 МБ всего против ~1.4 ГБ у аналогичных решений

• Миграция — импорт в один клик из формата JSONL от Anthropic

• Нулевая настройка — работает «из коробки», опциональная загрузка модели для семантического поиска

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

1. Добавьте в конфигурацию MCP

{
  "mcpServers": {
    "memory": {
      "command": ["uvx", "--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
    }
  }
}

Или клонируйте и запустите локально:

{
  "mcpServers": {
    "memory": {
      "command": ["uv", "run", "--directory", "/path/to/mcp-memory", "mcp-memory"]
    }
  }
}

2. Включите семантический поиск (опционально)

cd /path/to/mcp-memory
uv run python scripts/download_model.py

Это загрузит многоязычную модель предложений (~465 МБ) в ~/.cache/mcp-memory-v2/models/. Без нее все инструменты будут работать нормально — будет недоступен только search_semantic.

3. Миграция существующих данных (опционально)

Если у вас есть файл JSONL от Anthropic MCP Memory, используйте инструмент migrate или вызовите его напрямую:

uv run python -c "
from mcp_memory.storage import MemoryStore
from mcp_memory.migrate import migrate_jsonl
store = MemoryStore()
store.init_db()
result = migrate_jsonl(store, '~/.config/opencode/mcp-memory.jsonl')
print(result)
"

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

Основные (совместимые с Anthropic)

Поиск и анализ

Управление сущностями

Размышления (Reflections)

Типы сущностей

8 канонических типов:

Виды наблюдений

Семантическая классификация для наблюдений:

Типы отношений

4 категории:

Обратные отношения создаются автоматически для пар contiene/parte_de.

Архитектура

server.py (FastMCP)  <--  storage.py (SQLite + sqlite-vec + FTS5)
                               |
                         embeddings.py (ONNX Runtime)
                               |
                         sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
                         (384d, multilingual, cosine similarity)
                               |
                         scoring.py (Limbic Scoring + RRF)
                         salience . temporal decay . co-occurrence

• Хранилище: SQLite с журналом WAL, 5-секундным таймаутом ожидания, каскадным удалением

• Эмбеддинги: Одиночная модель ONNX, загружаемая один раз при запуске, косинусный поиск с L2-нормализацией

• Limbic Scoring: Переранжирует гибридных (KNN + FTS5) кандидатов, используя сигналы важности, временное затухание, паттерны совместного появления и оценки RRF — прозрачно для API

• Параллелизм: SQLite обрабатывает блокировки внутренне — без fcntl, без конфликтов файловой системы

• Размышления: Параллельные индексы FTS5 (reflection_fts) и векторные (reflection_embeddings) для повествовательного слоя, поиск через тот же гибридный конвейер RRF

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

Каждая сущность получает вектор эмбеддинга, сгенерированный из ее текста с использованием стратегии выбора Head+Tail+Diversity (бюджет: 480 токенов):

"{name} ({entity_type}) | {obs1} | {obs2} | ... | Rel: type -> target; ..."

Когда вы вызываете search_semantic, конвейер работает параллельно:

1. Семантический (KNN) — запрос кодируется и сравнивается с векторами сущностей через sqlite-vec

2. Полнотекстовый (FTS5) — запрос ищется по индексу BM25, охватывающему имена, типы и содержание наблюдений

3. Объединение (RRF) — результаты из обеих ветвей объединяются с использованием Reciprocal Rank Fusion (score(d) = Sum 1/(k + rank))

Объединенные кандидаты затем переранжируются движком Limbic Scoring, который учитывает:

• Значимость — часто используемые и хорошо связанные сущности ранжируются выше

• Временное затухание — недавно использованные сущности остаются «свежими»; нетронутые сущности затухают

• Совместное появление — сущности, которые часто появляются вместе, усиливают друг друга

Вывод включает limbic_score, scoring (разбивка по важности/времени/совместному появлению) и опционально rrf_score, когда FTS5 вносит результаты.

Для получения полных технических деталей см. DOCUMENTATION.md — включает формулу оценки, константы RRF, DDL схемы и архитектурные диаграммы.

Тестирование

uv run pytest tests/ -v

Более 285 тестов в 15 тестовых файлах, охватывающих все инструменты, эмбеддинги, оценку и граничные случаи. Нулевая регрессия.

Требования

• Python >= 3.12

• uv (менеджер пакетов)

Зависимости

Лицензия

MIT