👁 Quality Gate Status
👁 Bugs
👁 Vulnerabilities
👁 Code Smells
👁 Coverage
👁 Duplicated Lines (%)

Claude Memory MCP — Универсальная память для диалогов с ИИ

Сервер протокола контекста модели (MCP), обеспечивающий постоянную, доступную для поиска память диалогов на различных ИИ-платформах. Сохраняйте, ищите и извлекайте историю диалогов с помощью полнотекстового поиска со скоростью менее миллисекунды на базе SQLite FTS5.

Функции

• 🔍 Полнотекстовый поиск со скоростью менее миллисекунды через SQLite FTS5 с ранжированием по релевантности

• 🏷️ Автоматическое извлечение тем — более 574 уникальных тем в более чем 2000 ассоциациях

• 📊 Еженедельные сводки с аналитикой и закономерностями

• 🗃️ Организованное хранение файлов по дате и теме

• 🤖 Поддержка нескольких платформ — Claude, ChatGPT, Cursor AI и пользовательские форматы

• 🔌 Интеграция MCP для Claude Desktop и Claude Code

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

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

• Python 3.11+ (протестировано на 3.11.12)

• Рекомендуется среда Ubuntu/WSL

• Claude Desktop (для интеграции MCP)

Установка

Вариант 1: Установка с помощью Claude Code (рекомендуется)

Быстрая установка — скопируйте и вставьте это в Claude Code:

claude mcp add --transport stdio claude-memory -- sh -c "cd $HOME/Code/claude-memory-mcp && python3 src/server_fastmcp.py"

Важно: Замените $HOME/Code/claude-memory-mcp на фактический путь, по которому вы клонировали этот репозиторий.

Примеры для разных расположений:

# If cloned to ~/Code/claude-memory-mcp (default)
claude mcp add --transport stdio claude-memory -- sh -c "cd $HOME/Code/claude-memory-mcp && python3 src/server_fastmcp.py"

# If cloned to ~/projects/claude-memory-mcp
claude mcp add --transport stdio claude-memory -- sh -c "cd $HOME/projects/claude-memory-mcp && python3 src/server_fastmcp.py"

# If cloned to ~/dev/claude-memory-mcp
claude mcp add --transport stdio claude-memory -- sh -c "cd $HOME/dev/claude-memory-mcp && python3 src/server_fastmcp.py"

Что это делает:

• --transport stdio: Использует стандартный ввод/вывод для локальных процессов

• claude-memory: Идентификатор сервера

• --: Отделяет флаги CLI Claude от команды сервера

• sh -c "cd ... && python3 ...": Переходит в каталог проекта перед запуском сервера

Это автоматически добавляет MCP-сервер в конфигурацию Claude Desktop.

Документация: https://code.claude.com/docs/en/mcp

Вариант 2: Установка вручную

1. Клонируйте репозиторий:

   git clone https://github.com/yourusername/claude-memory-mcp.git
   cd claude-memory-mcp

2. Настройте виртуальное окружение:

   python3 -m venv .venv
   source .venv/bin/activate

3. Установите зависимости:

   pip install -e .

   Это устанавливает пакет в редактируемом режиме вместе со всеми необходимыми зависимостями:

   • mcp[cli]>=1.9.2 - Протокол контекста модели

   • jsonschema>=4.0.0 - Валидация JSON-схемы

   • aiofiles>=24.1.0 - Асинхронные файловые операции

4. Протестируйте систему:

   python3 tests/validate_system.py

Базовое использование

Автономное тестирование

# Test core functionality
python3 tests/standalone_test.py

Режим MCP-сервера

# Run as MCP server (from project root)
python3 src/server_fastmcp.py

# Or from src directory
cd src && python3 server_fastmcp.py

Массовый импорт

# Import conversations from JSON export
python3 scripts/bulk_import_enhanced.py your_conversations.json

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

search_conversations(query, limit=5)

Полнотекстовый поиск по всем сохраненным диалогам с ранжированием по релевантности.

search_by_topic(topic, limit=10)

Поиск диалогов, помеченных определенной темой.

add_conversation(content, title, date)

Сохранение нового диалога с автоматическим извлечением тем и индексацией FTS.

generate_weekly_summary(week_offset=0)

Создание аналитики и закономерностей на основе недавних диалогов.

get_search_stats()

Просмотр статистики поисковой системы — размер индекса, количество тем и статус движка.

Архитектура

~/claude-memory/
├── conversations/
│ ├── 2025/
│ │ └── 06-june/
│ │ └── 2025-06-01_topic-name.md
│ ├── index.json # Search index
│ └── topics.json # Topic frequency
└── summaries/
 └── weekly/
 └── week-2025-06-01.md

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

Интеграция с Claude Desktop

Добавьте в конфигурацию MCP Claude Desktop:

{
 "mcpServers": {
 "claude-memory": {
 "command": "python",
 "args": ["/path/to/claude-memory-mcp/server_fastmcp.py"]
 }
 }
}

Расположение хранилища

Хранилище по умолчанию: ~/claude-memory/

Переопределите с помощью переменной окружения:

export CLAUDE_MEMORY_PATH="/custom/path"

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

Формат логов

Переключайтесь между текстовыми логами, читаемыми человеком (по умолчанию), и структурированными JSON-логами для продакшена:

# JSON format (for production log aggregation)
export CLAUDE_MCP_LOG_FORMAT=json

