Skip to main content
Glama
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)