{
  "markdown": "# NOUZ — Семантический MCP-сервер для вашей базы знаний\n\n> *Структура появляется из содержания.*\n\nРаботает с Obsidian, Logseq и любыми директориями Markdown-файлов.\n\n[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)\n[![MCP SDK v2](https://img.shields.io/badge/MCP%20SDK-v2-lightgrey.svg)](https://modelcontextprotocol.io)\n[![PyPI](https://img.shields.io/badge/pypi-nouz--mcp-orange.svg)](https://pypi.org/project/nouz-mcp/)\n\nNOUZ работает на MCP Python SDK v2.\n\n🇬🇧 [English version](README_EN.md)\n\n---\n\n## Зачем нужен Nouz\n\nNOUZ выступает прослойкой между вашей базой заметок и AI-агентом. Он помогает превратить разрозненные Markdown-файлы в граф, с которым удобно работать и вам, и агенту:\n\n1. **Автоматическая классификация (Семантика)**\n   Вы задаете \"Ядра\" — базовые домены вашей базы. Когда вы добавляете новую заметку, NOUZ читает ее текст, сравнивает векторы и предлагает доменный знак или комбинацию доменов.\n\n2. **Поиск связей между заметками**\n   Сервер строит направленный структурный граф: `hierarchy` держится как DAG без циклов, а дополнительные смысловые связи живут рядом:\n   - *Семантические мосты:* две заметки из разных доменов указывают на одну и ту же идею.\n   - Явные теговые связи можно хранить вручную в YAML.\n\n3. **Отслеживание эволюции базы (Дрифт)**\n   NOUZ хранит доменный профиль содержательных узлов и может сравнить его с заявленным знаком. Если модуль описан как один домен, а его профиль постепенно тянет в другой, сервер покажет расхождение (`core_drift`).\n\nВ зависимости от ваших задач NOUZ работает в трех режимах: от простого графа (**LUCA**) до строгой 5-уровневой иерархии (**SLOI**).\n\n---\n\n## Как это работает\n\n1. Вы описываете домены в `config.yaml` — какую область покрывает каждый домен и по каким признакам текста его узнавать.\n2. Сервер превращает описания в векторы-эталоны (локально, через LM Studio или Ollama).\n3. Каждая новая заметка проецируется на эти оси. Знак определяется содержанием, или вами.\n\nЗдесь важно разделять два слоя. `artifact_signs` описывают форму L5-артефактов: лог, источник, гипотеза, спецификация и так далее. Эти знаки не агрегируются в доменный знак L4. Лог остается логом, источник остается источником.\n\n`core_mix` — не сумма типов артефактов. Это доменный профиль в SQLite-индексе. L4/L3/L2 получают его из собственного текста при `recalc_signs`, а родительские узлы могут затем получить усредненный профиль дочерних содержательных узлов через `recalc_core_mix`. `core_drift` появляется, когда сохраненный доменный профиль и текущий `sign` указывают на разные ведущие домены.\n\n**Семантические мосты** находят связи между заметками из разных доменов, когда тексты близки по смыслу. Если для обеих заметок уже есть чанки, мост дополнительно проверяется лучшей парой из них и возвращает конкретный признак. Теги остаются явной пользовательской разметкой.\n\n---\n\n## Быстрый старт\n\n```bash\npip install nouz-mcp\nOBSIDIAN_ROOT=/path/to/vault nouz-mcp\n```\n\nБез `config.yaml` сервер стартует в режиме **LUCA** — граф без семантики, работает сразу.\n\nЧтобы включить семантический режим, создайте локальный конфиг из шаблона:\n\n```bash\ncp config.template.yaml config.yaml\n```\n\nВ Windows PowerShell:\n\n```powershell\nCopy-Item config.template.yaml config.yaml\n```\n\nИли из исходников:\n\n```bash\ngit clone https://github.com/Semiotronika/NOUZ-MCP\ncd NOUZ-MCP\npip install -r requirements.txt\ncp config.template.yaml config.yaml\nOBSIDIAN_ROOT=./vault python server.py\n```\n\nПодключение к Claude Desktop, Cursor, Opencode или любому MCP-клиенту:\n\n```json\n{\n  \"mcpServers\": {\n    \"nouz\": {\n      \"command\": \"nouz-mcp\",\n      \"env\": {\n        \"OBSIDIAN_ROOT\": \"/path/to/vault\",\n        \"NOUZ_CONFIG\": \"/absolute/path/to/config.yaml\",\n        \"EMBED_API_URL\": \"http://127.0.0.1:1234/v1\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Инструменты MCP\n\n| Инструмент | Зачем |\n|------------|-------|\n| `suggest_metadata` | Знак, уровень, мосты, дрифт-предупреждения |\n| `write_file` | Записать заметку с YAML-разметкой |\n| `update_metadata` | Обновить только YAML, не меняя текст заметки |\n| `read_file` | Прочитать заметку + метаданные |\n| `calibrate_cores` | Обновить векторы-эталоны ядер |\n| `recalc_signs` | Пересчитать знаки всех заметок |\n| `recalc_core_mix` | Пересчитать доменный профиль родителей по дочерним содержательным узлам |\n| `index_all` | Переиндексировать всю базу; в PRIZMA/SLOI с `with_embeddings=true` также обновляет эмбеддинги файлов/чанков |\n| `embed` | Получить вектор для текста в PRIZMA/SLOI |\n| `chunk_text` | Разрезать Markdown-текст на стабильные чанки в PRIZMA/SLOI |\n| `chunk_file` | Разрезать тело одной заметки на стабильные чанки в PRIZMA/SLOI |\n| `search_chunks` | Искать по сохранённым chunk embeddings в PRIZMA/SLOI; по умолчанию снижает анизотропию |\n| `list_files` | Список с фильтрами по уровню, знаку |\n| `get_children` | Пройти вниз по графу |\n| `get_parents` | Пройти вверх по графу |\n| `suggest_parents` | Найти родителей для сироты |\n| `add_entity` | Создать сущность в один шаг (автоматический знак и иерархия, теги только явно) |\n| `process_orphans` | Автозаполнение файлов без разметки |\n\n---\n\n## Конфигурация\n\nМинимальный `config.yaml`:\n\n```yaml\nmode: prizma\n\netalons:\n  - sign: S\n    name: Systems Analysis\n    text: >\n      Methodology for analysing complex objects: feedback loops,\n      emergent properties, self-regulation, bifurcation points.\n      Cybernetics, synergetics, dissipative structures, catastrophe\n      theory, autopoiesis — tools for understanding how the whole\n      exceeds the sum of its parts. Not data and not code — a way\n      of thinking about how parts form a whole and why systems\n      behave non-linearly.\n  - sign: D\n    name: Data & Science\n    text: >\n      Physics and cosmology: from subatomic particles to the large-scale\n      structure of the Universe. Lagrangians, curvature tensors, scattering\n      cross-sections, quarks, bosons, fermions, plasma, vacuum fluctuations,\n      cosmic microwave background, cosmological constant, decoherence.\n      Pure science about the nature of matter, energy and spacetime.\n  - sign: E\n    name: Engineering\n    text: >\n      Software engineering, machine learning and infrastructure: writing\n      and debugging code, deployment, containerisation, neural networks,\n      inference, tokenisation, data serialisation, microservices, CI/CD,\n      automated testing, refactoring, Git, Docker, Kubernetes, APIs.\n      The practical discipline of building computational systems from\n      architecture to production.\n\nthresholds:\n  sign_spread: 0.05\n  confident_spread: 60.0\n  pattern_second_sign_threshold: 30.0\n  semantic_bridge_threshold: 0.55\n  parent_link_threshold: 0.55\n\nartifact_signs:\n  - sign: n\n    name: Note\n    text: Short note, observation, fragment.\n  - sign: c\n    name: Concept\n    text: Definition, concept, entity description.\n  - sign: r\n    name: Reference\n    text: External source, documentation, link, citation.\n  - sign: l\n    name: Log\n    text: Session log, chronology, dialogue record.\n  - sign: u\n    name: Update\n    text: Update, release note, changelog entry.\n  - sign: h\n    name: Hypothesis\n    text: Hypothesis, assumption, speculative idea.\n  - sign: s\n    name: Specification\n    text: Technical specification, instruction, requirements.\n```\n\nПосле настройки запустите `calibrate_cores` — сервер создаст эталонные векторы.\nПроверьте попарные косинусы: mean-centered между разными доменами должен быть\nзаметно ниже исходного. Если все пары примерно одинаковые — усильте различия в текстах.\nОтдельную проверку эталонов можно запустить из установленного пакета:\n`nouz-calc-etalons --config config.yaml`.\n\n`etalons` — это смысловые домены, которые сравниваются через эмбеддинги.\n`artifact_signs` — тип материала для артефактов L5: заметка, концепт, ссылка, лог, обновление, гипотеза или спецификация. Это эвристическая метка. Домены обычно обозначаются заглавными буквами (`S/D/E`), а типы материала — строчными (`n/c/r/l/u/h/s`); их можно заменить в конфиге на любые другие значения. При необходимости для любого типа можно добавить `keywords`: тогда сервер будет использовать ваши слова для эвристики вместо встроенного RU/EN набора.\n\n### Реальный пример расчёта\n\nВот фактические результаты для эталонов S/D/E с моделью `text-embedding-granite-embedding-278m-multilingual`:\n\n```text\n=== Pairwise Cosine (raw) ===\nS↔D: 0.5894    S↔E: 0.5862    D↔E: 0.6022\n\n=== Pairwise Cosine (mean-centered) ===\nS↔D: -0.5059   S↔E: -0.5117   D↔E: -0.4822\n```\n\nОтрицательные mean-centered значения здесь хороший результат: после вычитания среднего вектора домены хорошо расходятся. Smoke test эталонов текущим `nouz-calc-etalons`: S→99.6%, D→98.5%, E→98.1%. Это не оценка всей базы, а быстрая проверка, что каждый эталон после того же центрирования уверенно возвращается к своему знаку.\n\n| Переменная | По умолчанию | Описание |\n| --- | --- | --- |\n| `OBSIDIAN_ROOT` | `./obsidian` | Путь к хранилищу |\n| `NOUZ_CONFIG` | *(пусто)* | Абсолютный путь к `config.yaml`; если не задан, сервер ищет конфиг в текущей директории |\n| `NOUZ_DATABASE_NAME` | `obsidian_kb.db` | Имя файла SQLite-кэша внутри `OBSIDIAN_ROOT`; удобно для изолированных проверок, например `obsidian_kb.public.db` |\n| `NOUZ_DATABASE_PATH` | *(пусто)* | Полный путь к SQLite-кэшу; имеет приоритет над `NOUZ_DATABASE_NAME` |\n| `EMBED_PROVIDER` | `openai` | `openai`, `lmstudio`, `ollama` |\n| `EMBED_API_URL` | `http://127.0.0.1:1234/v1` | Эндпоинт для эмбеддингов |\n| `EMBED_API_KEY` | *(пусто)* | API-ключ, если нужен |\n| `EMBED_MODEL` | *(пусто)* | Имя модели |\n\n---\n\n## Приватность\n\n| Компонент | Локально? |\n|-----------|-----------|\n| Эмбеддинги (LM Studio / Ollama) | ✅ Да |\n| Ваши заметки | ✅ Да |\n| Сервер NOUZ | ✅ Да |\n| Контекст AI-агента (Claude, ChatGPT) | ❌ Уходит в облако |\n\nВсё критичное остаётся на вашей машине.\n\n---\n\n## Разработка\n\n```bash\ngit clone https://github.com/Semiotronika/NOUZ-MCP\ncd NOUZ-MCP\npip install -e .\npython -m compileall -q nouz_mcp pytest_smoke.py scripts\npython -m pytest -q\npython test_server.py\n```\n\n---\n\n## Ссылки\n\n- 🌐 [semiotronika.ru](https://semiotronika.ru)\n- 📦 [PyPI](https://pypi.org/project/nouz-mcp/)\n- 🗂️ [Glama Registry](https://glama.ai/mcp/servers/Semiotronika/NOUZ-MCP)\n- 🐙 [GitHub](https://github.com/Semiotronika/NOUZ-MCP)\n\nMIT License © 2026 Semiotronika\n\n*Косинусы считаются. Синтаксис меняется. Семантика остаётся.*\n\n<!-- mcp-name: io.github.Semiotronika/NOUZ-MCP -->\n",
  "bytes": 10497,
  "sha": "97a7f65e14c81f6f54f1f8bb15c01fecac0b3d5bcd661fef3cbe79c4326ecc28",
  "repo_slug": "kvantra-dev/nouz-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kvantra_dev_nouz_mcp_eaef5e7d/readme"
}