selti — Semantic Memory MCP Server

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

Примечание: Данный проект разработан с применением технологий искусственного интеллекта в рамках рабочего процесса Argenta Team. Код прошел рецензирование, тестирование и подготовлен к эксплуатации в production-среде.

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

Related MCP server: elephantasm-mcp

Архитектура

Система построена по многослойной архитектуре с чётким разделением ответственности:

Client (MCP over SSE)
       |
       v
   FastAPI / FastMCP ─── Auth Middleware (опционально)
       |
       v
   ┌─────────────────────────────────────────┐
   │            MCP Tools (16)               │
   │  store / search / get / update / delete │
   │  list / forget / ingest / stats / find  │
   │  recent / archive / link / unlink       │
   │  get_relations / traverse / graph_stats │
   └──────────────────────┬──────────────────┘
                          │
                          v
   ┌─────────────────────────────────────────┐
   │           MemoryService                 │
   │        (бизнес-логика)                  │
   └──────┬──────────────────────┬───────────┘
          │                      │
          v                      v
   ┌───────────┐        ┌───────────────┐
   │ DedupEngine│◄──────►│ Embedding API │
   │exact+sem. │        │  + Redis Cache│
   └─────┬─────┘        └───────┬───────┘
         │                      │
         v                      v
   ┌─────────────────────────────────────────┐
   │          MemoryRepository               │
   │       (SQL via asyncpg)                 │
   └──────────────────┬──────────────────────┘
                      │
                      v
   ┌─────────────────────────────────────────┐
   │    PostgreSQL 17 + pgvector (HNSW)      │
   │        4096-мерные эмбеддинги           │
   │        + Relations table (граф)         │
   └─────────────────────────────────────────┘

Слои архитектуры:

• MCP Tools — 16 инструментов, декорированных FastMCP. Валидация namespace, трекинг метрик, обработка ошибок. Включают инструменты для графа знаний (link, unlink, get_relations, traverse, graph_stats).

• DedupEngine — двухуровневая дедупликация: точная (SHA256) и семантическая (cosine distance). Оптимизирован: кеширует эмбеддинги в DedupDecision.

• MemoryService — координатор бизнес-логики: вызов эмбеддингов, дедупликация, взаимодействие с репозиторием. Поддерживает batch-операции и Relations API.

• Repository — уровень доступа к данным на asyncpg; сырые SQL-запросы с параметризацией. Включает методы для графа (add_relation, traverse, get_graph_stats) и archive.

• PostgreSQL / pgvector — HNSW-индекс для 4096-мерных векторов, B-tree индексы для фильтрации, JSONB для метаданных. Таблица relations для графа знаний.

• Redis Cache — кеш эмбеддингов (SHA256-ключи, TTL 24 часа); снижает нагрузку на Embedding API.

MCP Tools

Сервер предоставляет 16 инструментов для управления семантической памятью:

Основные инструменты

Инструменты для графа знаний

Каждый инструмент инструментирован метриками: количество вызовов, длительность выполнения, статус (ok/error).

Namespace-стратегия

Namespace обеспечивают логическую изоляцию данных в рамках одной базы. Передаются опционально (по умолчанию — default). Валидация на уровне tools; неверное значение вызывает ValueError.

Дедупликация

Ядро системы — DedupEngine, реализующий двухуровневую стратегию предотвращения дубликатов.

Уровень 1: Exact Match

Вычисляется SHA256(content). Выполняется поиск по content_hash в пределах namespace:

• user_facts → UPDATE (перезапись существующей записи)

• остальные → SKIP (пропуск, возврат существующей записи)

Уровень 2: Semantic Match

Если точное совпадение не найдено, генерируется эмбеддинг и выполняется векторный поиск. При score >= threshold запись считается дубликатом → SKIP.

Пороги семантической дедупликации (per-namespace)

Пороги настраиваются через переменную DEDUP_THRESHOLDS. Полное отключение — DEDUP_ENABLED=false.

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

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

• Docker 24+ и Docker Compose v2

• Python 3.12 (для миграций вне контейнера)

Запуск

# 1. Клонировать репозиторий
git clone <repository-url>
cd selti

# 2. Скопировать шаблон окружения
cp .env.example .env

# 3. Сгенерировать пароли
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# 4. Заполнить .env:
#    PG_PASSWORD     — пароль суперпользователя PostgreSQL
#    APP_PASSWORD    — пароль пользователя приложения athena_app
#    REDIS_PASSWORD  — пароль Redis

# 5. Запустить с локальными PostgreSQL и Redis
docker compose --profile local-db up -d

# 6. Проверить здоровье сервера
curl http://localhost:8000/health

# 7. Применить миграции базы данных
python migrations/run.py

Для подключения к внешним PostgreSQL и Redis — запустите без профиля --profile local-db и укажите соответствующие URL в .env.

Celery Setup

Система использует Celery для асинхронной обработки тяжёлых операций: векторного поиска, batch-вставок, дедупликации и работы с эмбеддингами. MCP-сервер только ставит задачи в очередь, а воркеры выполняют всю работу.

Архитектура

MCP Server (FastMCP) ──send_task()──▶ Redis (broker) ──▶ Celery Worker (prefork)
                                                                    │
                                    ┌───────────────────────────────┤
                                    │               │               │
                                    ▼               ▼               ▼
                              PostgreSQL        Qdrant        Embedding API
                              (pgvector)       (векторы)      (эмбеддинги)

Почему Celery, а не asyncio в MCP-сервере: вся логика selti — async (asyncpg, httpx), но тяжёлые операции (embedding, векторный поиск) блокируют event loop. Celery prefork воркеры изолируют эти операции в отдельных процессах, не блокируя обработку MCP-запросов.

Очереди

Запуск

# Development — всё вместе
docker compose up -d

# С Flower (мониторинг воркеров)
docker compose --profile dev up -d

# Только воркер (вручную, для отладки)
celery -A memory_server.celery_app worker \
    -Q memory,batch,hash \
    -c 4 \
    --without-gossip \
    --without-mingle \
    --without-heartbeat \
    -l INFO

# Только Flower
celery -A memory_server.celery_app flower --port=5555

Production-опции воркера

celery -A memory_server.celery_app worker \
    -Q memory,batch,hash \
    -c 4 \
    --without-gossip \
    --without-mingle \
    --without-heartbeat \
    --max-tasks-per-child=1000 \
    --max-memory-per-child=200000 \
    --logfile=- \
    -l INFO

Retry-политика

Задачи автоматически повторяются при ошибках сети или БД:

• Максимум попыток: 5

• Стратегия: exponential backoff + jitter

• Базовая задержка: 30 секунд

Validation-ошибки (ValueError, InvalidNamespace) не ретраятся — это баги данных, а не транзиентные сбои.

Мониторинг

Troubleshooting

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

Переменные окружения

PostgreSQL (локальный профиль)

Для локального запуска используется образ pgvector/pgvector:pg17 с предварительно настроенным HNSW-индексом:

• Расширение vector

• Таблица memories с колонкой embedding vector(8192)

• HNSW-индекс с параметрами m = 16, ef_construction = 200

• B-tree индексы: user_id, namespace, created_at DESC

• Триггер автообновления updated_at

• Уникальный индекс на (namespace, content_hash) для точной дедупликации

Аутентификация

Опциональная защита на основе API-ключа. Включается установкой переменной API_KEY в .env.

Механизм:

• HTTP-middleware проверяет заголовок Authorization: Bearer <API_KEY> для всех эндпоинтов

• ASGI-middleware защищает /mcp (mount-приложение FastMCP)

• Белый список (доступ без аутентификации): /health, /metrics

При пустом значении API_KEY доступ открыт.

Мониторинг

Метрики Prometheus

Эндпоинт /metrics предоставляет 13+ метрик:

Healthcheck

curl http://localhost:8000/health

Ответ содержит версию сервера и статусы проверок конфигурации.

Grafana Dashboard

Готовый dashboard для PostgreSQL + pgvector — monitoring/dashboards/postgres-pgvector.json.

Экспортёры

Для production-развёртывания предусмотрены экспортёры (включаются через -f monitoring/exporters/docker-compose.exporters.yml):

• postgres-exporter (порт 9187) — метрики PostgreSQL

• redis-exporter (порт 9121) — метрики Redis

Алерты

Правила алертинга — monitoring/alerts/prometheus-rules.yml:

• Доступность PostgreSQL и Redis

• Высокая загрузка соединений

• Конфликты запросов на реплике

• Долгие запросы (> 5 минут)

• Отставание WAL-архивации

• Отсутствие бэкапов

• Отсутствие HNSW-индекса при > 10k записей

• Высокое потребление памяти Redis

• Высокий процент промахов кеша Redis

Миграции

Управление схемой базы данных — через встроенный migration runner.

# Применить все неприменённые миграции
python migrations/run.py

# Откатить последнюю миграцию
python migrations/run.py --down

Миграции находятся в migrations/ — версионированные SQL-файлы с up/down-секциями. Система отслеживает применённые миграции в таблице _migrations.

Доступные миграции:

Zero-downtime Deploy

Скрипт deploy.sh реализует стратегию rolling-обновления:

1. Пулл нового образа из GHCR

2. Запуск нового контейнера на временном порту

3. Ожидание прохождения healthcheck

4. Переключение трафика (через reverse proxy или прямой restart)

5. Остановка и удаление старого контейнера

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

Проект покрыт модульными и интеграционными тестами (142+ теста).

# Установка зависимостей для тестов
pip install -r requirements.txt

# Запуск тестов
pytest tests/ -v

# С отчётом о покрытии
pytest tests/ --cov=memory_server -v

Разработка

Проект разработан в рамках Argenta Team — архитектура, разработка и сопровождение информационных систем.

Разработчик: Dek1m

Argenta Team — архитектура, разработка и сопровождение информационных систем.

Auto-deploy test: 2026-08-01T08:54:55Z