# Text format (default, for development)
export CLAUDE_MCP_LOG_FORMAT=text

Пример JSON-лога:

{
 "timestamp": "2025-01-15T10:30:45",
 "level": "INFO",
 "logger": "claude_memory_mcp",
 "function": "add_conversation",
 "line": 145,
 "message": "Added conversation successfully",
 "context": {
 "type": "performance",
 "duration_seconds": 0.045,
 "conversation_id": "conv_abc123"
 }
}

JSON-логирование идеально подходит для:

• Развертывания в продакшене с агрегацией логов (Datadog, ELK, CloudWatch)

• Автоматизированного мониторинга и оповещения

• Структурированного анализа логов и запросов

• Отслеживания производительности и отладки

Подробную документацию по JSON-логированию см. в docs/json-logging.md.

Структура файлов

claude-memory-mcp/
├── src/
│ ├── server_fastmcp.py # Main MCP server
│ ├── conversation_memory.py # Core memory engine + SQLite FTS5
│ ├── format_detector.py # Auto-detect AI platform format
│ ├── validators.py # Input validation
│ ├── logging_config.py # Structured logging (text/JSON)
│ ├── importers/ # Platform-specific importers
│ │ ├── chatgpt_importer.py
│ │ ├── claude_importer.py
│ │ ├── cursor_importer.py
│ │ └── generic_importer.py
│ └── schemas/ # JSON schema validation
├── tests/ # 435 tests, 98.68% coverage
├── data/ # Consolidated app data
├── scripts/ # Import and utility scripts
└── docs/ # Documentation

Производительность

Полнотекстовый поиск SQLite FTS5, протестированный на 347 индексированных диалогах:

• Скорость поиска: 0,2–0,5 мс на запрос (в 4,4 раза быстрее, чем линейное сканирование JSON)

• Поиск по темам: 0,3–0,4 мс по 574 уникальным темам

• Скорость записи: ~33 мс на диалог (включая индексацию)

• Емкость: 371 диалог в промышленной эксплуатации за 10 месяцев

• Покрытие тестами: 98,68% (435 тестов) — 0 запахов кода, 0 узких мест безопасности (проверено SonarCloud)

Последнее тестирование: апрель 2026 г. | Подробный отчет

Примечание для разработчиков: Тесты производительности создают каталог ~/claude-memory-test для изолированного тестирования. Обычное использование MCP использует только ~/claude-memory/. Если вы видите ~/claude-memory-test, его можно безопасно удалить.

Примеры поиска

# Technical topics
search_conversations("terraform azure")
search_conversations("mcp server setup")
search_conversations("python debugging")

# Project discussions 
search_conversations("interview preparation")
search_conversations("product management")
search_conversations("architecture decisions")

# Specific problems
search_conversations("dependency issues")
search_conversations("authentication error")
search_conversations("deployment configuration")

Разработка

Добавление новых функций

1. Извлечение тем: Измените _extract_topics() в ConversationMemoryServer

2. Алгоритм поиска: Улучшите метод search_conversations()

3. Создание сводки: Улучшите логику generate_weekly_summary()

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

# Run validation suite
python3 tests/validate_system.py

# Test individual components
python3 tests/standalone_test.py

# Run full test suite with coverage
python3 -m pytest tests/ --ignore=tests/standalone_test.py --cov=src --cov-report=term

# Import test data
python3 scripts/bulk_import_enhanced.py test_data.json --dry-run

Хранение тестовых данных (только для разработчиков): Если вы запускаете тесты производительности или генераторы тестовых данных, они создают каталог ~/claude-memory-test, чтобы изолировать тестовые данные от вашего рабочего каталога ~/claude-memory. Это только для разработки/тестирования — обычное использование MCP не создает этот каталог.

Чтобы очистить тестовые данные после запуска тестов:

rm -rf ~/claude-memory-test

Или используя цель очистки Makefile:

make clean-test-data

Устранение неполадок

Распространенные проблемы

Ошибки импорта MCP:

pip install mcp[cli] # Include CLI extras

Поиск не возвращает результатов:

• Проверьте индексацию диалогов: ls ~/claude-memory/conversations/index.json

• Проверьте права доступа к файлам

• Запустите проверку: python3 tests/validate_system.py

Ошибки часового пояса в еженедельной сводке:

• Убедитесь, что все объекты datetime используют согласованную обработку часовых поясов

• Недавнее исправление устраняет сравнение объектов с учетом часового пояса и без него

Системные требования

• Python: 3.11+ (протестировано на 3.11.12)

• Место на диске: ~10 МБ на 100 диалогов

• Память: <100 МБ ОЗУ

• ОС: Рекомендуется Ubuntu/WSL, совместимо с macOS/Windows

Участие в разработке

1. Сделайте форк репозитория

2. Создайте ветку для функции: git checkout -b feature-name

3. Зафиксируйте изменения: git commit -am 'Add feature'

4. Отправьте в ветку: git push origin feature-name

5. Отправьте Pull Request

Лицензия

Лицензия MIT — подробности см. в файле LICENSE

Благодарности

• Создано с помощью Model Context Protocol (MCP)

• Разработано для интеграции с Claude Desktop

• Вдохновлено потребностью в постоянном контексте диалога

Статус: Готово к использованию ✅
Последнее обновление: Апрель 2026 г.
Версия: 2.0.0

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers