Nouz

NOUZ — ナレッジベースのためのセマンティック MCP サーバー

構造は内容から生まれます。

Obsidian、Logseq、およびあらゆる Markdown ファイルのディレクトリで動作します。

NOUZ は MCP Python SDK v2 で動作します。

🇬🇧 英語版

---

Nouz が必要な理由

NOUZ は、ノートのナレッジベースと AI エージェントをつなぐレイヤーとして機能します。散在する Markdown ファイルを、あなたにもエージェントにも扱いやすいグラフに変換します。

1. 自動分類（セマンティクス） 「コア」として、ナレッジベースの基本ドメインを設定します。新しいノートを追加すると、NOUZ はテキストを読み取り、ベクトルを比較して、ドメインの印またはドメインの組み合わせを提案します。

2. ノート間のつながりを検索 サーバーは有向の構造グラフを構築します。hierarchy は循環のない DAG として維持され、追加の意味的なつながりはその隣に保持されます。

   • セマンティックブリッジ： 異なるドメインの2つのノートが、同じアイデアを指し示します。
   • 明示的なタグによるつながりは、YAML で手動管理できます。

3. ナレッジベースの変化を追跡（ドリフト） NOUZ は内容のあるノードのドメインプロファイルを保存し、それを設定された印と比較できます。モジュールが1つのドメインとして記述されていても、そのプロファイルが徐々に別のドメインへ引き寄せられている場合、サーバーは差異（core_drift）を表示します。

タスクに応じて、NOUZ はシンプルなグラフ（LUCA）から、厳格な5レベル階層（SLOI）まで、3つのモードで動作します。

---

仕組み

1. config.yaml で各ドメインがカバーする領域と、テキストを識別するための特徴を説明します。
2. サーバーはその説明を基準ベクトルに変換します（ローカル、LM Studio、または Ollama 経由）。
3. 新しいノートはそれらの軸に投影されます。印は内容、またはあなたによって決まります。

ここでは、2つのレイヤーを区別することが重要です。artifact_signs は、ログ、ソース、仮説、仕様など、L5 アーティファクトの形式を表します。これらの印は L4 のドメイン印には集約されません。ログはログのまま、ソースはソースのままです。

core_mix はアーティファクトタイプの合計ではありません。SQLite インデックスにあるドメインプロファイルです。L4/L3/L2 は recalc_signs の際に自身のテキストからこれを取得し、親ノードはその後、recalc_core_mix を通じて、内容のある子ノードの平均プロファイルを取得できます。保存されたドメインプロファイルと現在の sign が異なる主要ドメインを示すと、core_drift が発生します。

セマンティックブリッジは、テキストの意味が近い場合に、異なるドメインのノート間のつながりを見つけます。両方のノートにチャンクがある場合、チャンク同士の最良の組み合わせによってブリッジをさらに検証し、具体的な特徴を返します。タグは、ユーザーが明示的に付与するラベルとして扱われます。

---

クイックスタート

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

config.yaml がない場合、サーバーは LUCA モード（セマンティクスのないグラフ）で起動し、すぐに使えます。

セマンティックモードを有効にするには、テンプレートからローカル設定を作成します。

cp config.template.yaml config.yaml

Windows PowerShell の場合：

Copy-Item config.template.yaml config.yaml

または、ソースから実行します。

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 クライアントへの接続：

{
  "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:

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:

=== 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)	❌ Уходит в облако

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

---

Разработка

git clone https://github.com/Semiotronika/NOUZ-MCP
cd NOUZ-MCP
pip install -e .
python -m compileall -q nouz_mcp pytest_smoke.py scripts
python -m pytest -q
python test_server.py

---

Ссылки

• 🌐 semiotronika.ru
• 📦 PyPI
• 🗂️ Glama Registry
• 🐙 GitHub

MIT License © 2026 Maria Belkina

Косинусы считаются. Синтаксис меняется. Семантика остаётся.