🧠 MCP Memory Server

MCP сервер для управления долговременной памятью (Knowledge Graph) и поиска в интернете. Поддерживает SQLite (встроенное хранилище) и PostgreSQL (удалённая БД).

⚡ Используйте MCP инструменты прямо из VS Code: сохраняйте заметки, стройте граф знаний, ищите в интернете — всё без выхода из редактора.

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

🧠 Knowledge Graph (Граф знаний)

Сохранение сущностей — люди, концепции, заметки, проекты, статьи
Связи между сущностями — граф отношений (A --[related_to]--> B)
Полнотекстовый поиск — по имени, свойствам, тегам (FTS5 / PostgreSQL tsvector)
Семантический поиск — векторные эмбеддинги через sentence-transformers
Пространства имён — изолированные области знаний (проекты, темы)
Теги и категории — гибкая классификация
Экспорт графа — JSON/Markdown дамп всей базы знаний
TTL для сущностей — автоматическое "забывание" устаревших данных

🌐 Web Browser (Поиск в интернете)

Поиск через DuckDuckGo — без API-ключа, бесплатно
Скрейпинг страниц — извлечение основного контента по URL
Сохранение страниц как знаний — с эмбеддингами для поиска
Кэширование в Redis — повторные запросы без задержек

💬 Dialogue Memory (Память диалогов)

Хранение истории — каждая сессия диалога сохраняется
Извлечение контекста — восстановление предыдущих разговоров
Очистка сессии — управление памятью

⚙️ Системное

Health Check — мониторинг БД, Redis, эмбеддингов
Статистика — количество сущностей, связей, размер БД
Резервное копирование — SQLite backup / PostgreSQL dump

🖥️ Web UI

Dashboard — статистика, графики, граф знаний (D3.js)
Entity Browser — поиск и просмотр сущностей
Timeline — временная шкала изменений
Graph Visualization — force-directed граф с зумом

🏗️ Архитектура

┌─────────────────────────────────────────────────────────┐
│                   MCP Client (Claude)                    │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP Protocol (stdio / SSE)
┌──────────────────────▼──────────────────────────────────┐
│                    server.py (FastMCP)                    │
│  ┌────────────┐  ┌────────────┐  ┌───────────────────┐  │
│  │ Knowledge   │  │  Browser    │  │  Dialogue Memory │  │
│  │ Graph Tools │  │  Tools      │  │  Tools           │  │
│  └──────┬──────┘  └──────┬─────┘  └───────┬───────────┘  │
│         │                │                 │              │
│  ┌──────▼────────────────▼─────────────────▼──────────┐  │
│  │              KnowledgeGraph (core logic)            │  │
│  └──────┬──────────────────────┬──────────────────────┘  │
│         │                      │                         │
│  ┌──────▼──────┐       ┌──────▼──────┐                  │
│  │  SQLite3 /  │       │    Redis    │                  │
│  │ PostgreSQL  │       │   (cache)   │                  │
│  └─────────────┘       └─────────────┘                  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │         EmbeddingsEngine (sentence-transformers)  │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Технологии

Компонент	Технология	Назначение
MCP Server	`mcp[cli]` (FastMCP)	Протокол взаимодействия
Хранилище	SQLite3 / PostgreSQL (asyncpg)	Персистентность данных
Кэш	Redis (async)	Кэш запросов, сессии, TTL
Эмбеддинги	`sentence-transformers` / `fastembed`	Семантический поиск
Поиск	`duckduckgo-search`	Бесплатный веб-поиск
Скрейпинг	`httpx` + `beautifulsoup4`	Извлечение контента
Web UI	Starlette + D3.js	Визуализация графа

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

Установка

# Клонировать репозиторий
cd mcp-server

# Установить зависимости (рекомендуется использовать uv)
uv sync

# Или через pip
pip install -e .

Настройка

cp .env.example .env
# Отредактировать .env при необходимости

Запуск сервера (локальная сеть)

Сервер работает по SSE (Server-Sent Events) и доступен в локальной сети.

Через Python (SQLite)

# Установить зависимости
pip install -e .

# Запустить MCP сервер (SSE транспорт, порт 8000)
python -m server

Сервер будет доступен по адресу: http://127.0.0.1:8000/sse

Через Python (PostgreSQL)

# Настроить .env
DB_TYPE=postgres
PG_HOST=your-postgres-host
PG_USER=postgres
PG_PASSWORD=your-password
PG_DATABASE=mcp_memory

# Запустить
python -m server

Через Docker Compose (SQLite + Redis)

docker compose up -d

# Сервер: http://SERVER_IP:8000/sse
# Redis: порт 6379

Через Docker Compose (PostgreSQL + Redis — production)

cp .env.example .env
# Отредактировать PG_PASSWORD и EMBEDDINGS_MODE

docker compose -f docker-compose.remote.yml up -d

# PostgreSQL: порт 5432 (только localhost)
# Redis: порт 6379 (только localhost)
# Сервер: http://SERVER_IP:8000/sse

Вариант 1: Автоматически (конфигурация в проекте)

В файле .vscode/mcp.json уже прописано подключение по URL:

{
    "servers": {
        "memory-server": {
            "type": "url",
            "url": "http://localhost:8000/sse"
        }
    }
}

Замените localhost на IP-адрес сервера в локальной сети, если VS Code запущен на другом компьютере.

Вариант 2: Через settings.json пользователя

Добавьте в глобальный settings.json VS Code (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"):

{
    "mcp": {
        "servers": {
            "memory-server": {
                "type": "url",
                "url": "http://192.168.1.100:8000/sse"
            }
        }
    }
}

Замените IP на фактический адрес сервера.

Вариант 3: Локальный запуск сервера на том же компьютере

Если VS Code запущен на том же компьютере, что и сервер:

{
    "mcp": {
        "servers": {
            "memory-server": {
                "type": "url",
                "url": "http://localhost:8000/sse"
            }
        }
    }
}

Проверка подключения

Убедитесь, что сервер запущен (команда python -m server или docker-compose up -d)
Откройте VS Code
Если настроено через .vscode/mcp.json — откройте папку проекта
Используйте Ctrl+Shift+P → "MCP: List Tools" чтобы увидеть все доступные инструменты
При успешном подключении вы увидите список из 18 инструментов

Подключение из Kilo Code

Kilo Code поддерживает MCP серверы по протоколу SSE. Добавьте в kilo.json (глобальный ~/.config/kilo/kilo.json или проектный ./kilo.json):

Без авторизации

{
  "mcp": {
    "memory-server": {
      "type": "remote",
      "url": "http://192.168.1.100:8000/sse",
      "enabled": true
    }
  }
}

С авторизацией (SSE_API_KEY)

{
  "mcp": {
    "memory-server": {
      "type": "remote",
      "url": "http://192.168.1.100:8000/sse",
      "headers": {
        "Authorization": "Bearer your-secret-api-key"
      },
      "enabled": true
    }
  }
}

Замените IP и ключ на фактические значения сервера.

Подключение из Roo Code

Roo Code также поддерживает SSE MCP серверы. Добавьте в mcp_settings.json (или в настройках расширения → MCP → Edit Settings):

{
  "mcpServers": {
    "memory-server": {
      "type": "sse",
      "url": "http://192.168.1.100:8000/sse",
      "headers": {
        "Authorization": "Bearer your-secret-api-key"
      }
    }
  }
}

Если авторизация не включена — поле headers можно опустить.

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

Knowledge Graph

Инструмент	Описание	Параметры
`store_entity`	Сохранить сущность	`name`, `entity_type`, `properties`(JSON), `namespace`, `tags`, `ttl_seconds`
`get_entity`	Получить сущность	`entity_id` или `name` + `namespace`
`search_knowledge`	Поиск по базе знаний	`query`, `namespace`, `entity_type`, `tags`, `use_semantic`, `limit`
`list_entities`	Список сущностей	`namespace`, `entity_type`, `limit`, `offset`
`delete_entity`	Удалить сущность	`entity_id`
`add_relation`	Создать связь	`source_id`, `target_id`, `relation_type`, `properties`
`get_relations`	Связи сущности	`entity_id`, `relation_type`
`export_graph`	Экспорт графа	`namespace`

Browser

Инструмент	Описание	Параметры
`web_search`	Поиск в интернете	`query`, `max_results`
`scrape_page`	Извлечь текст страницы	`url`
`save_webpage_to_knowledge`	Сохранить страницу как знание	`url`, `namespace`, `tags`

Dialogue Memory

Инструмент	Описание	Параметры
`store_dialogue`	Сохранить реплику	`session_id`, `role`, `content`, `namespace`
`get_dialogue_history`	История сессии	`session_id`, `limit`
`clear_dialogue_history`	Очистить историю	`session_id`

System

Инструмент	Описание	Параметры
`health_check`	Проверка сервисов	—
`get_stats`	Статистика	`namespace`
`list_namespaces`	Список пространств	—

📝 Примеры использования

Сохранение знаний

🔧 store_entity(
    name="Python asyncio",
    entity_type="concept",
    properties='{"category": "programming", "difficulty": "intermediate"}',
    tags="python,async,programming"
)

Поиск с семантикой

🔍 search_knowledge(
    query="асинхронное программирование",
    use_semantic=true,
    limit=5
)

Связывание сущностей

🔗 add_relation(
    source_id="<entity_id_1>",
    target_id="<entity_id_2>",
    relation_type="depends_on"
)

Поиск в интернете и сохранение

🌐 web_search(query="последние новости AI", max_results=5)

📄 scrape_page(url="https://example.com/article")

💾 save_webpage_to_knowledge(
    url="https://example.com/article",
    tags="AI,research"
)

🐳 Docker

Локальная разработка (SQLite + Redis)

docker compose up -d

Production (PostgreSQL + Redis)

# Полный стек (PostgreSQL, Redis, MCP Server)
docker compose -f docker-compose.remote.yml up -d

# Или с внешней PostgreSQL (без локального контейнера PG)
docker compose -f docker-compose.remote.yml --profile external-db up -d

Сборка образа вручную

docker build -t mcp-memory-server .

# Запуск с пробросом .env
docker run -it --rm --env-file .env -v mcp-data:/app/data mcp-memory-server

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

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

# Запустить тесты
pytest -v

# С覆盖率
pytest --cov=. --cov-report=term-missing

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

Переменная	По умолчанию	Описание
`DB_TYPE`	`sqlite`	Тип БД: `sqlite` или `postgres`
`SQLITE_DB_PATH`	`data/memory.db`	Путь к SQLite (при `DB_TYPE=sqlite`)
`PG_HOST`	`localhost`	Хост PostgreSQL (при `DB_TYPE=postgres`)
`PG_PORT`	`5432`	Порт PostgreSQL
`PG_USER`	`postgres`	Пользователь PostgreSQL
`PG_PASSWORD`	—	Пароль PostgreSQL
`PG_DATABASE`	`mcp_memory`	Имя БД PostgreSQL
`PG_POOL_SIZE`	`10`	Размер пула соединений asyncpg
`REDIS_HOST`	`localhost`	Хост Redis
`REDIS_PORT`	`6379`	Порт Redis
`REDIS_DB`	`0`	Номер БД Redis
`REDIS_PASSWORD`	—	Пароль Redis
`MCP_HOST`	`127.0.0.1`	Интерфейс для SSE сервера
`MCP_PORT`	`8010`	Порт для SSE сервера
`MCP_TRANSPORT`	`sse`	Транспорт: `sse` (сеть) или `stdio` (локально)
`EMBEDDINGS_MODE`	`local`	Режим эмбеддингов: `none`, `local` или `fastembed`
`EMBEDDINGS_MODEL_NAME`	`all-MiniLM-L6-v2`	Модель эмбеддингов
`DEFAULT_NAMESPACE`	`default`	Пространство имён по умолчанию
`ENTITY_TTL_SECONDS`	`0`	TTL для сущностей (0 = без TTL)
`SSE_AUTH_ENABLED`	`false`	Включить Bearer token аутентификацию для SSE
`SSE_API_KEY`	—	API-ключ для SSE эндпоинтов

🤝 Предлагаемые улучшения

Авторизация — Bearer token аутентификация для SSE-эндпоинтов (SSE_AUTH_ENABLED + SSE_API_KEY)
Мониторинг URL — периодическая проверка страниц на изменения
OpenTelemetry — метрики и трейсинг
Партиционирование — шардирование PostgreSQL по namespace
Бэкап PostgreSQL — автоматический pg_dump по расписанию

📋 Changelog

v0.2.0 — PostgreSQL, async, Web UI

PostgreSQL: новый async-клиент (storage/postgres_client.py) на asyncpg:
- Пул соединений, JSONB, GIN-индексы, FTS через tsvector
- 16 индексов: GIN на JSONB/TEXT[]/tsvector, композитные, покрывающие
- Каскадные внешние ключи (ON DELETE CASCADE)
- Переключение между SQLite/PostgreSQL через DB_TYPE в .env
Async dispatch: KnowledgeGraph автоматически определяет sync/async хранилище
Web UI: Dashboard с D3.js графом, Entity Browser, Timeline, Stats
Favicon: иконка сервера (mcp.png) на всех страницах Web UI
Docker Compose: docker-compose.remote.yml для production-развёртывания
Тесты: 176/176, 0 warnings

v0.1.1 (предыдущий релиз)

Исправлен критический баг: __version__ теперь определён в server.py, сервер не падает при запуске
Исправлены импорты: относительные импорты (from ..storage) заменены на абсолютные (from storage)
Починены тесты: 73% тестов (143 из 197) теперь выполняются (раньше падали с ImportError)
Оптимизация производительности:
- N+1 запросы в GraphVisualizer заменены на batch-запрос get_relations_for_entities
- list_namespaces() теперь использует SELECT DISTINCT вместо загрузки всех сущностей
- export_graph() использует batch-запрос вместо цикла
Безопасность:
- Добавлен html.escape() для всех пользовательских данных в Web UI (XSS)
- Добавлена защита path traversal в MarkdownImporter
- MCP_HOST по умолчанию изменён на 127.0.0.1
Улучшения кода:
- Убран мёртвый вызов search_knowledge() в url_monitor.py
- _parse_json() теперь принимает str | None
- cosine_similarity() — @staticmethod
- Суждены блоки except Exception до конкретных исключений
- Убраны поздние импорты в server.py
- Добавлен fastembed в optional-dependencies
- Устранён дубликат тестового класса TestSearchEngineWithMockRedis
- Модельные тесты вынесены в test_models.py

📄 Лицензия

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.github/workflows		.github/workflows
browser		browser
knowledge		knowledge
scripts		scripts
storage		storage
tests		tests
webui		webui
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
DEPLOY_DEBIAN.md		DEPLOY_DEBIAN.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SYSTEM_REQUIREMENTS.md		SYSTEM_REQUIREMENTS.md
docker-compose.remote.yml		docker-compose.remote.yml
docker-compose.yml		docker-compose.yml
mcp.png		mcp.png
preview.html		preview.html
pyproject.toml		pyproject.toml
server.py		server.py

Folders and files

Latest commit

History

Repository files navigation

🧠 MCP Memory Server

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

🧠 Knowledge Graph (Граф знаний)

🌐 Web Browser (Поиск в интернете)

💬 Dialogue Memory (Память диалогов)

⚙️ Системное

🖥️ Web UI

🏗️ Архитектура

Технологии

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

Установка

Настройка

Запуск сервера (локальная сеть)

Через Python (SQLite)

Через Python (PostgreSQL)

Через Docker Compose (SQLite + Redis)

Через Docker Compose (PostgreSQL + Redis — production)

Вариант 1: Автоматически (конфигурация в проекте)

Вариант 2: Через settings.json пользователя

Вариант 3: Локальный запуск сервера на том же компьютере

Проверка подключения

Подключение из Kilo Code

Без авторизации

С авторизацией (SSE_API_KEY)

Подключение из Roo Code

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

Knowledge Graph

Browser

Dialogue Memory

System

📝 Примеры использования

Сохранение знаний

Поиск с семантикой

Связывание сущностей

Поиск в интернете и сохранение

🐳 Docker

Локальная разработка (SQLite + Redis)

Production (PostgreSQL + Redis)

Сборка образа вручную

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

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

🤝 Предлагаемые улучшения

📋 Changelog

v0.2.0 — PostgreSQL, async, Web UI

v0.1.1 (предыдущий релиз)

📄 Лицензия

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages