ContextKeep 🧠

Бесконечная долгосрочная память для ИИ-агентов

ContextKeep — это мощный автономный сервер памяти, который дает вашим ИИ-агентам (Claude, Cursor, Gemini, OpenCode и другим) постоянный мозг с возможностью поиска. Перестаньте повторяться — позвольте вашему ИИ запомнить всё навсегда.

Возможности • Что нового в V1.3 • Установка • Инструменты MCP • Веб-панель • Конфигурация

🌟 Возможности

• ♾️ Бесконечный контекст: Храните неограниченное количество деталей проекта, предпочтений, решений и фрагментов кода — без срока действия и ограничений по размеру.

• 💰 Экономия денег и токенов: Извлекайте только важные воспоминания, сокращая использование контекстного окна и расходы на API.

• 🔌 Универсальная совместимость: Работает с любым клиентом, поддерживающим MCP, через Stdio (локально) или SSE (удаленно/хоумлаб).

• 🧭 Протокол индексации памяти: Надежная двухэтапная система извлечения — list_all_memories() → retrieve_memory() — чтобы агенты всегда находили нужный ключ.

• 🖥️ Современная веб-панель: Визуально управляйте своими воспоминаниями с помощью представлений «Сетка», «Список» и «Календарь» в стильном темном интерфейсе.

• 🔒 Приватность прежде всего: 100% локальное хранилище. Ваши данные никогда не покидают ваш компьютер.

• 🔎 Умный поиск: Поиск по ключевым словам и семантический поиск по всему содержимому памяти.

• 🐧 Служба Linux: Работает незаметно в фоновом режиме как служба systemd.

• 🐳 Готовность к Docker: Развертывание одной командой с помощью Docker Compose.

• ⬇️ Экспорт и резервное копирование: Экспортируйте все воспоминания в формате JSON через инструмент MCP или веб-интерфейс.

🆕 Что нового в V1.3 — Harbor

🐳 Поддержка Docker

Самый популярный запрос сообщества. ContextKeep теперь поставляется с Dockerfile и docker-compose.yml для развертывания одной командой:

docker compose up --build

Это всё. MCP-сервер на :5100, веб-интерфейс на :5000, с постоянным хранилищем через тома Docker.

📦 Современная упаковка Python

• pyproject.toml — каноническая спецификация зависимостей для uv, poetry или pip

• Поддержка uv — установщик автоматически обнаруживает uv и использует uv sync для молниеносной настройки

• Обратная совместимость — pip install -r requirements.txt по-прежнему работает

🛠️ 3 новых инструмента MCP (всего 5 → 8)

⬇️ Экспорт через веб-интерфейс

• Кнопка Экспортировать всё на панели инструментов (или нажмите Ctrl+E)

• Загружает файл contextkeep_backup_YYYY-MM-DD.json с отметкой времени

🧹 Качество кода

• Исправлен «мертвый» код в memory_manager.py (недостижимый дубликат try/except)

• Добавлен отсутствующий core/__init__.py для правильной упаковки Python

• Заменены пустые except: на except Exception: по всему коду

🚀 Установка

Вариант 1: Быстрый старт (pip)

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

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep

2. Запустите установщик:

   • Linux/macOS:

python3 install.py

• Windows:

python install.py

3. Следуйте инструкциям мастера: Установщик создает виртуальное окружение, устанавливает зависимости и генерирует готовый к использованию mcp_config.json.

Вариант 2: uv (Быстро)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
uv sync
uv run python server.py

Вариант 3: Docker (Рекомендуется для хоумлабов)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
docker compose up --build -d

Это запускает:

Воспоминания сохраняются в томе Docker (contextkeep-data).

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

ContextKeep предоставляет 8 инструментов MCP любому подключенному агенту:

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

Добавьте это в ваш GEMINI.md, AGENTS.md или CLAUDE.md:

## Memory Index Protocol (MANDATORY)
1. FIRST — call `list_all_memories()` to get the complete key directory
2. THEN — call `retrieve_memory(exact_key)` using the exact key from step 1
Only use `search_memories()` for content-based searches, NOT for key lookup.

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

Скопируйте содержимое mcp_config.example.json в файл конфигурации вашего ИИ-клиента и обновите пути.

Вариант 1: Локально (Claude Desktop / Gemini CLI / Cursor)

{
  "mcpServers": {
    "context-keep": {
      "command": "/absolute/path/to/ContextKeep/venv/bin/python",
      "args": ["/absolute/path/to/ContextKeep/server.py"]
    }
  }
}

Вариант 2: Удаленно через SSH (Хоумлаб / Raspberry Pi)

Запустите ContextKeep на домашнем сервере и получайте к нему доступ с любого устройства в вашей сети:

{
  "mcpServers": {
    "context-keep": {
      "command": "ssh",
      "args": [
        "-i", "/path/to/private_key",
        "user@192.168.1.X",
        "'/path/to/ContextKeep/venv/bin/python'",
        "'/path/to/ContextKeep/server.py'"
      ]
    }
  }
}

Вариант 3: Режим SSE (HTTP)

Идеально подходит для OpenCode, веб-приложений или любого клиента, предпочитающего транспорт HTTP:

{
  "mcpServers": {
    "context-keep": {
      "transport": "sse",
      "url": "http://localhost:5100/sse"
    }
  }
}

Вариант 4: Docker

Используйте mcp_config.docker.example.json или укажите клиенту на контейнер:

{
  "mcpServers": {
    "context-keep": {
      "transport": "sse",
      "url": "http://localhost:5100/sse"
    }
  }
}

🌐 Веб-панель

ContextKeep поставляется с полнофункциональным веб-интерфейсом для управления воспоминаниями без использования CLI.

• URL: http://localhost:5000

• Сетка: Карточки воспоминаний с тегами, счетчиками символов и встроенными действиями

• Список: Плотная таблица со всеми воспоминаниями, отсортированными по дате последнего обновления

• Календарь: Просмотр истории воспоминаний по месяцам

• Поиск: Фильтрация в реальном времени по заголовкам, ключам и содержимому

• Полный CRUD: Создание, просмотр, редактирование и удаление воспоминаний из браузера

• Экспорт: Загрузка всех воспоминаний в формате JSON одним кликом (Ctrl+E)

Для ручного запуска:

./venv/bin/python webui.py

🐧 Настройка службы Linux (Рекомендуется для хоумлабов)

Запустите MCP-сервер и веб-интерфейс как постоянные фоновые службы:

chmod +x install_services.sh
./install_services.sh

Это установит:

Управление службами:

sudo systemctl status contextkeep-server
sudo systemctl restart contextkeep-webui

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

V1.3 — Harbor

• ✅ Поддержка Docker — Dockerfile + docker-compose.yml для развертывания одной командой

• ✅ Современная упаковка — pyproject.toml + поддержка uv наряду с pip

• ✅ Новый инструмент MCP: delete_memory() — агенты теперь могут удалять воспоминания

• ✅ Новый инструмент MCP: get_memory_stats() — количество и размер воспоминаний

• ✅ Новый инструмент MCP: export_memories() — полная резервная копия в JSON

• ✅ Веб-интерфейс: Кнопка «Экспортировать всё» с сочетанием клавиш Ctrl+E

• ✅ Веб-интерфейс: API-эндпоинт статистики

• ✅ Исправление: Удален «мертвый» код в memory_manager.py

• ✅ Исправление: Добавлен отсутствующий core/__init__.py для импорта Docker/пакетов

• ✅ Исправление: Пустые except заменены на except Exception

• ✅ Установщик обновлен до V1.3 с обнаружением uv

• ✅ Указаны участники сообщества 🙏

V1.2 — Obsidian Lab

• ✅ Новый инструмент MCP list_all_memories() — полный каталог памяти за один вызов

• ✅ Редизайн интерфейса Obsidian Lab — темная премиальная эстетика с акцентами цвета морской волны/неона

• ✅ Живой бейдж количества воспоминаний в заголовке

• ✅ Навигация по месяцам календаря (вперед/назад)

• ✅ Карточки в сетке теперь показывают теги и бейджи количества символов

• ✅ Удалена боковая панель «Последние воспоминания» для более чистого макета календаря

• ✅ Протокол индексации памяти V1.2 — стандартизированный двухэтапный шаблон извлечения для агентов

V1.1

• Веб-панель с представлениями «Сетка», «Список» и «Календарь»

• Поддержка транспорта SSE наряду со Stdio

• Установщик службы systemd для Linux

• Заголовки воспоминаний и метки времени

V1.0

• Базовый MCP-сервер с store_memory, retrieve_memory, search_memories

• Постоянное хранилище на базе JSON

• Поддержка удаленного транспорта SSH

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

Вклад приветствуется. Открывайте PR, создавайте issue или предлагайте функции — любой вклад ценен.

Участники сообщества V1.3

Огромное спасибо всем, кто внес вклад в релиз Harbor:

• @shuft — Открыл Issue #1 с запросом поддержки Docker

• @Cyberdogs7 — PR #2: Первоначальная реализация Docker и Docker Compose

• @frehov — PR #3: Dockerfile, pyproject.toml, поддержка uv, исправление __init__.py

• @thinkstylestudio — Продвижение в сообществе

☕ Поддержать проект

Если ContextKeep экономит ваше время, токены или нервы — подумайте о том, чтобы купить мне кофе.