MemoryHub
by kameton-dev
README.md
# MemoryHub
MemoryHub — MCP-сервер для долговременной памяти ИИ-ассистентов. Он предоставляет инструменты для проектов и заметок, хранит данные в SQLite и принимает запросы по MCP Streamable HTTP.
## Возможности
- Bearer-аутентификация по API-токенам.
- SHA-256 хеши токенов хранятся в SQLite; исходный токен показывается только при создании.
- Scopes: `memory:read`, `memory:write` и `memory:admin`.
- Проекты, поиск и получение записей памяти, обновление и архивирование.
- Защита MCP транспорта от DNS rebinding.
- Uvicorn за Nginx; пример systemd unit и фрагмент Nginx находятся в `deploy/`.
## MCP-инструменты
| Инструмент | Scope | Назначение |
| --- | --- | --- |
| `server_status` | `memory:read` | Проверить доступность MemoryHub |
| `project_create` | `memory:write` | Создать проект |
| `project_list` | `memory:read` | Получить список проектов |
| `memory_save` | `memory:write` | Сохранить запись |
| `memory_search` | `memory:read` | Найти записи по тексту, проекту и категории |
| `memory_get` | `memory:read` | Получить запись по ID |
| `memory_update` | `memory:write` | Обновить запись |
| `memory_delete` | `memory:write` | Архивировать запись без физического удаления |
`memory:admin` разрешает операции чтения и записи. Поиск по категориям использует `instructions`, `technical`, `preferences`, `decisions`, `context` и `notes`.
## Конфигурация
Настройки задаются переменными окружения. Для systemd их читает файл `/etc/memoryhub/memoryhub.env`; шаблон находится в [.env.example](.env.example).
| Переменная | Значение по умолчанию | Назначение |
| --- | --- | --- |
| `MEMORYHUB_DATABASE_URL` | `sqlite:////var/lib/memoryhub/memory.db` | SQLAlchemy URL базы данных |
| `MEMORYHUB_HOST` | `127.0.0.1` | Адрес, на котором слушает Uvicorn |
| `MEMORYHUB_PORT` | `8765` | Порт Uvicorn |
| `MEMORYHUB_ALLOWED_HOSTS` | локальные адреса | Список разрешённых значений `Host`, через запятую |
| `MEMORYHUB_ALLOWED_ORIGINS` | локальные origins | Список разрешённых `Origin`, через запятую |
## Развёртывание на Debian/Ubuntu
Пример использует `/opt/memoryhub` для приложения, `/var/lib/memoryhub` для данных и `/etc/memoryhub/memoryhub.env` для конфигурации.
1. Создайте пользователя и каталоги:
```bash
sudo useradd --system --home /opt/memoryhub --shell /usr/sbin/nologin memoryhub
sudo install -d -o memoryhub -g memoryhub -m 0750 /opt/memoryhub
sudo install -d -o memoryhub -g memoryhub -m 0750 /var/lib/memoryhub
sudo install -d -o root -g memoryhub -m 0750 /etc/memoryhub
```
2. Поместите код репозитория в `/opt/memoryhub`, создайте venv и установите зависимости:
```bash
cd /opt/memoryhub
sudo -u memoryhub python3 -m venv venv
sudo -u memoryhub venv/bin/pip install -r requirements.txt
```
3. Создайте системный env-файл и укажите ваш публичный MCP-домен в `MEMORYHUB_ALLOWED_HOSTS` и `MEMORYHUB_ALLOWED_ORIGINS`:
```bash
sudo install -o root -g memoryhub -m 0640 .env.example /etc/memoryhub/memoryhub.env
sudoedit /etc/memoryhub/memoryhub.env
```
Например, для `https://mcp.example.com/mcp` укажите `mcp.example.com,mcp.example.com:*` в `MEMORYHUB_ALLOWED_HOSTS` и `https://mcp.example.com` в `MEMORYHUB_ALLOWED_ORIGINS`. При изменении пути к SQLite обновите `MEMORYHUB_DATABASE_URL`; каталог базы должен быть доступен пользователю `memoryhub`.
4. Установите systemd unit. Он загружает настройки из `/etc/memoryhub/memoryhub.env`:
```bash
sudo install -o root -g root -m 0644 deploy/systemd/memoryhub.service /etc/systemd/system/memoryhub.service
sudo systemctl daemon-reload
sudo systemctl enable --now memoryhub
sudo systemctl status memoryhub --no-pager
```
При старте приложение создаёт отсутствующие таблицы через SQLAlchemy `create_all`; существующая база не удаляется и не пересоздаётся.
5. Настройте HTTPS reverse proxy в существующем виртуальном хосте. Фрагмент для `/mcp` приведён в [deploy/nginx/memoryhub-location.conf](deploy/nginx/memoryhub-location.conf). Добавьте его в нужный `server` block, сохранив остальные сайты и маршруты, затем проверьте и перечитайте Nginx:
```bash
sudo nginx -t
sudo systemctl reload nginx
```
Прокси должен передавать `Host` и `Authorization`, не буферизовать SSE и допускать длительные ответы.
## API-токены
Создайте отдельный токен для каждого клиента с нужными scopes. Команда печатает токен один раз — сохраните его в менеджере секретов и не отправляйте в логи или Git:
```bash
sudo -u memoryhub env MEMORYHUB_DATABASE_URL='sqlite:////var/lib/memoryhub/memory.db' \
/opt/memoryhub/venv/bin/python /opt/memoryhub/token_manager.py create \
--name claude-ai --scopes memory:read memory:write
```
Просмотр имён, scopes и статусов не раскрывает токены:
```bash
sudo -u memoryhub env MEMORYHUB_DATABASE_URL='sqlite:////var/lib/memoryhub/memory.db' \
/opt/memoryhub/venv/bin/python /opt/memoryhub/token_manager.py list
```
Отзыв токена:
```bash
sudo -u memoryhub env MEMORYHUB_DATABASE_URL='sqlite:////var/lib/memoryhub/memory.db' \
/opt/memoryhub/venv/bin/python /opt/memoryhub/token_manager.py revoke --id 1
```
Если в env-файле задан другой `MEMORYHUB_DATABASE_URL`, укажите то же значение в команде управления токенами.
## Подключение MCP-клиента
Используйте публичный HTTPS адрес MCP endpoint, например `https://mcp.example.com/mcp`. Для Claude Custom Connector выберите **No sign-in** и добавьте обязательный request header:
- Name: `authorization`
- Value: `Bearer <созданный API-токен>`
Проверьте сервис и журнал после подключения:
```bash
sudo systemctl status memoryhub --no-pager
sudo journalctl -u memoryhub -n 100 --no-pager
```
Чтобы вручную проверить публичный `initialize`, задайте токен в переменной оболочки и отправьте JSON-RPC запрос. Не вставляйте настоящий токен непосредственно в сохраняемую команду:
```bash
read -rsp 'MemoryHub token: ' MEMORYHUB_TOKEN; echo
curl -i https://mcp.example.com/mcp \
-H "Authorization: Bearer $MEMORYHUB_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"manual-check","version":"1.0"}}}'
unset MEMORYHUB_TOKEN
```
Успешный ответ — `HTTP 200`, JSON-RPC `result` и, для stateful Streamable HTTP, заголовок `Mcp-Session-Id`.
## Локальный запуск
Установите Python 3.11+ и зависимости. Перед запуском задайте `MEMORYHUB_DATABASE_URL` на локальный файл SQLite и добавьте loopback значения в `MEMORYHUB_ALLOWED_HOSTS` и `MEMORYHUB_ALLOWED_ORIGINS`. Для нового окружения приложение создаёт таблицы при прямом запуске:
```bash
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
export MEMORYHUB_DATABASE_URL='sqlite:///./memoryhub.db'
export MEMORYHUB_HOST='127.0.0.1'
export MEMORYHUB_PORT='8765'
export MEMORYHUB_ALLOWED_HOSTS='127.0.0.1,127.0.0.1:*,localhost,localhost:*'
export MEMORYHUB_ALLOWED_ORIGINS='http://127.0.0.1:8765,http://localhost:8765'
python main.py
```
## Лицензия
Этот проект распространяется под лицензией [**GNU Affero General Public License v3.0**](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues