NOUZ-MCP

# NOUZ — Семантический MCP-сервер для вашей базы знаний

> *Структура появляется из содержания.*

Работает с Obsidian, Logseq и любыми директориями Markdown-файлов.

[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![MCP SDK v2](https://img.shields.io/badge/MCP%20SDK-v2-lightgrey.svg)](https://modelcontextprotocol.io)
[![PyPI](https://img.shields.io/badge/pypi-nouz--mcp-orange.svg)](https://pypi.org/project/nouz-mcp/)

NOUZ работает на MCP Python SDK v2.

🇬🇧 [English version](README_EN.md)

---

## Зачем нужен Nouz

NOUZ выступает прослойкой между вашей базой заметок и AI-агентом. Он помогает превратить разрозненные Markdown-файлы в граф, с которым удобно работать и вам, и агенту:

1. **Автоматическая классификация (Семантика)**
   Вы задаете "Ядра" — базовые домены вашей базы. Когда вы добавляете новую заметку, NOUZ читает ее текст, сравнивает векторы и предлагает доменный знак или комбинацию доменов.

2. **Поиск связей между заметками**
   Сервер строит направленный структурный граф: `hierarchy` держится как DAG без циклов, а дополнительные смысловые связи живут рядом:
   - *Семантические мосты:* две заметки из разных доменов указывают на одну и ту же идею.
   - Явные теговые связи можно хранить вручную в YAML.

3. **Отслеживание эволюции базы (Дрифт)**
   NOUZ хранит доменный профиль содержательных узлов и может сравнить его с заявленным знаком. Если модуль описан как один домен, а его профиль постепенно тянет в другой, сервер покажет расхождение (`core_drift`).

В зависимости от ваших задач NOUZ работает в трех режимах: от простого графа (**LUCA**) до строгой 5-уровневой иерархии (**SLOI**).

---

## Как это работает

1. Вы описываете домены в `config.yaml` — какую область покрывает каждый домен и по каким признакам текста его узнавать.
2. Сервер превращает описания в векторы-эталоны (локально, через LM Studio или Ollama).
3. Каждая новая заметка проецируется на эти оси. Знак определяется содержанием, или вами.

Здесь важно разделять два слоя. `artifact_signs` описывают форму L5-артефактов: лог, источник, гипотеза, спецификация и так далее. Эти знаки не агрегируются в доменный знак L4. Лог остается логом, источник остается источником.

`core_mix` — не сумма типов артефактов. Это доменный профиль в SQLite-индексе. L4/L3/L2 получают его из собственного текста при `recalc_signs`, а родительские узлы могут затем получить усредненный профиль дочерних содержательных узлов через `recalc_core_mix`. `core_drift` появляется, когда сохраненный доменный профиль и текущий `sign` указывают на разные ведущие домены.

**Семантические мосты** находят связи между заметками из разных доменов, когда тексты близки по смыслу. Если для обеих заметок уже есть чанки, мост дополнительно проверяется лучшей парой из них и возвращает конкретный признак. Теги остаются явной пользовательской разметкой.

---

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

```bash
pip install nouz-mcp
OBSIDIAN_ROOT=/path/to/vault nouz-mcp
```

Без `config.yaml` сервер стартует в режиме **LUCA** — граф без семантики, работает сразу.

Чтобы включить семантический режим, создайте локальный конфиг из шаблона:

```bash
cp config.template.yaml config.yaml
```

В Windows PowerShell:

```powershell
Copy-Item config.template.yaml config.yaml
```

Или из исходников:

```bash
git clone https://github.com/Semiotronika/NOUZ-MCP
cd NOUZ-MCP
pip install -r requirements.txt
cp config.template.yaml config.yaml
OBSIDIAN_ROOT=./vault python server.py
```

Подключение к Claude Desktop, Cursor, Opencode или любому MCP-клиенту:

```json
{
  "mcpServers": {
    "nouz": {
      "command": "nouz-mcp",
      "env": {
        "OBSIDIAN_ROOT": "/path/to/vault",
        "NOUZ_CONFIG": "/absolute/path/to/config.yaml",
        "EMBED_API_URL": "http://127.0.0.1:1234/v1"
      }
    }
  }
}
```

---

## Инструменты MCP

| Инструмент | Зачем |
|------------|-------|
| `suggest_metadata` | Знак, уровень, мосты, дрифт-предупреждения |
| `write_file` | Записать заметку с YAML-разметкой |
| `update_metadata` | Обновить только YAML, не меняя текст заметки |
| `read_file` | Прочитать заметку + метаданные |
| `calibrate_cores` | Обновить векторы-эталоны ядер |
| `recalc_signs` | Пересчитать знаки всех заметок |
| `recalc_core_mix` | Пересчитать доменный профиль родителей по дочерним содержательным узлам |
| `index_all` | Переиндексировать всю базу; в PRIZMA/SLOI с `with_embeddings=true` также обновляет эмбеддинги файлов/чанков |
| `embed` | Получить вектор для текста в PRIZMA/SLOI |
| `chunk_text` | Разрезать Markdown-текст на стабильные чанки в PRIZMA/SLOI |
| `chunk_file` | Разрезать тело одной заметки на стабильные чанки в PRIZMA/SLOI |
| `search_chunks` | Искать по сохранённым chunk embeddings в PRIZMA/SLOI; по умолчанию снижает анизотропию |
| `list_files` | Список с фильтрами по уровню, знаку |
| `get_children` | Пройти вниз по графу |
| `get_parents` | Пройти вверх по графу |
| `suggest_parents` | Найти родителей для сироты |
| `add_entity` | Создать сущность в один шаг (автоматический знак и иерархия, теги только явно) |
| `process_orphans` | Автозаполнение файлов без разметки |

---

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

Минимальный `config.yaml`:

```yaml
mode: prizma

etalons:
  - sign: S
    name: Systems Analysis
    text: >
      Methodology for analysing complex objects: feedback loops,
      emergent properties, self-regulation, bifurcation points.
      Cybernetics, synergetics, dissipative structures, catastrophe
      theory, autopoiesis — tools for understanding how the whole
      exceeds the sum of its parts. Not data and not code — a way
      of thinking about how parts form a whole and why systems
      behave non-linearly.
  - sign: D
    name: Data & Science
    text: >
      Physics and cosmology: from subatomic particles to the large-scale
      structure of the Universe. Lagrangians, curvature tensors, scattering
      cross-sections, quarks, bosons, fermions, plasma, vacuum fluctuations,
      cosmic microwave background, cosmological constant, decoherence.
      Pure science about the nature of matter, energy and spacetime.
  - sign: E
    name: Engineering
    text: >
      Software engineering, machine learning and infrastructure: writing
      and debugging code, deployment, containerisation, neural networks,
      inference, tokenisation, data serialisation, microservices, CI/CD,
      automated testing, refactoring, Git, Docker, Kubernetes, APIs.
      The practical discipline of building computational systems from
      architecture to production.

thresholds:
  sign_spread: 0.05
  confident_spread: 60.0
  pattern_second_sign_threshold: 30.0
  semantic_bridge_threshold: 0.55
  parent_link_threshold: 0.55

artifact_signs:
  - sign: n
    name: Note
    text: Short note, observation, fragment.
  - sign: c
    name: Concept
    text: Definition, concept, entity description.
  - sign: r
    name: Reference
    text: External source, documentation, link, citation.
  - sign: l
    name: Log
    text: Session log, chronology, dialogue record.
  - sign: u
    name: Update
    text: Update, release note, changelog entry.
  - sign: h
    name: Hypothesis
    text: Hypothesis, assumption, speculative idea.
  - sign: s
    name: Specification
    text: Technical specification, instruction, requirements.
```

После настройки запустите `calibrate_cores` — сервер создаст эталонные векторы.
Проверьте попарные косинусы: mean-centered между разными доменами должен быть
заметно ниже исходного. Если все пары примерно одинаковые — усильте различия в текстах.
Отдельную проверку эталонов можно запустить из установленного пакета:
`nouz-calc-etalons --config config.yaml`.

`etalons` — это смысловые домены, которые сравниваются через эмбеддинги.
`artifact_signs` — тип материала для артефактов L5: заметка, концепт, ссылка, лог, обновление, гипотеза или спецификация. Это эвристическая метка. Домены обычно обозначаются заглавными буквами (`S/D/E`), а типы материала — строчными (`n/c/r/l/u/h/s`); их можно заменить в конфиге на любые другие значения. При необходимости для любого типа можно добавить `keywords`: тогда сервер будет использовать ваши слова для эвристики вместо встроенного RU/EN набора.

### Реальный пример расчёта

Вот фактические результаты для эталонов S/D/E с моделью `text-embedding-granite-embedding-278m-multilingual`:

```text
=== Pairwise Cosine (raw) ===
S↔D: 0.5894    S↔E: 0.5862    D↔E: 0.6022

=== Pairwise Cosine (mean-centered) ===
S↔D: -0.5059   S↔E: -0.5117   D↔E: -0.4822
```

Отрицательные mean-centered значения здесь хороший результат: после вычитания среднего вектора домены хорошо расходятся. Smoke test эталонов текущим `nouz-calc-etalons`: S→99.6%, D→98.5%, E→98.1%. Это не оценка всей базы, а быстрая проверка, что каждый эталон после того же центрирования уверенно возвращается к своему знаку.

| Переменная | По умолчанию | Описание |
| --- | --- | --- |
| `OBSIDIAN_ROOT` | `./obsidian` | Путь к хранилищу |
| `NOUZ_CONFIG` | *(пусто)* | Абсолютный путь к `config.yaml`; если не задан, сервер ищет конфиг в текущей директории |
| `NOUZ_DATABASE_NAME` | `obsidian_kb.db` | Имя файла SQLite-кэша внутри `OBSIDIAN_ROOT`; удобно для изолированных проверок, например `obsidian_kb.public.db` |
| `NOUZ_DATABASE_PATH` | *(пусто)* | Полный путь к SQLite-кэшу; имеет приоритет над `NOUZ_DATABASE_NAME` |
| `EMBED_PROVIDER` | `openai` | `openai`, `lmstudio`, `ollama` |
| `EMBED_API_URL` | `http://127.0.0.1:1234/v1` | Эндпоинт для эмбеддингов |
| `EMBED_API_KEY` | *(пусто)* | API-ключ, если нужен |
| `EMBED_MODEL` | *(пусто)* | Имя модели |

---

## Приватность

| Компонент | Локально? |
|-----------|-----------|
| Эмбеддинги (LM Studio / Ollama) | ✅ Да |
| Ваши заметки | ✅ Да |
| Сервер NOUZ | ✅ Да |
| Контекст AI-агента (Claude, ChatGPT) | ❌ Уходит в облако |

Всё критичное остаётся на вашей машине.

---

## Разработка

```bash
git clone https://github.com/Semiotronika/NOUZ-MCP
cd NOUZ-MCP
pip install -e