Selti — MCP Memory Server

Selti — это сервер постоянной памяти для AI-агентов, работающих через протокол MCP (Model Context Protocol). Сервер хранит диалоги, документы (база знаний), состояния агентов и универсальные записи, обеспечивая семантический поиск по ним.

---

Основные возможности

• Семантическая память — сохранение и поиск записей по смыслу через векторные эмбеддинги
• Управление диалогами — создание, просмотр и архивация бесед с историей сообщений
• База знаний — хранение документов с семантическим поиском
• Состояния агентов — сохранение конфигурации и состояния MCP-агентов
• MCP-протокол — полная поддержка tools, resources и prompts спецификации MCP
• Мониторинг — Prometheus-метрики, health/readiness probes, структурированное логирование

---

Стек технологий

Компонент	Технология
Язык	Python 3.12+
Веб-фреймворк	Flask 3
ORM	SQLAlchemy 2.0
База данных	PostgreSQL 16 + pgvector
Миграции	Alembic
Эмбеддинги	OpenAI-совместимый API (Qwen3-Embedding-8B)
Протокол	MCP (JSON-RPC 2.0)
Метрики	Prometheus + prometheus-flask-exporter
Деплой	Docker, Gunicorn

---

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

1. Клонирование

git clone https://github.com/Dek1m/selti.git
cd selti

2. Настройка окружения

cp .env.example .env
# Отредактируйте .env под своё окружение

3. Запуск через Docker Compose

docker compose up -d

Сервер будет доступен на http://localhost:8081.

4. Запуск вручную (для разработки)

# Установка зависимостей
pip install -e ".[dev]"

# Запуск сервера
python -m mcp_server.app

---

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

Все настройки задаются через переменные окружения или файл .env:

Переменная	По умолчанию	Описание
DATABASE_URL	postgresql://...	URL подключения к PostgreSQL с pgvector
EMBEDDING_API_URL	http://localhost:8080/v1/embeddings	URL эндпоинта эмбеддингов
EMBEDDING_MODEL	Qwen3-Embedding-8B-Q4_K_M.gguf	Модель эмбеддингов
EMBEDDING_DIMENSIONS	4096	Размерность векторов
FLASK_HOST	0.0.0.0	Хост для Flask
FLASK_PORT	8081	Порт для Flask
FLASK_DEBUG	false	Режим отладки
LOG_LEVEL	INFO	Уровень логирования
LOG_FORMAT	plain	Формат логов (plain или json)

---

Модели данных

Таблица	Назначение	Ключевые поля
memories	Универсальные записи	key, content, embedding (vector), scope
conversations	Диалоги	title, extra (JSONB)
messages	Сообщения	role, content, embedding (vector)
documents	Документы БЗ	title, content, embedding (vector), source
agents	Состояния агентов	name, config (JSONB), state (JSONB)

Размерность эмбеддингов — 4096 (превышает лимит pgvector для индексов в 2000), поэтому поиск выполняется точным перебором (brute-force) через оператор косинусного расстояния <=>.

---

MCP-протокол

Tools (инструменты)

Метод	Описание
memory.store	Сохранить запись (авто-эмбеддинг)
memory.search	Семантический поиск, top-K
memory.get	Получить запись по ID
memory.delete	Удалить запись
memory.list	Список записей с фильтрами
conversation.list	Список диалогов
conversation.get	Получить диалог с сообщениями
conversation.archive	Архивировать диалог

Resources (ресурсы)

• memory://{id} — запись памяти
• conversation://{id} — диалог
• document://{id} — документ

Prompts (промпты)

• memory-retrieve — поиск + форматирование результатов
• memory-summarize — суммаризация записи
• context-build — сборка контекста из диалога и семантических находок

---

API endpoints

Endpoint	Метод	Описание
/health	GET	Liveness probe (БД + pgvector)
/ready	GET	Readiness probe (БД + pgvector + embedding-сервис)
/metrics	GET	Prometheus-метрики
/mcp	POST	Единая точка входа MCP (JSON-RPC 2.0)

---

Мониторинг

Prometheus-метрики (/metrics)

• mcp_requests_total{method} — количество вызовов каждого MCP-метода
• mcp_request_duration_seconds{method} — гистограмма времени выполнения
• memory_store_total — количество сохранённых записей
• memory_search_total — количество поисковых запросов
• embedding_api_duration_seconds — время ответа embedding-сервиса
• db_pool_connections{state} — соединения в пуле БД

Логирование

• Структурированные JSON-логи при LOG_FORMAT=json
• Логирование каждого MCP-запроса (метод, параметры, длительность, статус)
• Логи SQL-запросов при LOG_LEVEL=DEBUG

---

Разработка

Запуск тестов

pytest tests/ -v

Миграции БД

alembic upgrade head
alembic revision --autogenerate -m "description"

Форматирование кода

ruff check mcp_server/

---

Лицензия

MIT